Chapter 2. Architecture & Deployment Forms

2.1 Overall architecture

┌──────────────┐  HTTP/WS   ┌────────────────────────────────┐
│ Browser /    │ ─────────▶ │  WxPrint service core          │
│ backend      │            │  ├ REST: /api/print /preview… │
└──────────────┘            │  ├ WS: /ws (direct + events)  │
                            │  ├ Job queue: queued→rendering→…│
                            │  ├ Loaders: templates & data   │
                            │  │   (id / URL / inline)       │
                            │  └ Render thread (dedicated)   │
                            │      ├ Pipeline A: overlay     │
                            │      └ Pipeline B: HTML/Twig    │
                            │        (both emit vector PDF)   │
                            └──────────────┬─────────────────┘
                                           │ Output layer
                            ├ Linux/macOS: CUPS (vector PDF)
                            └ Windows: GDI (rasterized at DPI)

Key points:

• Rendering runs on a dedicated thread, decoupled from the API layer; printer output (lp subprocess / GDI calls) runs on blocking threads and never slows down service responses.
• Two render pipelines, one PDF exit: preview, print, and PDF export behave identically — what you see is what prints.
• Templates and data can both be fetched at run time (URL loaders); business data that is only known at print time never needs to be staged in advance.

2.2 The three deployment forms

2.2.1 Resident tray (desktop default)

wxprint-tray lives in the system tray and brings up the embedded service core on start (the same HTTP/WS routes — no separate server process needed). Suited to office machines: autostart, tray menu management, a settings dialog, and the automatically popping preview window. See Chapter 9.

2.2.2 Headless service (server / print-dedicated machine)

wxprint-server is a standalone process for unattended operation: registered as a system service (see Chapter 3), combined with a LAN bind (0.0.0.0) it turns the machine into a print server shared by the whole network. Previews fall back to the server-side web component (/preview/{job_id}).

2.2.3 Designer (template authoring)

wxprint-designer is the template authoring tool; it embeds the service core for preview and test printing (zero configuration). See Chapter 8.

2.3 Render pipelines

2.3.1 Pipeline A: overlay

A JSON template describes the page (physical mm width/height) and absolutely positioned elements. Render flow: data binding (variables

• filters) → text layout (CJK-safe line breaking, automatic shrinking for overlong content) → vector drawing (embedded glyph runs, vector barcode/QR paths, table grids, charts) → PDF page. The background image is not printed by default (overlay semantics).

2.3.2 Pipeline B: HTML + Twig

HTML templates are written in Twig syntax; data injection and layout both happen server-side: loaded data → Twig renders pure static HTML+CSS → the built-in engine lays it out → slices it into pages by page height (forced page-break class .wxprint-page-break and orphan-avoidance class .wxprint-avoid-break supported) → vector PDF. No JavaScript is ever executed inside templates.

2.3.3 Batch and copies

Passing an array as data (or {"records": [...]}) makes a batch job: each record renders one page (or several for multi-page templates), and all pages are combined into one multi-page PDF and one print job that feeds paper continuously. copies_per_record controls per-record copies (triplicate forms), copies repeats the whole batch, and collate controls page order (record×copy×batch, or copy-major).

2.4 Job lifecycle

queued → rendering → printing → done
                      ├→ failed (render/print error, with code and message)
                      └→ cancelled (rendering: immediate; printing: stops remaining pages)

• Events: WS subscribers receive accepted / job (state changes + batch progress page_done/total_pages) / printer (printer state changes) / done / error in real time; REST users poll GET /api/jobs/{id} on demand.
• Preview jobs (preview: true / WS type:"preview") reach done right after rendering; the PDF is kept server-side for the preview window / web component, then committed via POST /api/jobs/{id}/print or downloaded via GET /api/jobs/{id}/pdf.
• One automatic retry on failure; render/print timeout guards are configurable.

2.5 Output layer

Platform	Path	Notes
Linux / macOS	CUPS (lp)	Vector PDF delivered directly — best text quality; -o media=Custom.<w>x<h>mm supports continuous custom paper
Windows	winspool GDI	PDF rasterized at the printer’s DPI (600 default), output page by page; custom paper via DEVMODE

• The PDF page equals the physical paper size, 1:1 with no scaling — the premise of overlay precision.
• Printer enumeration and state: CUPS lpstat (Linux/macOS) / winspool EnumPrinters (Windows); states include ready, offline, and out-of-paper.
• Per-printer calibration data is applied uniformly before rendering (see Section 7.10).

2.6 Data directory

~/.wxprint/ (%USERPROFILE%\.wxprint\ on Windows; under the system account profile in service mode):

Path	Contents
config.json	Persisted configuration (written by the tray settings dialog)
templates/<id>/	Registered templates (template.json + assets)
data/	Local data files (loadJSON path is restricted here by default)
spool/	Print intermediates (rendered PDFs staged for the print queue)
calibration/<printer>.json	Per-printer overlay calibration