System architecture
Overview
posprint is a desktop application with a web-based UI (Tauri) and a Rust backend that owns parsing, rendering, file I/O, and printer communication.
┌──────────────────────────────────────────────────────────────────┐
│ Application │
├────────────────────────────┬─────────────────────────────────────┤
│ UI Layer │ Core Layer (Rust) │
│ (TypeScript / Tauri WebView) │
│ │ │
│ DocumentEditor ───────────┼──► parse_dsl() → Document AST │
│ PreviewPane ◄─────────────┼─── render_preview(ast, width) │
│ SettingsPanel │ │
│ ParameterDialog │ │
│ PrinterPicker │ │
│ │ │
│ File menu ────────────────┼──► load_pos() / save_pos() │
│ Print button ─────────────┼──► list_printers() │
│ │ print_document(ast, params, dev) │
└────────────────────────────┴─────────────────────────────────────┘
│
┌─────────────────┼─────────────────┐
▼ ▼ ▼
Preview bitmap ESC/POS bytes .pos JSON file
---
Modules (Rust crate layout)
posprint-core/ # Library — no UI, unit-testable
├── dsl/
│ ├── lexer.rs # Tokenize source
│ ├── parser.rs # Build AST
│ └── ast.rs # Document, Block, Inline, Directive nodes
├── render/
│ ├── preview.rs # Layout for UI (lines, images, barcode placeholders)
│ └── escpos.rs # AST → ESC/POS byte buffer
├── params/
│ ├── collect.rs # Find unique ${Name} tokens
│ └── substitute.rs # Apply user values before render/print
├── io/
│ └── pos_file.rs # Serde types, load/save
└── print/
├── discover.rs # Enumerate serial / USB / BT devices
├── transport.rs # Trait: write(bytes), read optional status
└── pipeline.rs # substitute → escpos → transport
posprint-app/ # Tauri binary
├── commands/ # #[tauri::command] wrappers
├── state.rs # App state (last params, recent files)
└── main.rs
Frontend (src/):
src/
├── components/
│ ├── Editor.tsx
│ ├── Preview.tsx
│ ├── Toolbar.tsx
│ ├── ParameterModal.tsx
│ └── PrinterDialog.tsx
├── hooks/
│ ├── useDocument.ts
│ └── usePreview.ts
└── lib/
└── tauri.ts # Typed invoke wrappers
---
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 desktop application with a **web-based UI** (Tauri) and a **Rust backend** that owns parsing, rendering, file I/O, and printer communication. |
| 6 | |
| 7 | ``` |
| 8 | ┌──────────────────────────────────────────────────────────────────┐ |
| 9 | │ Application │ |
| 10 | ├────────────────────────────┬─────────────────────────────────────┤ |
| 11 | │ UI Layer │ Core Layer (Rust) │ |
| 12 | │ (TypeScript / Tauri WebView) │ |
| 13 | │ │ │ |
| 14 | │ DocumentEditor ───────────┼──► parse_dsl() → Document AST │ |
| 15 | │ PreviewPane ◄─────────────┼─── render_preview(ast, width) │ |
| 16 | │ SettingsPanel │ │ |
| 17 | │ ParameterDialog │ │ |
| 18 | │ PrinterPicker │ │ |
| 19 | │ │ │ |
| 20 | │ File menu ────────────────┼──► load_pos() / save_pos() │ |
| 21 | │ Print button ─────────────┼──► list_printers() │ |
| 22 | │ │ print_document(ast, params, dev) │ |
| 23 | └────────────────────────────┴─────────────────────────────────────┘ |
| 24 | │ |
| 25 | ┌─────────────────┼─────────────────┐ |
| 26 | ▼ ▼ ▼ |
| 27 | Preview bitmap ESC/POS bytes .pos JSON file |
| 28 | ``` |
| 29 | |
| 30 | --- |
| 31 | |
| 32 | ## Modules (Rust crate layout) |
| 33 | |
| 34 | ``` |
| 35 | posprint-core/ # Library — no UI, unit-testable |
| 36 | ├── dsl/ |
| 37 | │ ├── lexer.rs # Tokenize source |
| 38 | │ ├── parser.rs # Build AST |
| 39 | │ └── ast.rs # Document, Block, Inline, Directive nodes |
| 40 | ├── render/ |
| 41 | │ ├── preview.rs # Layout for UI (lines, images, barcode placeholders) |
| 42 | │ └── escpos.rs # AST → ESC/POS byte buffer |
| 43 | ├── params/ |
| 44 | │ ├── collect.rs # Find unique ${Name} tokens |
| 45 | │ └── substitute.rs # Apply user values before render/print |
| 46 | ├── io/ |
| 47 | │ └── pos_file.rs # Serde types, load/save |
| 48 | └── print/ |
| 49 | ├── discover.rs # Enumerate serial / USB / BT devices |
| 50 | ├── transport.rs # Trait: write(bytes), read optional status |
| 51 | └── pipeline.rs # substitute → escpos → transport |
| 52 | |
| 53 | posprint-app/ # Tauri binary |
| 54 | ├── commands/ # #[tauri::command] wrappers |
| 55 | ├── state.rs # App state (last params, recent files) |
| 56 | └── main.rs |
| 57 | ``` |
| 58 | |
| 59 | Frontend (`src/`): |
| 60 | |
| 61 | ``` |
| 62 | src/ |
| 63 | ├── components/ |
| 64 | │ ├── Editor.tsx |
| 65 | │ ├── Preview.tsx |
| 66 | │ ├── Toolbar.tsx |
| 67 | │ ├── ParameterModal.tsx |
| 68 | │ └── PrinterDialog.tsx |
| 69 | ├── hooks/ |
| 70 | │ ├── useDocument.ts |
| 71 | │ └── usePreview.ts |
| 72 | └── lib/ |
| 73 | └── tauri.ts # Typed invoke wrappers |
| 74 | ``` |
| 75 | |
| 76 | --- |
| 77 | |
| 78 | ## Data flow |
| 79 | |
| 80 | ### Edit loop (live preview) |
| 81 | |
| 82 | 1. User types in editor → debounced (e.g. 150 ms) invoke `preview_document(source, settings)`. |
| 83 | 2. Core parses DSL → AST (or returns parse errors with line/col). |
| 84 | 3. Core renders preview model: text lines, image refs, barcode/QR placeholders sized to page width. |
| 85 | 4. UI displays preview scaled to panel width (auto) or fixed mm width. |
| 86 | |
| 87 | ### Save / load |
| 88 | |
| 89 | 1. **Save:** UI sends `{ metadata, body }` → `save_pos(path)` → JSON on disk. |
| 90 | 2. **Load:** `load_pos(path)` → populate editor and settings. |
| 91 | |
| 92 | |
| 93 | |
| 94 | 1. User clicks Print → `collect_parameters(ast)` → unique sorted names. |
| 95 | 2. UI shows modal; pre-fill from `last_print_params` in app state. |
| 96 | 3. On confirm → `print_document(ast, params, printer_id)`. |
| 97 | 4. Core: substitute → build ESC/POS → open transport → write bytes → cut (if configured). |
| 98 | |
| 99 | --- |
| 100 | |
| 101 | ## Key types (conceptual) |
| 102 | |
| 103 | ```rust |
| 104 | struct Document { |
| 105 | blocks: Vec<Block>, |
| 106 | } |
| 107 | |
| 108 | enum Block { |
| 109 | Paragraph { inlines: Vec<Inline>, align: Align }, |
| 110 | Heading { level: u8, text: String }, |
| 111 | Rule, |
| 112 | Image { src: String, width: ImageWidth }, // src may be ${Param} |
| 113 | Barcode { symbology: BarcodeKind, data: String, height: u8 }, |
| 114 | Qr { data: String, size: QrSize }, |
| 115 | Feed { lines: u8 }, |
| 116 | Cut, |
| 117 | } |
| 118 | |
| 119 | struct PosFile { |
| 120 | version: u32, |
| 121 | metadata: Metadata, |
| 122 | body: String, |
| 123 | } |
| 124 | |
| 125 | struct Metadata { |
| 126 | title: Option<String>, |
| 127 | page_width_mm: f32, // 58, 80, etc. |
| 128 | preview_mode: PreviewMode, // AutoScale | Fixed |
| 129 | codepage: Option<String>, |
| 130 | cut_after_print: bool, |
| 131 | } |
| 132 | |
| 133 | struct PrinterDevice { |
| 134 | id: String, // stable key for session |
| 135 | name: String, |
| 136 | transport: TransportKind, |
| 137 | // ... |
| 138 | } |
| 139 | ``` |
| 140 | |
| 141 | --- |
| 142 | |
| 143 | ## Tauri commands (IPC surface) |
| 144 | |
| 145 | | Command | Input | Output | |
| 146 | |---------|-------|--------| |
| 147 | | `parse_document` | `body: string` | `{ ast \| errors }` | |
| 148 | | `preview_document` | `body, metadata` | `PreviewModel` | |
| 149 | | `collect_parameters` | `body` | `string[]` (unique, sorted) | |
| 150 | | `save_pos` | `path, PosFile` | `Result<()>` | |
| 151 | | `load_pos` | `path` | `PosFile` | |
| 152 | | `list_printers` | — | `PrinterDevice[]` | |
| 153 | | `print_document` | `body, metadata, params, printer_id` | `Result<()>` | |
| 154 | |
| 155 | --- |
| 156 | |
| 157 | ## Preview vs print fidelity |
| 158 | |
| 159 | | Aspect | Preview | Print | |
| 160 | |--------|---------|-------| |
| 161 | | Text font | UI monospace, scaled | Printer built-in font | |
| 162 | | Line width | Computed from `page_width_mm` | ESC/POS dot width | |
| 163 | | Images | Resized bitmap in canvas | Raster ESC/POS | |
| 164 | | Barcodes | SVG/canvas placeholder | Native printer barcode commands | |
| 165 | | Alignment | CSS / canvas | ESC/POS justify commands | |
| 166 | |
| 167 | Both paths share the **same AST and substitution**; preview and print each have their own backend (preview renderer vs `escpos` encoder). |
| 168 | |
| 169 | --- |
| 170 | |
| 171 | ## State persistence |
| 172 | |
| 173 | | Data | Storage | |
| 174 | |------|---------| |
| 175 | | Recent files | App config (Tauri `app_data_dir`) | |
| 176 | | Last parameter values | `params.json` keyed by template path or global | |
| 177 | | Window layout | Optional, Tauri store | |
| 178 | | Selected printer | Per-machine preference | |
| 179 | |
| 180 | --- |
| 181 | |
| 182 | ## Testing strategy |
| 183 | |
| 184 | | Layer | Approach | |
| 185 | |-------|----------| |
| 186 | | DSL parser | Unit tests + snapshot fixtures | |
| 187 | | Parameter collect/substitute | Unit tests | |
| 188 | | ESC/POS encoder | Byte snapshot tests | |
| 189 | | Preview layout | Snapshot images (optional) | |
| 190 | | Printer I/O | Manual hardware matrix; mock `Transport` trait in CI | |
| 191 | | UI | Component tests; E2E with mocked Tauri commands | |
| 192 | |
| 193 | --- |
| 194 | |
| 195 | ## Build and release |
| 196 | |
| 197 | - **CI:** GitHub Actions — `cargo test`, `cargo clippy`, frontend lint, build Windows + Linux artifacts. |
| 198 | - **Artifacts:** `.msi` or `.exe` (Windows), `.deb` / AppImage (Linux). |
| 199 | - **Versioning:** Semver; `.pos` `version` field for file format migrations. |
| 200 | |
| 201 | See [PRINTING.md](PRINTING.md) for the device layer and [DSL-SPEC.md](DSL-SPEC.md) for language details. |