Feature: Printing

[ChrisEdgington]

Integrating a Full Print System into Carbon

The Problem

Carbon has label generation (file+/ routes that produce ZPL and PDF files) and a standalone print bridge (crbnos/zpl-print — a local server that forwards ZPL to Zebra printers via ngrok). But there's no integrated print system:

• zpl-print is external — separate repo, manual ngrok setup, ZPL only (no PDF)
• No automation — posting a receipt doesn't print labels; operators download them manually
• No print management — no visibility into what printed, no retry on failure, no reprint
• No work center routing in Carbon — zpl-print maps work centers to printers in a config file, but Carbon itself has no awareness of this
• No audit trail — no record of what was printed, when, or by whom
• Hardcoded layouts — 4 fixed label sizes, no user customization

This proposal brings print management into Carbon itself, building on the pattern zpl-print established.

The Proposal

A Print Manager — a first-class module in both ERP and MES — that handles all printing through a centralized job queue, inspired by how IFS and SAP handle print output management.

How It Works

Business Event (e.g. receipt posted)
    → Print job record created (content generated and stored)
        → Delivery task sends to printer (ProxyBox)
            → Status updated (completed / failed)

Print Manager UI (ERP + MES)
    → View all print jobs and their status
    → View the generated output (ZPL or PDF)
    → Reprint to same or different printer

Key Design Decisions

1. Two separate Trigger.dev tasks — generation and delivery are decoupled

   • print-job-generate: fetches data, generates label content, stores it on the job record
   • print-job-deliver: reads stored content, sends to printer
   • This means the delivery backend (ProxyBox today) can be swapped without touching generation
   • Reprints skip generation entirely — content is already stored

2. Print Manager as a top-level module — not buried in Settings

   • Accessible in both ERP (back office) and MES (shop floor)
   • Shows all jobs with status, lets users view output, reprint, or redirect to a different printer

3. Auto-print driven by settings — configurable per business event

   • Toggles for: receipt labels, shipment labels, kanban cards, operation labels
   • Business event routes get ~10 lines each (check settings, trigger task)

4. Work center → printer routing — operators at different work centers get labels on their nearest printer, not a default printer. Routes are stored in a printerRoute table linked to work centers. Printer types correspond to labelSizes IDs (e.g., zebra2x1, zebra4x2, document) because a Zebra loaded with 2x1" labels is a different target than one loaded with 4x2" labels. This brings the work center mapping from zpl-print's config file into Carbon's database.

5. Existing label routes untouched — downloads still work exactly as before

What Changes

What	Impact
New @carbon/printing shared package	Types, service functions, validators, delivery backends — used by ERP, MES, and Trigger.dev tasks
Permission module	Add Printing to the module enum for RLS-based access control
New printerRoute database table	Maps (work center, printer type) → printer endpoint. Printer types correspond to labelSizes IDs (e.g., zebra2x1, zebra4x2, document)
New printJob database table	Stores job queue + audit trail with RLS (includes completedAt, origin column)
New Print Manager routes (ERP + MES)	Top-level /x/print-manager with app-specific UI
Two new Trigger.dev tasks	print-job-generate (with idempotency keys) + print-job-deliver
Revised printing settings page	Add auto-print toggles
Settings models update	settings.models.ts gets autoPrint validator
4 business event routes	~10 lines each (receipt, shipment, kanban, operation complete)

1 new shared package, 5 new files, 1 revised file, 9 files with small additions.

What Doesn't Change

• All existing file+/ label routes (PDF/ZPL download still works)
• No UI modifications to existing components (no print buttons scattered everywhere)
• No changes to the event system or other modules
• No new infrastructure dependencies — this uses Trigger.dev tasks, the same infrastructure Carbon already requires for notifications, MRP, accounting sync, and other async operations

Future-Proofed

• Alternative delivery backends: The print-job-deliver task is the only code aware of how content reaches a printer. Adding support for CUPS, PrintNode, direct IPP, or any other target means adding a new delivery module — generation and the Print Manager UI are untouched.
• Alternative generation backends: The print-job-generate task is the single point of content creation. Swapping in an external label API means changing one task — delivery and the Print Manager UI are untouched.
• Job cleanup: Add to existing cleanup cron task to prune old completed jobs.

---

External Dependencies

Print Server — Print Delivery

Carbon is a cloud application. It cannot talk directly to USB or network printers on a customer's LAN. A print server acts as the local relay — Carbon sends label content (ZPL or PDF) over HTTPS, and the print server forwards it to the physical printer.

The delivery interface is generic: an HTTP POST with content to a printer endpoint URL, authenticated via API key. Any print server that exposes printers as HTTP endpoints can plug in.

Reference implementation: ProxyBox Zero — a small hardware device that sits on the local network and exposes connected printers as HTTP API endpoints. Other print servers (CUPS with an HTTP wrapper, PrintNode, direct IPP bridges) could be supported as sibling delivery modules in @carbon/printing.

How it integrates:

• The print-job-deliver Trigger.dev task sends content to a print server endpoint via a simple HTTP POST
• Each printer type (label, document, shipping) has its own endpoint URL configured in settings
• Authentication via API key header
• The architecture supports multiple delivery backends as sibling modules in @carbon/printing

What operators configure: Printer endpoint URLs and an API key — all in the Printing settings page.

Label Design — Label Generation

Carbon's label generation is currently hardcoded — 4 fixed sizes, no custom layouts, no template system, no designer. Users who need a different label layout or want to add a company logo have to change source code. This is a significant gap for a manufacturing system where every customer has different labeling requirements.

The generation interface is generic: the print-job-generate task is the single point of content creation. Any label design API that accepts template ID + data and returns rendered output (PDF, ZPL, PNG) can plug in.

Reference implementation: Bindery Press — a label design and generation platform with a WYSIWYG designer, data binding, multi-format output (PDF + ZPL + PNG from one template), and broad barcode support (Code128, EAN-13, UPC-A, QR, DataMatrix). Other label design APIs with similar capabilities could be supported by swapping the generation logic in the same task.

How it integrates:

• The print-job-generate task calls the label design API with a template ID, output format, and bound data
• Users design their own labels in the external designer and configure template IDs in Carbon's settings
• Carbon automatically binds data and renders labels when business events fire
• No architectural changes to the Print Manager, delivery layer, or UI