# brook-sys/picofarm architecture

> Architecture diagram of the GitHub repository brook-sys/picofarm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brook-sys/picofarm
- Repository: https://github.com/brook-sys/picofarm

## Overview

PicoFarm is a self-hosted print-farm and order-fulfillment application. Users manage a product catalog and sales, turn order items into production tasks and print jobs, then queue work and monitor or control a printer fleet. The browser frontend talks to a Go API; business workflows use repository and storage layers backed by SQLite and disk files. Major additional capabilities include sales-channel integrations, slicer support, realtime updates, notifications, and operational reporting. Some backend wiring and unsampled pages are represented only where the README or source index supports the relationship.

Main entry points: [`web/src/api/client.ts`](https://github.com/brook-sys/picofarm/blob/main/web/src/api/client.ts) (API client), [`web/src/App.tsx`](https://github.com/brook-sys/picofarm/blob/main/web/src/App.tsx) (Web app routes), [`internal/service`](https://github.com/brook-sys/picofarm/tree/main/internal/service) (Business services), [`web/src/pages/Sales.tsx`](https://github.com/brook-sys/picofarm/blob/main/web/src/pages/Sales.tsx) (Sales and orders)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_webapp["Web app routes<br/>[App.tsx]"]
  node_salesui["Sales and orders<br/>[Sales.tsx]"]
  node_catalogui["Catalog and tasks<br/>[ProjectDetail.tsx]"]
  node_printerui["Printer and queue UI<br/>[PrintQueue.tsx]"]
  node_channelsui["Channel settings<br/>[Channels.tsx]"]
  node_filesui["File library<br/>[GCodeFiles.tsx]"]
  node_materialsui["Materials UI<br/>[Materials.tsx]"]
  node_settingsui["Settings and slicer<br/>[Settings.tsx]"]
  node_apiclient["API client<br/>[client.ts]"]
  node_realtimeui["Realtime updates<br/>[useWebSocket.ts]"]
end

subgraph group_backend["Backend workflows"]
  node_server["Go server runtime<br/>[main.go]"]
  node_router["HTTP API routes<br/>[router.go]"]
  node_services["Business services"]
  node_hub["WebSocket hub<br/>[hub.go]"]
end

subgraph group_production["Print operations"]
  node_printersvc["Printer service<br/>[printer_service.go]"]
  node_printermgr["Printer connections<br/>[manager.go]"]
  node_protocols["Printer protocols"]
end

subgraph group_persistence["Persistence"]
  node_repositories["Data repositories"]
  node_sqlite[("SQLite database<br/>[sqlite.go]")]
  node_filedata["Uploaded files<br/>[storage.go]"]
end

subgraph group_integrations["Integrations"]
  node_saleschannels["Sales channels"]
  node_slicer["External slicer<br/>[slicer.go]"]
end

node_user(("Farm operator"))
node_externalchannels(("Sales platforms"))

node_user -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_salesui
node_webapp -->|"routes to"| node_catalogui
node_webapp -->|"routes to"| node_printerui
node_webapp -->|"routes to"| node_channelsui
node_salesui -->|"requests data"| node_apiclient
node_catalogui -->|"requests data"| node_apiclient
node_printerui -->|"requests data"| node_apiclient
node_apiclient -->|"calls API"| node_router
node_server -->|"starts"| node_router
node_router -->|"dispatches to"| node_services
node_saleschannels -.->|"connects"| node_externalchannels
node_services -.->|"uses adapters"| node_saleschannels
node_services -->|"persists through"| node_repositories
node_repositories -->|"accesses"| node_sqlite
node_services -->|"stores uploads"| node_filedata
node_services -->|"includes"| node_printersvc
node_printersvc -->|"connects printers"| node_printermgr
node_printermgr -.->|"uses clients"| node_protocols
node_settingsui -.->|"configures"| node_apiclient
node_settingsui -.->|"configures"| node_slicer
node_webapp -.->|"uses updates"| node_realtimeui
node_realtimeui -->|"receives events"| node_hub
node_hub -->|"serves WebSocket"| node_router
node_filesui -.->|"requests files"| node_apiclient
node_materialsui -.->|"requests inventory"| node_apiclient
node_user -.->|"records orders"| node_salesui
node_salesui -.->|"fulfills items"| node_catalogui
node_catalogui -.->|"queues print jobs"| node_printerui

click node_webapp "https://github.com/brook-sys/picofarm/blob/main/web/src/App.tsx"
click node_salesui "https://github.com/brook-sys/picofarm/blob/main/web/src/pages/Sales.tsx"
click node_catalogui "https://github.com/brook-sys/picofarm/blob/main/web/src/pages/ProjectDetail.tsx"
click node_printerui "https://github.com/brook-sys/picofarm/blob/main/web/src/pages/PrintQueue.tsx"
click node_channelsui "https://github.com/brook-sys/picofarm/blob/main/web/src/pages/Channels.tsx"
click node_filesui "https://github.com/brook-sys/picofarm/blob/main/web/src/pages/GCodeFiles.tsx"
click node_materialsui "https://github.com/brook-sys/picofarm/blob/main/web/src/pages/Materials.tsx"
click node_settingsui "https://github.com/brook-sys/picofarm/blob/main/web/src/pages/Settings.tsx"
click node_apiclient "https://github.com/brook-sys/picofarm/blob/main/web/src/api/client.ts"
click node_realtimeui "https://github.com/brook-sys/picofarm/blob/main/web/src/hooks/useWebSocket.ts"
click node_server "https://github.com/brook-sys/picofarm/blob/main/cmd/server/main.go"
click node_router "https://github.com/brook-sys/picofarm/blob/main/internal/api/router.go"
click node_services "https://github.com/brook-sys/picofarm/tree/main/internal/service"
click node_saleschannels "https://github.com/brook-sys/picofarm/tree/main/internal/saleschannel"
click node_printersvc "https://github.com/brook-sys/picofarm/blob/main/internal/service/printer_service.go"
click node_printermgr "https://github.com/brook-sys/picofarm/blob/main/internal/printer/manager.go"
click node_protocols "https://github.com/brook-sys/picofarm/tree/main/internal/printer"
click node_slicer "https://github.com/brook-sys/picofarm/blob/main/internal/service/slicer.go"
click node_repositories "https://github.com/brook-sys/picofarm/tree/main/internal/repository"
click node_sqlite "https://github.com/brook-sys/picofarm/blob/main/internal/database/sqlite.go"
click node_filedata "https://github.com/brook-sys/picofarm/blob/main/internal/storage/storage.go"
click node_hub "https://github.com/brook-sys/picofarm/blob/main/internal/realtime/hub.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webapp,node_salesui,node_catalogui,node_printerui,node_channelsui,node_filesui,node_materialsui,node_settingsui,node_apiclient,node_realtimeui toneBlue
class node_server,node_router,node_services,node_hub toneAmber
class node_printersvc,node_printermgr,node_protocols toneMint
class node_repositories,node_sqlite,node_filedata toneRose
class node_saleschannels,node_slicer,node_user,node_externalchannels toneIndigo
```

## Components

### Web application

- [Web app routes](https://github.com/brook-sys/picofarm/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Sales and orders](https://github.com/brook-sys/picofarm/blob/main/web/src/pages/Sales.tsx): `web/src/pages/Sales.tsx`
- [Catalog and tasks](https://github.com/brook-sys/picofarm/blob/main/web/src/pages/ProjectDetail.tsx): `web/src/pages/ProjectDetail.tsx`
- [Printer and queue UI](https://github.com/brook-sys/picofarm/blob/main/web/src/pages/PrintQueue.tsx): `web/src/pages/PrintQueue.tsx`
- [Channel settings](https://github.com/brook-sys/picofarm/blob/main/web/src/pages/Channels.tsx): `web/src/pages/Channels.tsx`
- [File library](https://github.com/brook-sys/picofarm/blob/main/web/src/pages/GCodeFiles.tsx): `web/src/pages/GCodeFiles.tsx`
- [Materials UI](https://github.com/brook-sys/picofarm/blob/main/web/src/pages/Materials.tsx): `web/src/pages/Materials.tsx`
- [Settings and slicer](https://github.com/brook-sys/picofarm/blob/main/web/src/pages/Settings.tsx): `web/src/pages/Settings.tsx`
- [API client](https://github.com/brook-sys/picofarm/blob/main/web/src/api/client.ts): `web/src/api/client.ts`
- [Realtime updates](https://github.com/brook-sys/picofarm/blob/main/web/src/hooks/useWebSocket.ts): `web/src/hooks/useWebSocket.ts`

### Backend workflows

- [Go server runtime](https://github.com/brook-sys/picofarm/blob/main/cmd/server/main.go): `cmd/server/main.go`
- [HTTP API routes](https://github.com/brook-sys/picofarm/blob/main/internal/api/router.go): `internal/api/router.go`
- [Business services](https://github.com/brook-sys/picofarm/tree/main/internal/service): `internal/service`
- [WebSocket hub](https://github.com/brook-sys/picofarm/blob/main/internal/realtime/hub.go): `internal/realtime/hub.go`

### Print operations

- [Printer service](https://github.com/brook-sys/picofarm/blob/main/internal/service/printer_service.go): `internal/service/printer_service.go`
- [Printer connections](https://github.com/brook-sys/picofarm/blob/main/internal/printer/manager.go): `internal/printer/manager.go`
- [Printer protocols](https://github.com/brook-sys/picofarm/tree/main/internal/printer): `internal/printer`

### Persistence

- [Data repositories](https://github.com/brook-sys/picofarm/tree/main/internal/repository): `internal/repository`
- [SQLite database](https://github.com/brook-sys/picofarm/blob/main/internal/database/sqlite.go): `internal/database/sqlite.go`
- [Uploaded files](https://github.com/brook-sys/picofarm/blob/main/internal/storage/storage.go): `internal/storage/storage.go`

### Integrations

- [Sales channels](https://github.com/brook-sys/picofarm/tree/main/internal/saleschannel): `internal/saleschannel`
- [External slicer](https://github.com/brook-sys/picofarm/blob/main/internal/service/slicer.go): `internal/service/slicer.go`

### Other components

- **Farm operator**
- **Sales platforms**

## Connections

- Farm operator → Web app routes: uses
- Web app routes → Sales and orders: routes to (evidence: `web/src/App.tsx`)
- Web app routes → Catalog and tasks: routes to (evidence: `web/src/App.tsx`)
- Web app routes → Printer and queue UI: routes to (evidence: `web/src/App.tsx`)
- Web app routes → Channel settings: routes to (evidence: `web/src/App.tsx`)
- Sales and orders → API client: requests data
- Catalog and tasks → API client: requests data
- Printer and queue UI → API client: requests data (evidence: `web/src/api/client.ts`)
- API client → HTTP API routes: calls API
- Go server runtime → HTTP API routes: starts (evidence: `cmd/server/main.go`)
- HTTP API routes → Business services: dispatches to (evidence: `internal/api/router.go`)
- Sales channels → Sales platforms: connects
- Business services → Sales channels: uses adapters
- Business services → Data repositories: persists through (evidence: `internal/service/printer_service.go`)
- Data repositories → SQLite database: accesses
- Business services → Uploaded files: stores uploads
- Business services → Printer service: includes
- Printer service → Printer connections: connects printers (evidence: `internal/service/printer_service.go`)
- Printer connections → Printer protocols: uses clients
- Settings and slicer → API client: configures
- Settings and slicer → External slicer: configures
- Web app routes → Realtime updates: uses updates (evidence: `web/src/App.tsx`)
- Realtime updates → WebSocket hub: receives events
- WebSocket hub → HTTP API routes: serves WebSocket (evidence: `internal/api/router.go`)
- File library → API client: requests files
- Materials UI → API client: requests inventory
- Farm operator → Sales and orders: records orders
- Sales and orders → Catalog and tasks: fulfills items
- Catalog and tasks → Printer and queue UI: queues print jobs
