System architecture
Overview
posprint is a single Rust binary using egui (eframe). No separate frontend language, no WebView, no IPC layer.
┌─────────────────────────────────────────┐
│ posprint (Rust + egui) │
│ - Editor / Preview / Help tabs │
│ - DSL parse → AST │
│ - Preview layout + in-tree ESC/POS │
│ - USB-serial printer discovery/print │
│ - `.pos` JSON load/save (serde) │
└─────────────────────────────────────────┘
Source layout
src/
├── main.rs # eframe entry point
├── app.rs # egui UI (editor, preview, help, print dialog)
├── lib.rs # crate root; exports + HELP_MARKDOWN
├── dsl/ # Parser and AST (mod.rs, parser.rs)
├── params.rs # Parameter collect/substitute
├── escpos.rs # ESC/POS byte encoder (in-tree)
├── preview.rs # Preview model for UI canvas
├── io/mod.rs # .pos file format (PosFile, PosMetadata)
└── print/mod.rs # USB-serial discovery, SerialTransport, MockTransport
External dependencies (minimal)
| Crate | Role |
|---|---|
eframe / egui | Native UI |
serde / serde_json | .pos file format |
serialport | USB-serial enumeration and I/O |
image | Decode/resize images for @image raster print |
rfd | Native open/save file dialogs |
ESC/POS command generation is not delegated to a third-party crate.
---
UI structure
| Tab / area | Module | Description |
|---|---|---|
| Editor | app.rs | Multiline TextEdit (monospace) for template source |
| Preview | app.rs + preview.rs | Canvas render of PreviewModel; auto-scale or fixed mm |
| Help | app.rs | Scrollable view of docs/HELP.md via include_str! |
| Toolbar | app.rs | New, Open, Save, Save As, Print |
| Settings | app.rs | Page width (mm), preview mode |
| Print dialog | app.rs | Parameter fields + USB-serial printer picker |
Bottom panel switches tabs. Top panel holds actions and settings.
---
Data flow
Edit loop (live preview)
1. User types in the Editor tab. 2. Each frame, parse(&body) runs; errors show in the toolbar. 3. On Preview tab, render_preview(&doc, &metadata) builds a PreviewModel. 4. Canvas draws text lines, rules, and placeholders for barcode/QR/image.
Preview is not debounced — it re-parses when the Preview tab is shown (and parse runs every frame for error display).
Save / load
1. Open: rfd file dialog → PosFile::load_from_path → populate body, metadata, file_path. 2. Save / Save As: PosFile::save_to_path writes pretty-printed JSON.
Image paths in @image resolve relative to the .pos file directory on print.
1. User clicks Print → parse body → collect_parameter_names(&doc). 2. Modal shows one field per unique parameter; pre-filled from last_params (in-memory). 3. User selects a USB-serial port from list_usb_serial_printers(). 4. substitute_document → EscPosEncoder::encode_document → SerialTransport::open (9600 baud) → print_bytes.
---
Key types
Implemented in dsl/mod.rs, io/mod.rs, print/mod.rs:
// dsl/
struct Document { blocks: Vec<Block> }
enum Block {
Paragraph { align, inlines },
List { align, items },
Heading { level, inlines },
Rule,
Feed(u8),
Cut,
Image { path, width: ImageWidth, align },
Barcode { symbology, data, height, align, show_text },
Qr { data, size, ecc, align },
}
// io/
struct PosFile { version, metadata: PosMetadata, body }
struct PosMetadata { title, page_width_mm, preview_mode, chars_per_line, codepage }
// print/
struct PrinterDevice { id, display_name, port_name }
trait PrinterTransport { write_all, flush }
---
Preview vs print fidelity
| Aspect | Preview | |
|---|---|---|
| Text font | egui monospace/proportional | Printer built-in font |
| Line width | From chars_per_line() | ESC/POS dot width from page_width_mm |
| Images | [image: path] placeholder | Monochrome raster (GS v 0) |
| Barcodes / QR | Text placeholder | Native ESC/POS commands |
| Alignment | Canvas positioning | ESC a |
Both paths share the same AST; substitution happens only at print time. Preview shows unresolved ${Param} tokens as-is.
---
State persistence (current)
| Data | Storage | Notes |
|---|---|---|
| Template + metadata | .pos file on disk | User saves explicitly |
| Last parameter values | PosPrintApp.last_params | In-memory only; lost on quit |
| Recent files | — | Not implemented |
| Selected printer | — | Not persisted between sessions |
---
Testing
| Layer | Location | Approach |
|---|---|---|
| DSL parser | dsl/parser.rs | Unit tests |
| Parameters | params.rs | Unit tests |
| ESC/POS encoder | escpos.rs | Byte structure tests |
| Preview | preview.rs | Unit tests |
.pos I/O | io/mod.rs | Round-trip + tempfile tests |
| Printer I/O | print/mod.rs | MockTransport; no hardware in CI |
| App | app.rs | Default template parse/param tests |
Run: cargo test (20 tests). CI runs this on Linux (Docker) and Windows (shell runner).
---
Build and release
- CI: GitLab (
.gitlab-ci.yml) —cargo teston push; release artifacts on tags. - Linux artifact:
.debviacargo-deb([package.metadata.deb]inCargo.toml). - Windows artifact:
target/release/posprint.exe. - Versioning: Semver in
Cargo.toml;.posversionfield for file-format migrations.
---
Planned (not implemented)
- USB printer class (bulk OUT) without serial emulation
- Bluetooth SPP
- Network printers (TCP 9100)
- Baud-rate autodetect / settings UI
- Persisted last parameters and recent files
- Syntax highlighting in editor
See PRINTING.md and DSL-SPEC.md for protocol and language details.
Source
| 1 | # System architecture |
| 2 | |
| 3 | ## Overview |
| 4 | |
| 5 | posprint is a **single Rust binary** using **egui** (eframe). No separate frontend language, no WebView, no IPC layer. |
| 6 | |
| 7 | ``` |
| 8 | ┌─────────────────────────────────────────┐ |
| 9 | │ posprint (Rust + egui) │ |
| 10 | │ - Editor / Preview / Help tabs │ |
| 11 | │ - DSL parse → AST │ |
| 12 | │ - Preview layout + in-tree ESC/POS │ |
| 13 | │ - USB-serial printer discovery/print │ |
| 14 | │ - `.pos` JSON load/save (serde) │ |
| 15 | └─────────────────────────────────────────┘ |
| 16 | ``` |
| 17 | |
| 18 | ### Source layout |
| 19 | |
| 20 | ``` |
| 21 | src/ |
| 22 | ├── main.rs # eframe entry point |
| 23 | ├── app.rs # egui UI (editor, preview, help, print dialog) |
| 24 | ├── lib.rs # crate root; exports + HELP_MARKDOWN |
| 25 | ├── dsl/ # Parser and AST (mod.rs, parser.rs) |
| 26 | ├── params.rs # Parameter collect/substitute |
| 27 | ├── escpos.rs # ESC/POS byte encoder (in-tree) |
| 28 | ├── preview.rs # Preview model for UI canvas |
| 29 | ├── io/mod.rs # .pos file format (PosFile, PosMetadata) |
| 30 | └── print/mod.rs # USB-serial discovery, SerialTransport, MockTransport |
| 31 | ``` |
| 32 | |
| 33 | ### External dependencies (minimal) |
| 34 | |
| 35 | | Crate | Role | |
| 36 | |-------|------| |
| 37 | | `eframe` / `egui` | Native UI | |
| 38 | | `serde` / `serde_json` | `.pos` file format | |
| 39 | | `serialport` | USB-serial enumeration and I/O | |
| 40 | | `image` | Decode/resize images for `@image` raster print | |
| 41 | | `rfd` | Native open/save file dialogs | |
| 42 | |
| 43 | ESC/POS command generation is **not** delegated to a third-party crate. |
| 44 | |
| 45 | --- |
| 46 | |
| 47 | ## UI structure |
| 48 | |
| 49 | | Tab / area | Module | Description | |
| 50 | |------------|--------|-------------| |
| 51 | | **Editor** | `app.rs` | Multiline `TextEdit` (monospace) for template source | |
| 52 | | **Preview** | `app.rs` + `preview.rs` | Canvas render of `PreviewModel`; auto-scale or fixed mm | |
| 53 | | **Help** | `app.rs` | Scrollable view of `docs/HELP.md` via `include_str!` | |
| 54 | | Toolbar | `app.rs` | New, Open, Save, Save As, Print | |
| 55 | | Settings | `app.rs` | Page width (mm), preview mode | |
| 56 | | Print dialog | `app.rs` | Parameter fields + USB-serial printer picker | |
| 57 | |
| 58 | Bottom panel switches tabs. Top panel holds actions and settings. |
| 59 | |
| 60 | --- |
| 61 | |
| 62 | ## Data flow |
| 63 | |
| 64 | ### Edit loop (live preview) |
| 65 | |
| 66 | 1. User types in the Editor tab. |
| 67 | 2. Each frame, `parse(&body)` runs; errors show in the toolbar. |
| 68 | 3. On Preview tab, `render_preview(&doc, &metadata)` builds a `PreviewModel`. |
| 69 | 4. Canvas draws text lines, rules, and placeholders for barcode/QR/image. |
| 70 | |
| 71 | Preview is **not debounced** — it re-parses when the Preview tab is shown (and parse runs every frame for error display). |
| 72 | |
| 73 | ### Save / load |
| 74 | |
| 75 | 1. **Open:** `rfd` file dialog → `PosFile::load_from_path` → populate `body`, `metadata`, `file_path`. |
| 76 | 2. **Save / Save As:** `PosFile::save_to_path` writes pretty-printed JSON. |
| 77 | |
| 78 | Image paths in `@image` resolve relative to the `.pos` file directory on print. |
| 79 | |
| 80 | |
| 81 | |
| 82 | 1. User clicks **Print** → parse body → `collect_parameter_names(&doc)`. |
| 83 | 2. Modal shows one field per unique parameter; pre-filled from `last_params` (in-memory). |
| 84 | 3. User selects a USB-serial port from `list_usb_serial_printers()`. |
| 85 | 4. `substitute_document` → `EscPosEncoder::encode_document` → `SerialTransport::open` (9600 baud) → `print_bytes`. |
| 86 | |
| 87 | --- |
| 88 | |
| 89 | ## Key types |
| 90 | |
| 91 | Implemented in `dsl/mod.rs`, `io/mod.rs`, `print/mod.rs`: |
| 92 | |
| 93 | ```rust |
| 94 | // dsl/ |
| 95 | struct Document { blocks: Vec<Block> } |
| 96 | |
| 97 | enum Block { |
| 98 | Paragraph { align, inlines }, |
| 99 | List { align, items }, |
| 100 | Heading { level, inlines }, |
| 101 | Rule, |
| 102 | Feed(u8), |
| 103 | Cut, |
| 104 | Image { path, width: ImageWidth, align }, |
| 105 | Barcode { symbology, data, height, align, show_text }, |
| 106 | Qr { data, size, ecc, align }, |
| 107 | } |
| 108 | |
| 109 | // io/ |
| 110 | struct PosFile { version, metadata: PosMetadata, body } |
| 111 | struct PosMetadata { title, page_width_mm, preview_mode, chars_per_line, codepage } |
| 112 | |
| 113 | // print/ |
| 114 | struct PrinterDevice { id, display_name, port_name } |
| 115 | trait PrinterTransport { write_all, flush } |
| 116 | ``` |
| 117 | |
| 118 | --- |
| 119 | |
| 120 | ## Preview vs print fidelity |
| 121 | |
| 122 | | Aspect | Preview | Print | |
| 123 | |--------|---------|-------| |
| 124 | | Text font | egui monospace/proportional | Printer built-in font | |
| 125 | | Line width | From `chars_per_line()` | ESC/POS dot width from `page_width_mm` | |
| 126 | | Images | `[image: path]` placeholder | Monochrome raster (GS v 0) | |
| 127 | | Barcodes / QR | Text placeholder | Native ESC/POS commands | |
| 128 | | Alignment | Canvas positioning | ESC a | |
| 129 | |
| 130 | Both paths share the same **AST**; substitution happens only at print time. Preview shows unresolved `${Param}` tokens as-is. |
| 131 | |
| 132 | --- |
| 133 | |
| 134 | ## State persistence (current) |
| 135 | |
| 136 | | Data | Storage | Notes | |
| 137 | |------|---------|-------| |
| 138 | | Template + metadata | `.pos` file on disk | User saves explicitly | |
| 139 | | Last parameter values | `PosPrintApp.last_params` | In-memory only; lost on quit | |
| 140 | | Recent files | — | Not implemented | |
| 141 | | Selected printer | — | Not persisted between sessions | |
| 142 | |
| 143 | --- |
| 144 | |
| 145 | ## Testing |
| 146 | |
| 147 | | Layer | Location | Approach | |
| 148 | |-------|----------|----------| |
| 149 | | DSL parser | `dsl/parser.rs` | Unit tests | |
| 150 | | Parameters | `params.rs` | Unit tests | |
| 151 | | ESC/POS encoder | `escpos.rs` | Byte structure tests | |
| 152 | | Preview | `preview.rs` | Unit tests | |
| 153 | | `.pos` I/O | `io/mod.rs` | Round-trip + tempfile tests | |
| 154 | | Printer I/O | `print/mod.rs` | `MockTransport`; no hardware in CI | |
| 155 | | App | `app.rs` | Default template parse/param tests | |
| 156 | |
| 157 | Run: `cargo test` (20 tests). CI runs this on Linux (Docker) and Windows (shell runner). |
| 158 | |
| 159 | --- |
| 160 | |
| 161 | ## Build and release |
| 162 | |
| 163 | - **CI:** GitLab (`.gitlab-ci.yml`) — `cargo test` on push; release artifacts on tags. |
| 164 | - **Linux artifact:** `.deb` via `cargo-deb` (`[package.metadata.deb]` in `Cargo.toml`). |
| 165 | - **Windows artifact:** `target/release/posprint.exe`. |
| 166 | - **Versioning:** Semver in `Cargo.toml`; `.pos` `version` field for file-format migrations. |
| 167 | |
| 168 | --- |
| 169 | |
| 170 | ## Planned (not implemented) |
| 171 | |
| 172 | - USB printer class (bulk OUT) without serial emulation |
| 173 | - Bluetooth SPP |
| 174 | - Network printers (TCP 9100) |
| 175 | - Baud-rate autodetect / settings UI |
| 176 | - Persisted last parameters and recent files |
| 177 | - Syntax highlighting in editor |
| 178 | |
| 179 | See [PRINTING.md](PRINTING.md) and [DSL-SPEC.md](DSL-SPEC.md) for protocol and language details. |