From d8c0991dc6e91bad35e441351db2e54929afd3d8 Mon Sep 17 00:00:00 2001 From: Otto the Minion Date: Thu, 21 May 2026 13:29:24 -0400 Subject: [PATCH] docs: add comprehensive project context file (CONTEXT.md) for agent reference --- docs/CONTEXT.md | 214 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 214 insertions(+) create mode 100644 docs/CONTEXT.md diff --git a/docs/CONTEXT.md b/docs/CONTEXT.md new file mode 100644 index 0000000..eabc5e4 --- /dev/null +++ b/docs/CONTEXT.md @@ -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 +```