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.
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)
struct Document {
blocks: Vec<Block>,
}
enum Block {
Paragraph { inlines: Vec<Inline>, 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<String>,
page_width_mm: f32, // 58, 80, etc.
preview_mode: PreviewMode, // AutoScale | Fixed
codepage: Option<String>,
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 | |
|---|---|---|
| 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:
.msior.exe(Windows),.deb/ AppImage (Linux). - Versioning: Semver;
.posversionfield for file format migrations.
See PRINTING.md for the device layer and DSL-SPEC.md for language details.
Source
| 1 | # System architecture |
| 2 | |
| 3 | ## Overview |
| 4 | |
| 5 | posprint is a **single Rust binary** using **egui** (eframe). No separate frontend language. |
| 6 | |
| 7 | ``` |
| 8 | ┌─────────────────────────────────────────┐ |
| 9 | │ posprint (Rust + egui) │ |
| 10 | │ - Editor / Preview / Help tabs │ |
| 11 | │ - DSL parse → AST │ |
| 12 | │ - Preview layout + ESC/POS encode │ |
| 13 | │ - USB-serial printer discovery/print │ |
| 14 | │ - `.pos` serde │ |
| 15 | └─────────────────────────────────────────┘ |
| 16 | ``` |
| 17 | |
| 18 | ### Crate layout |
| 19 | |
| 20 | ``` |
| 21 | src/ |
| 22 | ├── main.rs, app.rs # egui application |
| 23 | ├── lib.rs |
| 24 | ├── dsl/ # Parser and AST |
| 25 | ├── params.rs # Parameter collect/substitute |
| 26 | ├── escpos.rs # ESC/POS byte encoder |
| 27 | ├── preview.rs # Preview model |
| 28 | ├── io/ # .pos file format |
| 29 | └── print/ # USB-serial discovery and I/O |
| 30 | ``` |
| 31 | |
| 32 | --- |
| 33 | |
| 34 | ## Data flow |
| 35 | |
| 36 | ### Edit loop (live preview) |
| 37 | |
| 38 | 1. User types in editor → debounced (e.g. 150 ms) invoke `preview_document(source, settings)`. |
| 39 | 2. Core parses DSL → AST (or returns parse errors with line/col). |
| 40 | 3. Core renders preview model: text lines, image refs, barcode/QR placeholders sized to page width. |
| 41 | 4. UI displays preview scaled to panel width (auto) or fixed mm width. |
| 42 | |
| 43 | ### Save / load |
| 44 | |
| 45 | 1. **Save:** UI sends `{ metadata, body }` → `save_pos(path)` → JSON on disk. |
| 46 | 2. **Load:** `load_pos(path)` → populate editor and settings. |
| 47 | |
| 48 | |
| 49 | |
| 50 | 1. User clicks Print → `collect_parameters(ast)` → unique sorted names. |
| 51 | 2. UI shows modal; pre-fill from `last_print_params` in app state. |
| 52 | 3. On confirm → `print_document(ast, params, printer_id)`. |
| 53 | 4. Core: substitute → build ESC/POS → open transport → write bytes → cut (if configured). |
| 54 | |
| 55 | --- |
| 56 | |
| 57 | ## Key types (conceptual) |
| 58 | |
| 59 | ```rust |
| 60 | struct Document { |
| 61 | blocks: Vec<Block>, |
| 62 | } |
| 63 | |
| 64 | enum Block { |
| 65 | Paragraph { inlines: Vec<Inline>, align: Align }, |
| 66 | Heading { level: u8, text: String }, |
| 67 | Rule, |
| 68 | Image { src: String, width: ImageWidth }, // src may be ${Param} |
| 69 | Barcode { symbology: BarcodeKind, data: String, height: u8 }, |
| 70 | Qr { data: String, size: QrSize }, |
| 71 | Feed { lines: u8 }, |
| 72 | Cut, |
| 73 | } |
| 74 | |
| 75 | struct PosFile { |
| 76 | version: u32, |
| 77 | metadata: Metadata, |
| 78 | body: String, |
| 79 | } |
| 80 | |
| 81 | struct Metadata { |
| 82 | title: Option<String>, |
| 83 | page_width_mm: f32, // 58, 80, etc. |
| 84 | preview_mode: PreviewMode, // AutoScale | Fixed |
| 85 | codepage: Option<String>, |
| 86 | cut_after_print: bool, |
| 87 | } |
| 88 | |
| 89 | struct PrinterDevice { |
| 90 | id: String, // stable key for session |
| 91 | name: String, |
| 92 | transport: TransportKind, |
| 93 | // ... |
| 94 | } |
| 95 | ``` |
| 96 | |
| 97 | --- |
| 98 | |
| 99 | ## Tauri commands (IPC surface) |
| 100 | |
| 101 | | Command | Input | Output | |
| 102 | |---------|-------|--------| |
| 103 | | `parse_document` | `body: string` | `{ ast \| errors }` | |
| 104 | | `preview_document` | `body, metadata` | `PreviewModel` | |
| 105 | | `collect_parameters` | `body` | `string[]` (unique, sorted) | |
| 106 | | `save_pos` | `path, PosFile` | `Result<()>` | |
| 107 | | `load_pos` | `path` | `PosFile` | |
| 108 | | `list_printers` | — | `PrinterDevice[]` | |
| 109 | | `print_document` | `body, metadata, params, printer_id` | `Result<()>` | |
| 110 | |
| 111 | --- |
| 112 | |
| 113 | ## Preview vs print fidelity |
| 114 | |
| 115 | | Aspect | Preview | Print | |
| 116 | |--------|---------|-------| |
| 117 | | Text font | UI monospace, scaled | Printer built-in font | |
| 118 | | Line width | Computed from `page_width_mm` | ESC/POS dot width | |
| 119 | | Images | Resized bitmap in canvas | Raster ESC/POS | |
| 120 | | Barcodes | SVG/canvas placeholder | Native printer barcode commands | |
| 121 | | Alignment | CSS / canvas | ESC/POS justify commands | |
| 122 | |
| 123 | Both paths share the **same AST and substitution**; preview and print each have their own backend (preview renderer vs `escpos` encoder). |
| 124 | |
| 125 | --- |
| 126 | |
| 127 | ## State persistence |
| 128 | |
| 129 | | Data | Storage | |
| 130 | |------|---------| |
| 131 | | Recent files | App config (Tauri `app_data_dir`) | |
| 132 | | Last parameter values | `params.json` keyed by template path or global | |
| 133 | | Window layout | Optional, Tauri store | |
| 134 | | Selected printer | Per-machine preference | |
| 135 | |
| 136 | --- |
| 137 | |
| 138 | ## Testing strategy |
| 139 | |
| 140 | | Layer | Approach | |
| 141 | |-------|----------| |
| 142 | | DSL parser | Unit tests + snapshot fixtures | |
| 143 | | Parameter collect/substitute | Unit tests | |
| 144 | | ESC/POS encoder | Byte snapshot tests | |
| 145 | | Preview layout | Snapshot images (optional) | |
| 146 | | Printer I/O | Manual hardware matrix; mock `Transport` trait in CI | |
| 147 | | UI | Component tests; E2E with mocked Tauri commands | |
| 148 | |
| 149 | --- |
| 150 | |
| 151 | ## Build and release |
| 152 | |
| 153 | - **CI:** GitHub Actions — `cargo test`, `cargo clippy`, frontend lint, build Windows + Linux artifacts. |
| 154 | - **Artifacts:** `.msi` or `.exe` (Windows), `.deb` / AppImage (Linux). |
| 155 | - **Versioning:** Semver; `.pos` `version` field for file format migrations. |
| 156 | |
| 157 | See [PRINTING.md](PRINTING.md) for the device layer and [DSL-SPEC.md](DSL-SPEC.md) for language details. |