CubeCraft-Creations/Extrudex
11
0
Fork 0
Code Issues Pull Requests 8 Actions Packages Projects Releases Wiki Activity
Files
368d07017424d48c696c6627c402cd196e996f08
Extrudex/docs/CONTEXT.md
T
Otto d8c0991dc6
Dev Build / build-test (push) Failing after 1s
Details
docs: add comprehensive project context file (CONTEXT.md) for agent reference
2026-05-21 13:29:24 -04:00

9.8 KiB
Raw Blame History

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

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

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 View Git Blame Copy Permalink