Extrudex/docs/CONTEXT.md

# 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
```