# System architecture ## Overview posprint is a **single Rust binary** using **egui** (eframe). No separate frontend language. ``` ┌─────────────────────────────────────────┐ │ posprint (Rust + egui) │ │ - Editor / Preview / Help tabs │ │ - DSL parse → AST │ │ - Preview layout + ESC/POS encode │ │ - USB-serial printer discovery/print │ │ - `.pos` serde │ └─────────────────────────────────────────┘ ``` ### Crate layout ``` src/ ├── main.rs, app.rs # egui application ├── lib.rs ├── dsl/ # Parser and AST ├── params.rs # Parameter collect/substitute ├── escpos.rs # ESC/POS byte encoder ├── preview.rs # Preview model ├── io/ # .pos file format └── print/ # USB-serial discovery and I/O ``` --- ## Data flow ### Edit loop (live preview) 1. User types in editor → debounced (e.g. 150 ms) invoke `preview_document(source, settings)`. 2. Core parses DSL → AST (or returns parse errors with line/col). 3. Core renders preview model: text lines, image refs, barcode/QR placeholders sized to page width. 4. UI displays preview scaled to panel width (auto) or fixed mm width. ### Save / load 1. **Save:** UI sends `{ metadata, body }` → `save_pos(path)` → JSON on disk. 2. **Load:** `load_pos(path)` → populate editor and settings. ### Print 1. User clicks Print → `collect_parameters(ast)` → unique sorted names. 2. UI shows modal; pre-fill from `last_print_params` in app state. 3. On confirm → `print_document(ast, params, printer_id)`. 4. Core: substitute → build ESC/POS → open transport → write bytes → cut (if configured). --- ## Key types (conceptual) ```rust struct Document { blocks: Vec, } enum Block { Paragraph { inlines: Vec, align: Align }, Heading { level: u8, text: String }, Rule, Image { src: String, width: ImageWidth }, // src may be ${Param} Barcode { symbology: BarcodeKind, data: String, height: u8 }, Qr { data: String, size: QrSize }, Feed { lines: u8 }, Cut, } struct PosFile { version: u32, metadata: Metadata, body: String, } struct Metadata { title: Option, page_width_mm: f32, // 58, 80, etc. preview_mode: PreviewMode, // AutoScale | Fixed codepage: Option, cut_after_print: bool, } struct PrinterDevice { id: String, // stable key for session name: String, transport: TransportKind, // ... } ``` --- ## Tauri commands (IPC surface) | Command | Input | Output | |---------|-------|--------| | `parse_document` | `body: string` | `{ ast \| errors }` | | `preview_document` | `body, metadata` | `PreviewModel` | | `collect_parameters` | `body` | `string[]` (unique, sorted) | | `save_pos` | `path, PosFile` | `Result<()>` | | `load_pos` | `path` | `PosFile` | | `list_printers` | — | `PrinterDevice[]` | | `print_document` | `body, metadata, params, printer_id` | `Result<()>` | --- ## Preview vs print fidelity | Aspect | Preview | Print | |--------|---------|-------| | Text font | UI monospace, scaled | Printer built-in font | | Line width | Computed from `page_width_mm` | ESC/POS dot width | | Images | Resized bitmap in canvas | Raster ESC/POS | | Barcodes | SVG/canvas placeholder | Native printer barcode commands | | Alignment | CSS / canvas | ESC/POS justify commands | Both paths share the **same AST and substitution**; preview and print each have their own backend (preview renderer vs `escpos` encoder). --- ## State persistence | Data | Storage | |------|---------| | Recent files | App config (Tauri `app_data_dir`) | | Last parameter values | `params.json` keyed by template path or global | | Window layout | Optional, Tauri store | | Selected printer | Per-machine preference | --- ## Testing strategy | Layer | Approach | |-------|----------| | DSL parser | Unit tests + snapshot fixtures | | Parameter collect/substitute | Unit tests | | ESC/POS encoder | Byte snapshot tests | | Preview layout | Snapshot images (optional) | | Printer I/O | Manual hardware matrix; mock `Transport` trait in CI | | UI | Component tests; E2E with mocked Tauri commands | --- ## Build and release - **CI:** GitHub Actions — `cargo test`, `cargo clippy`, frontend lint, build Windows + Linux artifacts. - **Artifacts:** `.msi` or `.exe` (Windows), `.deb` / AppImage (Linux). - **Versioning:** Semver; `.pos` `version` field for file format migrations. See [PRINTING.md](PRINTING.md) for the device layer and [DSL-SPEC.md](DSL-SPEC.md) for language details.