Architecture

PrintStudio is a Turborepo monorepo. All packages share a single bun.lock and are built with Bun 1.3. The repository root workspace includes apps/* and packages/*.

Monorepo Structure

printstudio/
├── apps/
│   ├── print-ops-api/     # Hono REST API — 100+ endpoints, port 8787
│   ├── web/               # Astro 6 storefront + operator dashboard, port 4321
│   ├── plant-agent/       # LAN-side machine control agent, port 8788
│   ├── mobile/            # Flutter/Dart operator app
│   └── docs/              # This Starlight documentation site, port 4322
├── packages/
│   ├── core/              # All business logic
│   ├── domain/            # 408 Zod schemas + SKU/machine catalogs
│   ├── integrations/      # 14 external adapter implementations
│   └── test-suite/        # End-to-end test coverage
├── monitoring/
│   ├── prometheus/        # Scrape config
│   └── grafana/           # Provisioned dashboards
├── n8n/workflows/         # 10 importable workflow JSON files
├── scripts/               # start-dev.sh, start-ecosystem.sh, seed.ts
├── docker-compose.yml     # Core: Postgres, Redis, API, agent, web
└── docker-compose.ecosystem.yml  # Adds n8n, FDM Monster, Obico, Grafana

Package Responsibilities

`packages/core`

All business logic lives here. Nothing else in the monorepo writes its own business rules.

Module	Responsibility
`auth/`	Web Crypto SHA-256 sessions, API keys, RBAC (customer / operator / admin)
`state-machine/`	49 typed transitions across 8 job states
`queues/`	BullMQ — 6 queues: validation, slicing, routing, printing, post-process, shipping
`pricing/`	base + material + print_time × demand × quality multipliers, rush, batch discounts
`inventory/`	Filament/resin/laser stock tracking; auto-blocks jobs on insufficient stock
`orchestrator/`	AutoPilot — monitors fleet, auto-routes, retries failures, batches jobs
`notifications/`	Multi-provider email (Resend + SMTP), OpenClaw webhooks
`payments/`	Stripe checkout session + webhook handling
`analytics/`	Job throughput, printer utilisation, material waste, revenue
`metrics/`	Prometheus metrics export
`discovery/`	mDNS-style LAN printer discovery
`db/`	Drizzle ORM schemas, migrations, seed data
`setup/`	Environment generator for the Setup Wizard

`packages/domain`

408 Zod schemas defining every data shape in the system: SKUs, orders, jobs, printers, materials, customers. The schemas are the canonical source of truth — both the API and the frontend import from here.

The package also contains the SKU catalog and machine capability registry.

`packages/integrations`

Adapters for 14 external systems:

Adapter	Protocol
Bambu Lab printers	MQTT + LAN API
Moonraker / Klipper	REST (port 7125)
OctoPrint	REST
OrcaSlicer	CLI subprocess
n8n	REST webhooks
FDM Monster	REST
Obico (AI failure detection)	REST
InvenTree	REST
Stripe	REST + webhooks
Resend (email)	REST
SMTP (email)	SMTP
OpenClaw	REST
Home Assistant	REST
Shipping carriers	REST

`apps/print-ops-api`

Hono REST API built with Bun. Mounts routes for every domain entity. Exposes:

OpenAPI spec at /openapi.json
Scalar interactive docs at /docs
All business operations at /api/*

`apps/web`

Astro 6 application with SSR. Serves both the customer-facing storefront (product configurator, checkout) and the operator dashboard (job board, analytics, printer management).

`apps/plant-agent`

LAN-side agent that runs on the same network as printers. Handles direct machine communication for printers that don’t expose a public API. Provides a local REST API consumed by print-ops-api.

Data Flow

Customer visits storefront
        │
        ▼
Configurator (packages/domain schemas)
        │  selects SKU, options, quantity
        ▼
Pricing Engine (packages/core/pricing)
        │  computes line-item costs
        ▼
Stripe Checkout (packages/core/payments)
        │  payment confirmed
        ▼
Order Created → Jobs Created (1 job per line item)
        │
        ▼
Validation Queue (BullMQ)
        │  checks inventory, validates parameters
        ▼
Slicing Queue
        │  OrcaSlicer CLI generates G-code
        ▼
Routing Queue
        │  AutoPilot selects optimal printer
        ▼
Printing Queue → Printer Adapter (Bambu/Moonraker/OctoPrint)
        │  monitors progress
        ▼
Post-Process Queue
        │  cooling, support removal, finishing
        ▼
Ready → Shipping (carrier API)
        │
        ▼
Customer notified (email + OpenClaw)

Technology Decisions

Hono — ultra-fast web framework that runs identically on Bun, Node, Cloudflare Workers, and Deno. Zero-dependency, tiny bundle, first-class TypeScript.

Drizzle ORM — type-safe SQL that generates migrations and keeps schema in TypeScript. No query builder magic — you write SQL-like expressions, Drizzle typechecks them.

BullMQ — Redis-backed job queue with priorities, retries, concurrency limits, and job events. Each state machine transition is a BullMQ job, making the system resumable across restarts.

Bun — runtime + package manager. Faster installs, faster tests, native TypeScript execution. All scripts use bun directly.

Astro — zero-JS-by-default frontend framework. The operator dashboard uses Astro islands for interactive components (job board, charts) while static pages ship no JavaScript.

Turborepo — parallel task execution across packages with intelligent caching. bun run build builds all packages in dependency order.