Merge branch 'dev' into agent/dex/CUB-10-imoonrakerclient-interface-dtos
This commit is contained in:
220
README.md
220
README.md
@@ -0,0 +1,220 @@
|
|||||||
|
# Extrudex
|
||||||
|
|
||||||
|
> Filament inventory and print tracking system for CubeCraft Creations.
|
||||||
|
|
||||||
|
Extrudex replaces Spoolman with a fully custom solution built for Joshua's 7-printer fleet. It tracks spool stock, per-print material consumption, and cost-of-goods — with a touch-optimized kiosk interface on a Raspberry Pi 5.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
|
||||||
|
| Layer | Technology |
|
||||||
|
|---|---|
|
||||||
|
| Backend | ASP.NET Core Web API (.NET 8) |
|
||||||
|
| Database | PostgreSQL (snake_case via EF Core) |
|
||||||
|
| ORM | Entity Framework Core |
|
||||||
|
| Real-time | SignalR (`PrinterHub`) |
|
||||||
|
| Printer integration | Moonraker REST/WebSocket (Elegoo) · MQTTnet + TLS (Bambu Lab) |
|
||||||
|
| Frontend | Angular 17+, Angular Material |
|
||||||
|
| Deployment | Docker · Docker Compose |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
Extrudex/
|
||||||
|
├── backend/
|
||||||
|
│ ├── Domain/
|
||||||
|
│ │ ├── Base/ # BaseEntity, AuditableEntity
|
||||||
|
│ │ ├── Entities/ # Spool, Printer, PrintJob, FilamentUsage,
|
||||||
|
│ │ │ # AmsUnit, AmsSlot, MaterialBase,
|
||||||
|
│ │ │ # MaterialFinish, MaterialModifier
|
||||||
|
│ │ ├── Enums/ # ConnectionType, DataSource, JobStatus,
|
||||||
|
│ │ │ # PrinterStatus, PrinterType, QrResourceType
|
||||||
|
│ │ └── Interfaces/ # ICostPerPrintService, IFilamentUsageSyncService,
|
||||||
|
│ │ # IMoonrakerClient, IQrCodeService
|
||||||
|
│ ├── Infrastructure/
|
||||||
|
│ │ ├── Configuration/ # FilamentUsageSyncOptions
|
||||||
|
│ │ ├── Data/
|
||||||
|
│ │ │ ├── Configurations/ # EF Core fluent configs (snake_case)
|
||||||
|
│ │ │ ├── Migrations/ # EF migrations
|
||||||
|
│ │ │ ├── Seed/ # SeedData.cs
|
||||||
|
│ │ │ └── ExtrudexDbContext.cs
|
||||||
|
│ │ └── Services/ # CostPerPrintService, FilamentUsageSyncService,
|
||||||
|
│ │ # MoonrakerClient, QrCodeService
|
||||||
|
│ └── API/
|
||||||
|
│ ├── Controllers/ # Filaments, Spools, Printers, PrintJobs,
|
||||||
|
│ │ # MaterialBases, MaterialFinishes,
|
||||||
|
│ │ # MaterialModifiers, MaterialLookups,
|
||||||
|
│ │ # CostAnalysis, QR
|
||||||
|
│ ├── DTOs/ # Request/response shapes per domain
|
||||||
|
│ ├── Filters/ # FluentValidationFilter
|
||||||
|
│ ├── Hubs/ # PrinterHub, IPrinterClient
|
||||||
|
│ ├── Jobs/ # FilamentUsageSyncJob (background)
|
||||||
|
│ ├── Validators/ # FluentValidation validators
|
||||||
|
│ ├── Program.cs
|
||||||
|
│ └── appsettings.json
|
||||||
|
├── frontend/
|
||||||
|
│ └── src/app/
|
||||||
|
│ ├── components/ # DashboardSummary, FilamentFilter, FilamentTable
|
||||||
|
│ ├── models/ # Filament, Agent model types
|
||||||
|
│ └── app.routes.ts
|
||||||
|
├── design/ # UX specs and mockups (kiosk + mobile)
|
||||||
|
├── docker-compose.dev.yml
|
||||||
|
├── deploy.sh
|
||||||
|
└── README.md
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Domain Model
|
||||||
|
|
||||||
|
### Materials (normalized taxonomy)
|
||||||
|
|
||||||
|
| Entity | Description |
|
||||||
|
|---|---|
|
||||||
|
| `MaterialBase` | The base material type — PLA, PETG, ABS, ASA, TPU, etc. |
|
||||||
|
| `MaterialFinish` | Required. Surface finish — Basic (default), Matte, Silk, Sparkle, etc. |
|
||||||
|
| `MaterialModifier` | Optional. Composite fill — Carbon Fiber, Glass Fiber, Wood, etc. |
|
||||||
|
|
||||||
|
**Rules:**
|
||||||
|
- `MaterialFinish` is required — every spool must have one. Default is `"Basic"`.
|
||||||
|
- `MaterialModifier` is optional — plain PLA has no modifier.
|
||||||
|
|
||||||
|
### Consumption calculation
|
||||||
|
|
||||||
|
```
|
||||||
|
grams_used = mm_extruded × filament_cross_section_area × material_density
|
||||||
|
```
|
||||||
|
|
||||||
|
Grams are always derived, never assumed from printer telemetry directly.
|
||||||
|
|
||||||
|
### Printers
|
||||||
|
|
||||||
|
| Type | Integration |
|
||||||
|
|---|---|
|
||||||
|
| Bambu Lab (×5) | MQTTnet with TLS |
|
||||||
|
| Elegoo Centauri Carbon | Moonraker REST + WebSocket |
|
||||||
|
| Elegoo Saturn (resin ×2) | Manual / future |
|
||||||
|
|
||||||
|
AMS units and slots are modelled as `AmsUnit` → `AmsSlot[]` → `Spool`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Key Design Decisions
|
||||||
|
|
||||||
|
1. **Spoolman rejected** — Full custom system for data model control and workflow flexibility.
|
||||||
|
2. **`"Basic"` not `"Standard"`** — Default `MaterialFinish` value is `Basic`.
|
||||||
|
3. **`MaterialFinish` is required** — No null/optional finish state allowed.
|
||||||
|
4. **`MaterialModifier` is optional** — Not every spool has a modifier.
|
||||||
|
5. **Derived consumption** — Grams calculated from mm × density, never assumed.
|
||||||
|
6. **Push over poll** — SignalR and MQTT preferred over periodic polling.
|
||||||
|
7. **Snake_case PostgreSQL** — All database identifiers follow this convention via EF Core.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Getting Started
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
|
||||||
|
- .NET 8 SDK
|
||||||
|
- Node.js 20+
|
||||||
|
- Docker + Docker Compose
|
||||||
|
- PostgreSQL (or use the dev compose stack)
|
||||||
|
|
||||||
|
### Backend
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd backend
|
||||||
|
|
||||||
|
# Restore and build
|
||||||
|
dotnet restore
|
||||||
|
dotnet build
|
||||||
|
|
||||||
|
# Apply migrations
|
||||||
|
dotnet ef database update
|
||||||
|
|
||||||
|
# Run API (dev)
|
||||||
|
dotnet run --project API
|
||||||
|
```
|
||||||
|
|
||||||
|
API runs at `http://localhost:5000` · Swagger at `http://localhost:5000/swagger`
|
||||||
|
|
||||||
|
### Frontend
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd frontend
|
||||||
|
npm install
|
||||||
|
ng serve
|
||||||
|
```
|
||||||
|
|
||||||
|
Frontend runs at `http://localhost:4200`
|
||||||
|
|
||||||
|
### Docker (dev stack)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker-compose -f docker-compose.dev.yml up
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
`backend/appsettings.json` — override in `appsettings.Development.json` or environment variables:
|
||||||
|
|
||||||
|
| Key | Default | Description |
|
||||||
|
|---|---|---|
|
||||||
|
| `ConnectionStrings:ExtrudexDb` | `Host=localhost;...` | PostgreSQL connection string |
|
||||||
|
| `FilamentUsageSync:PollingInterval` | `00:05:00` | Sync job interval |
|
||||||
|
| `FilamentUsageSync:RequestTimeout` | `00:00:30` | Moonraker request timeout |
|
||||||
|
| `FilamentUsageSync:Enabled` | `true` | Enable/disable background sync |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Real-Time Events
|
||||||
|
|
||||||
|
SignalR hub endpoint: `/hubs/printer`
|
||||||
|
|
||||||
|
Clients receive `PrinterHub` events for live printer status, job progress, and spool consumption updates.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## API Overview
|
||||||
|
|
||||||
|
| Route prefix | Resource |
|
||||||
|
|---|---|
|
||||||
|
| `/api/filaments` | Filament catalog |
|
||||||
|
| `/api/spools` | Spool inventory |
|
||||||
|
| `/api/printers` | Printer registry |
|
||||||
|
| `/api/print-jobs` | Print job tracking |
|
||||||
|
| `/api/material-bases` | Material base types |
|
||||||
|
| `/api/material-finishes` | Material finishes |
|
||||||
|
| `/api/material-modifiers` | Material modifiers |
|
||||||
|
| `/api/material-lookups` | Combined material lookup |
|
||||||
|
| `/api/cost-analysis` | Cost-per-print and COGS |
|
||||||
|
| `/api/qr` | QR code generation |
|
||||||
|
|
||||||
|
Full schema available at `/swagger` when running in dev.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## CI
|
||||||
|
|
||||||
|
Gitea Actions pipeline (`.gitea/workflows/dev.yml`) runs on every push to `dev`:
|
||||||
|
|
||||||
|
- `dotnet build`
|
||||||
|
- Frontend `ng build`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Branch & PR Rules
|
||||||
|
|
||||||
|
- All feature branches target `dev` — **never `main`**
|
||||||
|
- Branch naming: `agent/<agent>/CUB-N-short-description`
|
||||||
|
- PR titles: `CUB-N: short description`
|
||||||
|
- PRs require Otto review before Joshua merges
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Built by CubeCraft Creations · Orchestrated by Otto*
|
||||||
|
|||||||
Reference in New Issue
Block a user