215 lines
9.8 KiB
Markdown
215 lines
9.8 KiB
Markdown
# 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
|
||
```
|