# STLP Shop Manager (farmd) — design overview

Status: DRAFT for founder review (#855). Working title farmd; product name
STLP Shop Manager. License: proprietary SLP pending decision.

## 1. Goal

Run the Starting Line Productions shop as a production system: Etsy orders
flow through Dolibarr into managed print / laser / CNC / reflow / cut /
sew / embroider jobs on the shop floor, with completion flowing back.
One dashboard, Cloudron-deployable, SSO via the platform OIDC provider,
single Go binary. Shop-time booking integrates with **ThymeSlot** (the
Cloudron booking app already in use).

## 2. Managed device classes

| Class | Devices | Adapter | Control level |
|---|---|---|---|
| FDM printers | Klipper/Moonraker, OctoPrint, Bambu | moonraker / octoprint / bambu | full (status, files, jobs, temps) |
| **Reflow oven** | Whizoo controller | reflow | profile library + run logging (v1); serial/MQTT start+monitor (v2) |
| **Laser (CR-10 conversion)** | GRBL | grbl-laser | full (power/speed presets, job send) |
| **CNC (CR-10 conversion)** | GRBL | grbl-cnc | full (feeds/speeds/tools, job send) |
| **Glowforge laser ×2** | Glowforge cloud service | glowforge (unofficial API) | job push + status poll; cloud-tethered, community API |
| **Chinese CO2 laser** | DSP (Ruida/TopWisdom) or GRBL | dsp / grbl (survey first) | job send + status; DSP protocol is reverse-engineered territory |
| **Silhouette Cameo ×2** | Silhouette graphtec protocol | cameo (Linux `silhouette` tool lineage) | cut job send; one device reserved for PCB stencils (pairs with #859 pipeline) |
| **Embroidery machines** | USB-direct (no network) | embroidery (file prep only) | pattern export (.pes/.dst via Ink/Stitch + libembroidery) + job tracking |
| **Sewing machines** | manual | manual (tracking only) | job/time tracking against ThymeSlot bookings |

Design rule: devices without network control get the **manual-device class**
— job tracking, time logging against ThymeSlot bookings, and file prep —
instead of pretending to direct control.

## 3. ThymeSlot booking integration

Shop time is booked in **ThymeSlot** (Cloudron app, already in use; upstream
POOL_SIZE request pending in #739). farmd integrates rather than replaces:

- device reservation view: farmd pulls bookings (ThymeSlot API/export) so the
  dashboard shows booked slots per device alongside live job state;
- gate rule (configurable): device jobs require an active/covering booking for
  the member, or warn-only mode;
- usage writeback: actual run time logged per job feeds billing/reports.

## 4. System context

```mermaid
flowchart LR
    E[Etsy orders] --> D[Dolibarr ERP/MRP]
    D -- REST: orders + fulfillment --> F[farmd]
    O[Operator] -- OIDC SSO --> F
    B2[ThymeSlot bookings] -- API/sync --> F
    F -- Moonraker WS --> K[FDM printers]
    F -- OctoPrint REST --> OP[FDM printers]
    F -- MQTT/FTP --> B[Bambu]
    F -- serial/bridge --> R[Whizoo reflow oven]
    F -- GRBL serial --> L[CR-10 laser]
    F -- GRBL serial --> C[CR-10 CNC]
    F -- unofficial cloud API --> G[Glowforge x2]
    F -- DSP/GRBL survey --> Z[Chinese CO2 laser]
    F -- cameo tool --> CM[Cameo x2: stencil + general]
    F -- file prep + tracking --> EM[Embroidery + sewing]
    F -- alerts --> N[ntfy]
    F -- G-code/artifacts --> S[(farm storage)]
```

## 5. Components

- **core** (Go): job queue + state machine (per device class), scheduler
  (capabilities: material, build volume, bed, laser wattage, oven profile,
  hoop/needle for embroidery), retry/reprint rules, batch groups (Etsy
  orders = batches).
- **adapters**: moonraker (WS), octoprint (REST+WS), bambu (MQTT/FTP),
  grbl (serial; laser+cnc profiles), reflow (profile mgmt v1, control v2),
  glowforge (unofficial cloud API, poll-based), cameo (cut jobs), manual
  (tracking-only class).
- **profiles**: reflow curves (per paste), laser material presets (per
  machine), CNC tool libraries, embroidery hoop/thread presets — all
  versioned; runs record the profile version used.
- **web** (embedded html/template + htmx, no Node): farm dashboard, device
  cards, job board, batch view, profile editors (incl. reflow curve editor),
  booking calendar view, history.
- **dolibarr-connector**: confirmed orders -> job specs; fulfillment
  writeback; idempotent.
- **authn**: Cloudron OIDC; roles admin/operator/viewer; API tokens for
  machine access.

## 6. Job lifecycle

```mermaid
stateDiagram-v2
    [*] --> Queued: order line / manual
    Queued --> Prep: slicing / CAM / profile / pattern
    Prep --> Ready: artifacts + booking check
    Ready --> Running: device free (+ booking if gated)
    Running --> Post: job complete
    Post --> Done: QA pass
    Post --> Reprint: QA fail
    Running --> Failed: error / material out
    Failed --> Queued: auto-requeue (n retries)
    Done --> [*]: Dolibarr fulfillment writeback
```

## 7. Phasing

- **MVP-1**: dashboard + FDM adapters (Moonraker/OctoPrint) + manual queue +
  OIDC + ntfy alerts + Cloudron package.
- **MVP-2**: GRBL adapter (CR-10 laser/CNC) + Silhouette cameo (stencil +
  general) + profile libraries + Dolibarr connector + ThymeSlot booking
  view.
- **MVP-3**: reflow profile library + run logging + Whizoo bridge, Glowforge
  unofficial-API adapter, Chinese laser DSP survey, embroidery/sewing
  manual-device tracking, batch automation, QA checklists, Prometheus.

## 8. Cloudron packaging

manifestVersion 2: httpPort 3000, localstorage (sqlite + artifacts), OIDC
addon, healthcheck /healthz, multi-user via platform groups. Serial devices
reach farmd over TCP serial bridges (ser2net) — Cloudron apps have no serial
access by design.