Compare commits

..

1 Commits

Author SHA1 Message Date
Otto d8c0991dc6 docs: add comprehensive project context file (CONTEXT.md) for agent reference
Dev Build / build-test (push) Failing after 1s
2026-05-21 13:29:24 -04:00
8 changed files with 231 additions and 249 deletions
+8 -11
View File
@@ -1,37 +1,34 @@
#!/bin/bash
set -e
echo "🔧 Deploying Extrudex (Go + React) on Raspberry Pi..."
echo "🔧 Deploying Extrudex Docker runtime..."
# Check if Docker Compose is available
if ! docker compose version &>/dev/null && ! command -v docker-compose &>/dev/null; then
if ! command -v docker-compose &> /dev/null && ! docker compose version &> /dev/null; then
echo "❌ Docker Compose is not installed"
exit 1
fi
COMPOSE_CMD="docker compose"
if command -v docker-compose &>/dev/null; then
if command -v docker-compose &> /dev/null; then
COMPOSE_CMD="docker-compose"
fi
echo "📦 Building and starting Go backend + React frontend + PostgreSQL..."
echo "📦 Building and starting services..."
$COMPOSE_CMD -f docker-compose.dev.yml up -d --build
echo "⏳ Waiting for services to become healthy..."
sleep 10
sleep 15
echo "✅ Deployment complete!"
echo ""
echo "Services running:"
echo " • PostgreSQL: localhost:5433"
echo " • Extrudex API (Go): http://localhost:5080"
echo " • Extrudex Web (React): http://localhost:5081"
echo ""
echo "Barcode scanner: HID keyboard input — focus any text field to start scanning."
echo "Kiosk mode: Chromium auto-starts on boot via systemd (extrudex-kiosk.service)."
echo " • Extrudex API: http://localhost:5080"
echo " • Extrudex Web: http://localhost:5081"
echo ""
echo "To view logs:"
echo " $COMPOSE_CMD -f docker-compose.dev.yml logs -f"
echo ""
echo "To stop:"
echo " $COMPOSE_CMD -f docker-compose.dev.yml down"
echo " $COMPOSE_CMD -f docker-compose.dev.yml down"
+8 -5
View File
@@ -28,10 +28,13 @@ services:
ports:
- "5080:8080"
environment:
- DATABASE_URL=postgres://extrudex:changeme@extrudex-db:5432/extrudex?sslmode=disable
- PORT=8080
- CORS_ORIGIN=*
- LOG_LEVEL=info
- ASPNETCORE_ENVIRONMENT=Development
- ASPNETCORE_URLS=http://+:8080
- EXTRUDEX_DB_HOST=extrudex-db
- EXTRUDEX_DB_PORT=5432
- EXTRUDEX_DB_NAME=extrudex
- EXTRUDEX_DB_USER=extrudex
- EXTRUDEX_DB_PASSWORD=changeme
depends_on:
extrudex-db:
condition: service_healthy
@@ -41,7 +44,7 @@ services:
interval: 30s
timeout: 10s
retries: 3
start_period: 15s
start_period: 40s
networks:
- extrudex-network
+214
View File
@@ -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
```
-168
View File
@@ -1,168 +0,0 @@
# Pi 5 Kiosk Setup — Extrudex (Go + React)
## Prerequisites
- Raspberry Pi 5 (4 GB or 8 GB)
- MicroSD card (32 GB minimum, Class 10+)
- HDMI touchscreen display
- USB barcode scanner (HID keyboard mode)
- Power supply (27W USB-C recommended)
## One-Line Setup
```bash
# 1. Install Raspberry Pi OS (64-bit, Desktop)
# 2. Enable SSH and VNC
# 3. Run the automated bootstrap
curl -sSL https://raw.githubusercontent.com/CubeCraft-Creations/Extrudex/dev/scripts/pi-bootstrap.sh | bash
```
Or follow the manual steps below.
## Manual Setup
### 1. Install Docker
```bash
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker pi
```
Log out and back in for group changes to take effect.
### 2. Clone and deploy
```bash
cd /home/pi
git clone https://code.cubecraftcreations.com/CubeCraft-Creations/Extrudex.git
cd Extrudex
git checkout dev
# Run the deploy script
chmod +x deploy.sh
./deploy.sh
```
### 3. Verify services
```bash
docker compose -f docker-compose.dev.yml ps
# All three services should be "Up"
```
Check the health endpoint:
```bash
curl http://localhost:5080/health
# Expected: {"status":"ok","db_connected":true,"timestamp":"..."}
```
### 4. Configure kiosk auto-start
```bash
# Enable the Docker stack service (starts on boot)
sudo cp systemd/extrudex.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable extrudex.service
# Enable the kiosk service (starts Chromium after Docker stack)
sudo cp systemd/extrudex-kiosk.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable extrudex-kiosk.service
```
### 5. Configure display server
For Pi 5, Raspberry Pi OS uses Wayland by default. If you encounter
X11-specific issues, switch to X11 in raspi-config (Advanced Options →
Resolution → X11).
The kiosk service supports both Wayland and X11 display servers.
### 6. Touchscreen calibration (if needed)
```bash
# Install calibration tools
sudo apt install -y xinput-calibrator
# Run calibration, note the device ID and parameters
xinput_calibrator
```
Add the calibration to `~/.config/labwc/labwc.conf` or `/etc/X11/xorg.conf.d/`
as appropriate for your display server.
## USB Barcode Scanner
The USB barcode scanner works as a HID keyboard device — it types scanned
codes followed by an Enter keypress. No driver configuration is needed.
On the React frontend, the search input auto-focuses on page load and
will capture barcode input immediately. After a touch on another element,
tap the search field again to re-focus.
## Auto-Refresh on Wake
The React app polls the SSE endpoint every 30 seconds for real-time
updates. When the Pi wakes from sleep, the next poll will immediately
sync the UI.
The kiosk service has `Restart=always` and `RestartSec=10`, so Chromium
will restart within 10 seconds of any crash or power cycle.
## Touch Gestures
Chromium is launched with `--touch-events=enabled` and `--enable-pinch`
for native touch gesture support:
- **Tap** — click/submit
- **Two-finger scroll** — page scrolling
- **Pinch** — zoom (disabled in kiosk mode by default; enable if needed)
## Troubleshooting
### Services not starting
```bash
sudo systemctl status extrudex
sudo systemctl status extrudex-kiosk
docker compose -f docker-compose.dev.yml logs
```
### Kiosk shows blank page
- Ensure Docker stack is running: `docker compose ps`
- Check nginx is serving the React build: `curl http://localhost:5081`
- Check Chromium logs: `journalctl -u extrudex-kiosk -n 50`
### Barcode not working
- Verify scanner is in HID keyboard mode (most USB scanners default to this)
- Open a text field and scan — you should see digits appear
- Check with `dmesg | grep -i usb` for device enumeration
### PostgreSQL connection refused
```bash
docker compose -f docker-compose.dev.yml restart extrudex-db
# Wait 15 seconds, then check health
curl http://localhost:5080/health
```
## Architecture
```
┌──────────────────────────────────────────────┐
│ Pi 5 (Raspberry Pi OS 64-bit) │
│ │
│ ┌─────────────┐ ┌──────────┐ ┌─────────┐ │
│ │ Chromium │ │ Nginx │ │ Go │ │
│ │ Kiosk │→│ (React) │→│ API │ │
│ │ :5081 │ │ :5080 │ │ :8080 │ │
│ └─────────────┘ └──────────┘ └────┬────┘ │
│ │ │
│ ┌────────▼────┐ │
│ │ PostgreSQL │ │
│ │ :5432 │ │
│ └─────────────┘ │
│ │
│ ┌──────────┐ │
│ │ USB │ │
│ │ Scanner │ → HID keyboard → Browser │
│ └──────────┘ │
└──────────────────────────────────────────────┘
```
+1 -1
View File
@@ -10,7 +10,7 @@ server {
}
location /api/ {
proxy_pass http://extrudex-api:8080/api/;
proxy_pass http://backend:8080/api/;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
-36
View File
@@ -1,36 +0,0 @@
[Unit]
Description=Extrudex Kiosk (Chromium, Go + React frontend)
After=network-online.target extrudex.service
Requires=extrudex.service
[Service]
Type=simple
User=pi
Group=pi
Environment=DISPLAY=:0
Environment=XAUTHORITY=/home/pi/.Xauthority
WorkingDirectory=/home/pi
ExecStart=/usr/bin/chromium-browser \
--no-first-run \
--no-default-browser-check \
--autoplay-policy=no-user-gesture-required \
--disable-infobars \
--disable-window-activation \
--disable-full-screen-modal \
--kiosk http://localhost:5081 \
--disable-features=TranslateUI \
--touch-events=enabled \
--enable-pinch
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=10
# Touchscreen / kiosk
Environment=QT_QPA_PLATFORM=wayland
Environment=QT_WAYLAND_SHELL_INTEGRATION=wayland
[Install]
WantedBy=multi-user.target
-12
View File
@@ -1,12 +0,0 @@
[Unit]
Description=Extrudex Kiosk Session (user-level, seat %i)
After=graphical-session.target
[Service]
Type=simple
Environment=DISPLAY=:0
ExecStart=/bin/true
Restart=on-failure
[Install]
WantedBy=graphical-session.target
-16
View File
@@ -1,16 +0,0 @@
[Unit]
Description=Extrudex Docker Compose Stack (Go + React)
After=network-online.target docker.service
Requires=docker.service
[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/home/pi/extrudex
ExecStart=/usr/bin/docker compose -f docker-compose.dev.yml up -d
ExecStop=/usr/bin/docker compose -f docker-compose.dev.yml down
TimeoutStartSec=120
TimeoutStopSec=120
[Install]
WantedBy=multi-user.target