docs: add comprehensive project context file (CONTEXT.md) for agent reference
Dev Build / build-test (push) Failing after 1s
Dev Build / build-test (push) Failing after 1s
This commit is contained in:
+214
@@ -0,0 +1,214 @@
|
|||||||
|
# Extrudex — Project Context
|
||||||
|
|
||||||
|
> **Last updated:** 2026-05-21
|
||||||
|
> **Repo:** `CubeCraft-Creations/Extrudex` | **Host:** `code.cubecraftcreations.com`
|
||||||
|
> **Local clone:** `/mnt/ai-storage/projects/Extrudex` | **Default branch:** `dev`
|
||||||
|
> **Discord:** `DISCORD_DEV_EXTRUDEX_CHANNEL_ID`
|
||||||
|
> **Linear Epic:** [CUB-110](https://linear.app/cubecraft-creations/issue/CUB-110)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Custom filament inventory and print tracking system for CubeCraft Creations. Tracks spool consumption, material costs, and per-print COGS across a fleet of 6 FDM printers (5 Bambu Lab + 1 Elegoo Centauri Carbon) + resin printers. Kiosk interface on Raspberry Pi 5 with USB barcode scanner.
|
||||||
|
|
||||||
|
**Active refactor in progress:** .NET → Go + React (CUB-110 epic).
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
|
||||||
|
| Layer | Technology | Notes |
|
||||||
|
|-------|-----------|-------|
|
||||||
|
| Backend (legacy) | ASP.NET Core 9 + EF Core | Being replaced by Go |
|
||||||
|
| Backend (new) | Go 1.24+ | Chi router, pgx (PostgreSQL), gorilla/websocket, paho.mqtt.golang |
|
||||||
|
| Frontend (legacy) | Angular 17+ | Being replaced by React |
|
||||||
|
| Frontend (new) | React 18 + TypeScript + Tailwind CSS | Vite |
|
||||||
|
| Database | PostgreSQL 16+ | snake_case naming |
|
||||||
|
| Real-time | SSE (Server-Sent Events) | Replaces SignalR |
|
||||||
|
| Printer integrations | Moonraker REST + WebSocket, MQTT TLS | Elegoo/Klipper + Bambu Lab |
|
||||||
|
| CI/CD | Gitea Actions | `.gitea/workflows/dev.yml` |
|
||||||
|
| Deployment | Docker/Compose, Pi 5 kiosk | |
|
||||||
|
|
||||||
|
## Key Design Decisions
|
||||||
|
|
||||||
|
1. **Custom system over Spoolman** — Full control over data model and integrations
|
||||||
|
2. **MaterialFinish required** on every spool; default is "Basic"
|
||||||
|
3. **MaterialModifier is optional**
|
||||||
|
4. **Grams derived from:** `mm_extruded × filament_cross_section_area × material_density`
|
||||||
|
5. **Push over poll** — SSE + MQTT preferred; Moonraker polling is fallback
|
||||||
|
6. **Snake_case** for all PostgreSQL identifiers
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
Extrudex/
|
||||||
|
├── backend/ # Original .NET backend (being replaced)
|
||||||
|
│ ├── API/Controllers/ # Filaments, Spools, PrintJobs, Printers, Materials, QR, UsageLogs, Cost
|
||||||
|
│ ├── API/DTOs/ # DTOs per domain
|
||||||
|
│ ├── API/Validators/ # FluentValidation rules
|
||||||
|
│ ├── API/Hubs/ # SignalR PrinterHub
|
||||||
|
│ ├── API/Jobs/ # Background sync jobs
|
||||||
|
│ ├── Domain/Entities/ # EF Core entities (Printer, Spool, PrintJob, MaterialBase, etc.)
|
||||||
|
│ ├── Domain/Enums/ # ConnectionType, DataSource, JobStatus, PrinterStatus, QrResourceType
|
||||||
|
│ ├── Domain/Interfaces/ # Service interfaces
|
||||||
|
│ ├── Infrastructure/Data/ # EF DbContext, Configurations, Migrations, SeedData
|
||||||
|
│ ├── Infrastructure/Services/ # MoonrakerClient, CostPerPrint, UsageLog, FilamentUsage, QR
|
||||||
|
│ └── Program.cs # ASP.NET entry point
|
||||||
|
├── cmd/server/main.go # Go entrypoint (new), worker discovery, graceful shutdown
|
||||||
|
├── internal/ # Go backend (new)
|
||||||
|
│ ├── config/config.go # Env vars
|
||||||
|
│ ├── db/db.go # PostgreSQL connection pool (pgx)
|
||||||
|
│ ├── models/models.go # Go domain structs
|
||||||
|
│ ├── router/router.go # Chi HTTP routes
|
||||||
|
│ ├── sse/broadcaster.go # SSE broadcaster
|
||||||
|
│ ├── sse/events.go # SSE event types
|
||||||
|
│ ├── sse/handler.go # SSE HTTP handler
|
||||||
|
│ ├── handlers/ # API handlers (filament, health, material, print_job, printer, usage_log)
|
||||||
|
│ ├── repositories/ # DB access layer
|
||||||
|
│ └── services/ # Business logic + validation
|
||||||
|
├── migrations/ # Go-migrate SQL migrations
|
||||||
|
│ ├── 000001_initial_schema.up.sql
|
||||||
|
│ ├── 000001_initial_schema.down.sql
|
||||||
|
│ ├── 000002_seed_data.up.sql
|
||||||
|
│ └── 000002_seed_data.down.sql
|
||||||
|
├── frontend/ # React frontend (new)
|
||||||
|
│ ├── src/
|
||||||
|
│ │ ├── App.tsx
|
||||||
|
│ │ ├── main.tsx
|
||||||
|
│ │ ├── components/ # ColorSwatch, LoadingSpinner, RecentPrints, SummaryCard
|
||||||
|
│ │ ├── pages/
|
||||||
|
│ │ │ ├── Dashboard.tsx # Main dashboard with summary cards + recent prints
|
||||||
|
│ │ │ └── InventoryPage.tsx # Filament inventory list (table + filters)
|
||||||
|
│ │ ├── services/
|
||||||
|
│ │ │ ├── api.ts # Axios client
|
||||||
|
│ │ │ └── filamentService.ts
|
||||||
|
│ │ ├── stores/ # State stores (WIP)
|
||||||
|
│ │ ├── types/
|
||||||
|
│ │ │ ├── filament.ts
|
||||||
|
│ │ │ └── index.ts
|
||||||
|
│ │ └── hooks/
|
||||||
|
│ ├── Dockerfile + nginx.conf
|
||||||
|
│ └── vite.config.ts, tailwind.config.js
|
||||||
|
├── design/ # UX/design specs + mockup images
|
||||||
|
│ ├── homepage-spec.md
|
||||||
|
│ ├── 01-filament-inventory-list.md
|
||||||
|
│ ├── 02-spool-detail-view.md
|
||||||
|
│ ├── 03-smart-intake-workflow.md
|
||||||
|
│ ├── smart-intake-identify-spec.md
|
||||||
|
│ └── *.jpg / *.png # Mockup images (kiosk + mobile)
|
||||||
|
├── docker-compose.dev.yml
|
||||||
|
└── deploy.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
## Database Schema (PostgreSQL — .NET EF Core Migrations)
|
||||||
|
|
||||||
|
Core entities managed by EF Core with full configurations:
|
||||||
|
- **Printers** — id, name, type (BambuLab/Moonraker), connection_type, status, ip_address, mac_address, ams_count
|
||||||
|
- **AmsUnit / AmsSlot** — Bambu Lab AMS tray tracking
|
||||||
|
- **Spools** — filament inventory with material, color, weight, location, QR support
|
||||||
|
- **MaterialBase / MaterialFinish / MaterialModifier** — material taxonomy
|
||||||
|
- **PrintJobs** — job tracking with status, cost, filament consumption
|
||||||
|
- **UsageLogs** — per-printer filament consumption records
|
||||||
|
- **FilamentUsage** — aggregated per-spool consumption tracking
|
||||||
|
- **FilamentUsageSyncJob** — background Moonraker polling
|
||||||
|
- **MoonrakerPrinterSyncJob** — background printer status sync
|
||||||
|
|
||||||
|
## API Endpoints (.NET)
|
||||||
|
|
||||||
|
| Method | Endpoint | Description |
|
||||||
|
|--------|----------|-------------|
|
||||||
|
| GET | /api/filaments | List filaments (paginated, filterable) |
|
||||||
|
| POST | /api/filaments | Create filament |
|
||||||
|
| GET | /api/filaments/{id} | Get filament detail |
|
||||||
|
| PUT | /api/filaments/{id} | Update filament |
|
||||||
|
| DELETE | /api/filaments/{id} | Delete filament |
|
||||||
|
| GET | /api/spools | List spools |
|
||||||
|
| POST | /api/spools | Create spool |
|
||||||
|
| GET | /api/spools/{id} | Get spool detail |
|
||||||
|
| PUT | /api/spools/{id} | Update spool |
|
||||||
|
| DELETE | /api/spools/{id} | Delete spool |
|
||||||
|
| GET | /api/print-jobs | List print jobs |
|
||||||
|
| POST | /api/print-jobs | Create print job |
|
||||||
|
| GET | /api/print-jobs/{id} | Get print job detail |
|
||||||
|
| GET | /api/printers | List printers |
|
||||||
|
| POST | /api/printers | Register printer |
|
||||||
|
| GET | /api/printers/{id} | Get printer detail |
|
||||||
|
| GET | /api/printers/{id}/costs | Per-print cost summary |
|
||||||
|
| GET | /api/printers/{id}/usage | Filament usage history |
|
||||||
|
| GET | /api/materials/bases | List material bases |
|
||||||
|
| POST | /api/materials/bases | Create material base |
|
||||||
|
| GET | /api/materials/finishes | List material finishes |
|
||||||
|
| POST | /api/materials/finishes | Create material finish |
|
||||||
|
| GET | /api/materials/modifiers | List material modifiers |
|
||||||
|
| POST | /api/materials/modifiers | Create modifier |
|
||||||
|
| GET | /api/materials/lookups | Unified material lookup |
|
||||||
|
| GET | /api/qr/resolve/{code} | QR code resolve |
|
||||||
|
| GET | /api/usage-logs | List usage logs |
|
||||||
|
| POST | /api/usage-logs | Create usage log |
|
||||||
|
|
||||||
|
## CUB-110 Epic Progress (Go + React Rewrite)
|
||||||
|
|
||||||
|
| Sub-task | Title | Status | Agent |
|
||||||
|
|----------|-------|--------|-------|
|
||||||
|
| CUB-111 | Design PostgreSQL schema | Done | Hex |
|
||||||
|
| CUB-112 | Scaffold Go backend | Done | Dex |
|
||||||
|
| CUB-113 | Core CRUD API endpoints | Done | Dex |
|
||||||
|
| CUB-116 | Scaffold React frontend | In Review | Rex |
|
||||||
|
| CUB-117 | Moonraker + MQTT integrations | In Progress | Dex |
|
||||||
|
| CUB-118 | (deprecated → CUB-135 + CUB-136) | — | — |
|
||||||
|
| CUB-130 | Add/Edit Filament form | In Review | Rex |
|
||||||
|
| CUB-131 | Filament Detail page | In Review | Rex |
|
||||||
|
| CUB-132 | Filament Inventory list | Done | Rex |
|
||||||
|
| CUB-133 | Dashboard summary cards | In Review | Rex |
|
||||||
|
| CUB-134 | Printers list page | Todo | Rex |
|
||||||
|
| CUB-135 | Subscribe to SSE in React | In Review | Rex |
|
||||||
|
| CUB-136 | Add SSE endpoint in Go | In Review | Dex |
|
||||||
|
| CUB-128 | Settings page | Todo | — |
|
||||||
|
| CUB-129 | Print Jobs list page | Todo | — |
|
||||||
|
| CUB-114 | Pi 5 kiosk deployment | Todo | — |
|
||||||
|
|
||||||
|
## Active Branches
|
||||||
|
|
||||||
|
| Branch | Agent | Issue | Status |
|
||||||
|
|--------|-------|-------|--------|
|
||||||
|
| `agent/dex/CUB-117-moonraker-mqtt-go` | Dex | CUB-117 | Local commit ready |
|
||||||
|
| `agent/dex/CUB-136-sse-endpoint` | Dex | CUB-136 | PR open |
|
||||||
|
| `agent/rex/CUB-130-filament-form` | Rex | CUB-130 | PR open |
|
||||||
|
| `agent/rex/CUB-131-filament-detail` | Rex | CUB-131 | PR open |
|
||||||
|
| `agent/rex/CUB-133-dashboard-cards` | Rex | CUB-133 | PR open |
|
||||||
|
| `agent/rex/CUB-135-sse-subscribe` | Rex | CUB-135 | PR open |
|
||||||
|
|
||||||
|
## Known Limitations
|
||||||
|
|
||||||
|
- Go rewrite is in progress — backend `internal/` is new Go code, but legacy .NET code still serves endpoints
|
||||||
|
- Kiosk deployment not finalized (CUB-114)
|
||||||
|
- Smart intake workflow is designed but not implemented
|
||||||
|
- MQTT Bambu Lab integration is partially complete (CUB-117)
|
||||||
|
|
||||||
|
## Default Agent Assignments
|
||||||
|
|
||||||
|
| Area | Agent | Notes |
|
||||||
|
|------|-------|-------|
|
||||||
|
| Backend (Go API, Moonraker, MQTT) | Dex | gitea-dex MCP |
|
||||||
|
| Database (PostgreSQL schema, migrations) | Hex | gitea-hex MCP |
|
||||||
|
| Frontend (React, Tailwind) | Rex | gitea-rex MCP |
|
||||||
|
| Design (wireframes, UX) | Sketch | |
|
||||||
|
|
||||||
|
## Getting Started
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /mnt/ai-storage/projects/Extrudex
|
||||||
|
git checkout dev
|
||||||
|
git pull origin dev
|
||||||
|
|
||||||
|
# Legacy .NET backend
|
||||||
|
cd backend && dotnet run
|
||||||
|
|
||||||
|
# New Go backend
|
||||||
|
go run cmd/server/main.go
|
||||||
|
|
||||||
|
# React frontend
|
||||||
|
cd frontend && npm install && npm run dev
|
||||||
|
|
||||||
|
# Docker
|
||||||
|
docker compose -f docker-compose.dev.yml up --build
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user