System architecture
Overview
posprint is a single Rust binary using egui (eframe). No separate frontend language, no WebView, no IPC layer.
┌──────────────────────────────────────────────────┐
│ posprint (Rust + egui) │
│ - Design / Help / Settings │
│ - DSL parse → AST → preview + ESC/POS │
│ - USB-direct / Win spooler / serial printing │
│ - `.pos` JSON load/save (serde) │
└──────────────────────────────────────────────────┘
Source layout
src/
├── main.rs # CLI + eframe / print-only entry
├── app.rs # Full designer UI
├── print_only_app.rs # Print-only window (--print)
├── print_dialog.rs # Shared print dialog
├── cli.rs # clap: print, link, cli-help
├── lib.rs # crate root; HELP_MARKDOWN
├── dsl/ # Parser and AST
├── params.rs # Parameter collect / substitute / preview samples
├── escpos.rs # ESC/POS byte encoder (in-tree)
├── preview.rs # PreviewModel for UI canvas
├── text_wrap.rs # Shared wrap (preview + print)
├── datetime.rs # @date / @time formatting
├── raster.rs # Barcode / QR bitmaps
├── image_load.rs # Local + http(s) @image loading
├── protocol_url.rs # posprint:// encode/decode
├── editor_assist.rs # @ autocomplete, Insert snippets
├── help_view.rs # Markdown help renderer
├── io/mod.rs # PosFile, PosMetadata
├── pipeline.rs # Encode / print helpers
├── print/
│ ├── mod.rs # list_printers, SerialTransport, MockTransport
│ ├── usb_direct.rs # USB printer-class (rusb)
│ └── win_spool.rs # Windows spooler (Windows)
└── shell_integration.rs # .pos Print verb + posprint:// protocol (Windows)
External dependencies
| Crate | Role |
|---|---|
eframe / egui | Native UI |
serde / serde_json | .pos file format |
serialport | Serial enumeration and I/O |
rusb | USB printer-class devices |
image | Decode/resize images |
rfd | Native open/save dialogs |
barcoders / qrcode | Raster barcodes and QR |
clap | CLI |
flate2 / base64 | posprint:// payloads |
ureq | @image http(s) download |
chrono | Date/time |
pulldown-cmark | In-app Help markdown |
ESC/POS generation is in-tree (escpos.rs), not the escpos crates.io package.
---
UI structure
| Area | Module | Description |
|---|---|---|
| Design | app.rs | Editor + side preview |
| Help | help_view.rs | docs/HELP.md via include_str! |
| Settings | app.rs | Default page width for new documents |
| Toolbar | app.rs | New, Open, Save, Save As, Insert, Print |
| Document page width / zoom | app.rs | Per-document width (mm), preview zoom |
| Print dialog | print_dialog.rs | Parameters + multi-transport printer picker |
| App config | config.rs | %APPDATA%/posprint/config.json (Windows) / ~/.config/posprint/config.json (default width, last printer) |
While the print dialog is open, the main UI is disabled and editor autocomplete does not steal focus.
---
Data flow
Edit loop (live preview)
1. User edits the template on the Design tab. 2. Each frame, parse(&body) runs; errors show in the toolbar. 3. render_preview builds a PreviewModel (text, rules, bitmaps, spacers). 4. Canvas draws with calibrated zoom (PREVIEW_SCREEN_CALIBRATION) and Font A–matched text size.
Save / load
1. Open: rfd → PosFile::load_from_path. 2. Save / Save As: pretty-printed JSON.
@image paths resolve relative to the .pos directory on preview and print.
1. Print → parse → collect_parameter_names. 2. Dialog: text field per ${Name}, checkbox per $[Name]; list_printers() for USB / spooler / serial. 3. substitute_document → EscPosEncoder → open_printer → print_bytes. 4. Serial baud is probed (115200 first, then 9600, …).
---
Key types
// dsl/
struct Document { blocks: Vec<Block> }
enum Block {
Paragraph { align, inlines },
AlignedRow { parts }, // same-line :left:/:center:/:right: → space pad
List { align, items: Vec<ListItem> }, // ListItem { depth, inlines }
Heading { level, align, inlines },
Rule, Feed(u8), Cut,
Image { path, width, align },
Barcode { mode, symbology, data, height, align, show_text },
Qr { mode, data, size, ecc, version, align },
Date { format, align },
Time { format, align },
}
enum Inline { Text(String), Param(String), CheckboxParam(String), Checkbox { checked } }
// io/
struct PosMetadata { title, page_width_mm, chars_per_line, codepage }
// printable_dots() = chars_per_line() * 12
// print/
enum PrinterTarget { Serial(String), UsbDirect { … }, WinSpooler(String) }
Legacy JSON fields preview_mode and cut_after_print are ignored if present.
---
Preview vs print fidelity
| Aspect | Preview | |
|---|---|---|
| Text | egui monospace (print-matched size) | Printer Font A |
| Line width | chars_per_line / printable_dots | Same wrap model |
| Images / barcode / QR | Raster bitmaps | ESC/POS native or GS v 0 |
| Blank lines | Spacer = line spacing dots | ESC d |
| Parameters | Sample / dialog values | Substituted values |
---
State persistence
| Data | Storage |
|---|---|
| Template + metadata | .pos file |
| Last parameter values | In-memory (print_dialog.last_params) |
| Default page width / last printer | config.rs → platform config JSON |
| Recent files | Not persisted |
---
Testing
| Layer | Location |
|---|---|
| DSL, params, ESC/POS, preview, wrap, I/O, print mocks | src/** unit tests |
| App / shell helpers | src/main.rs tests |
Run: cargo test (~100 tests). CI: tests on merge requests; release artifacts on tags.
---
Build and release
- CI: GitLab (
.gitlab-ci.yml) - Artifacts: Windows
.exe, Debian.deb, Arch.pkg.tar.zst - Versioning: Semver in
Cargo.toml;.posversionfor file-format migrations
See PRINTING.md, DSL-SPEC.md, and BUILD.md.
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 | │ - Design / Help / Settings │ |
| 11 | │ - DSL parse → AST → preview + ESC/POS │ |
| 12 | │ - USB-direct / Win spooler / serial printing │ |
| 13 | │ - `.pos` JSON load/save (serde) │ |
| 14 | └──────────────────────────────────────────────────┘ |
| 15 | ``` |
| 16 | |
| 17 | ### Source layout |
| 18 | |
| 19 | ``` |
| 20 | src/ |
| 21 | ├── main.rs # CLI + eframe / print-only entry |
| 22 | ├── app.rs # Full designer UI |
| 23 | ├── print_only_app.rs # Print-only window (--print) |
| 24 | ├── print_dialog.rs # Shared print dialog |
| 25 | ├── cli.rs # clap: print, link, cli-help |
| 26 | ├── lib.rs # crate root; HELP_MARKDOWN |
| 27 | ├── dsl/ # Parser and AST |
| 28 | ├── params.rs # Parameter collect / substitute / preview samples |
| 29 | ├── escpos.rs # ESC/POS byte encoder (in-tree) |
| 30 | ├── preview.rs # PreviewModel for UI canvas |
| 31 | ├── text_wrap.rs # Shared wrap (preview + print) |
| 32 | ├── datetime.rs # @date / @time formatting |
| 33 | ├── raster.rs # Barcode / QR bitmaps |
| 34 | ├── image_load.rs # Local + http(s) @image loading |
| 35 | ├── protocol_url.rs # posprint:// encode/decode |
| 36 | ├── editor_assist.rs # @ autocomplete, Insert snippets |
| 37 | ├── help_view.rs # Markdown help renderer |
| 38 | ├── io/mod.rs # PosFile, PosMetadata |
| 39 | ├── pipeline.rs # Encode / print helpers |
| 40 | ├── print/ |
| 41 | │ ├── mod.rs # list_printers, SerialTransport, MockTransport |
| 42 | │ ├── usb_direct.rs # USB printer-class (rusb) |
| 43 | │ └── win_spool.rs # Windows spooler (Windows) |
| 44 | └── shell_integration.rs # .pos Print verb + posprint:// protocol (Windows) |
| 45 | ``` |
| 46 | |
| 47 | ### External dependencies |
| 48 | |
| 49 | | Crate | Role | |
| 50 | |-------|------| |
| 51 | | `eframe` / `egui` | Native UI | |
| 52 | | `serde` / `serde_json` | `.pos` file format | |
| 53 | | `serialport` | Serial enumeration and I/O | |
| 54 | | `rusb` | USB printer-class devices | |
| 55 | | `image` | Decode/resize images | |
| 56 | | `rfd` | Native open/save dialogs | |
| 57 | | `barcoders` / `qrcode` | Raster barcodes and QR | |
| 58 | | `clap` | CLI | |
| 59 | | `flate2` / `base64` | `posprint://` payloads | |
| 60 | | `ureq` | `@image http(s)` download | |
| 61 | | `chrono` | Date/time | |
| 62 | | `pulldown-cmark` | In-app Help markdown | |
| 63 | |
| 64 | ESC/POS generation is **in-tree** (`escpos.rs`), not the `escpos` crates.io package. |
| 65 | |
| 66 | --- |
| 67 | |
| 68 | ## UI structure |
| 69 | |
| 70 | | Area | Module | Description | |
| 71 | |------|--------|-------------| |
| 72 | | **Design** | `app.rs` | Editor + side preview | |
| 73 | | **Help** | `help_view.rs` | `docs/HELP.md` via `include_str!` | |
| 74 | | **Settings** | `app.rs` | Default page width for new documents | |
| 75 | | Toolbar | `app.rs` | New, Open, Save, Save As, Insert, Print | |
| 76 | | Document page width / zoom | `app.rs` | Per-document width (mm), preview zoom | |
| 77 | | Print dialog | `print_dialog.rs` | Parameters + multi-transport printer picker | |
| 78 | | App config | `config.rs` | `%APPDATA%/posprint/config.json` (Windows) / `~/.config/posprint/config.json` (default width, last printer) | |
| 79 | |
| 80 | While the print dialog is open, the main UI is disabled and editor autocomplete does not steal focus. |
| 81 | |
| 82 | --- |
| 83 | |
| 84 | ## Data flow |
| 85 | |
| 86 | ### Edit loop (live preview) |
| 87 | |
| 88 | 1. User edits the template on the Design tab. |
| 89 | 2. Each frame, `parse(&body)` runs; errors show in the toolbar. |
| 90 | 3. `render_preview` builds a `PreviewModel` (text, rules, bitmaps, spacers). |
| 91 | 4. Canvas draws with calibrated zoom (`PREVIEW_SCREEN_CALIBRATION`) and Font A–matched text size. |
| 92 | |
| 93 | ### Save / load |
| 94 | |
| 95 | 1. **Open:** `rfd` → `PosFile::load_from_path`. |
| 96 | 2. **Save / Save As:** pretty-printed JSON. |
| 97 | |
| 98 | `@image` paths resolve relative to the `.pos` directory on preview and print. |
| 99 | |
| 100 | |
| 101 | |
| 102 | 1. **Print** → parse → `collect_parameter_names`. |
| 103 | 2. Dialog: text field per `${Name}`, checkbox per `$[Name]`; `list_printers()` for USB / spooler / serial. |
| 104 | 3. `substitute_document` → `EscPosEncoder` → `open_printer` → `print_bytes`. |
| 105 | 4. Serial baud is probed (`115200` first, then `9600`, …). |
| 106 | |
| 107 | --- |
| 108 | |
| 109 | ## Key types |
| 110 | |
| 111 | ```rust |
| 112 | // dsl/ |
| 113 | struct Document { blocks: Vec<Block> } |
| 114 | enum Block { |
| 115 | Paragraph { align, inlines }, |
| 116 | AlignedRow { parts }, // same-line :left:/:center:/:right: → space pad |
| 117 | List { align, items: Vec<ListItem> }, // ListItem { depth, inlines } |
| 118 | Heading { level, align, inlines }, |
| 119 | Rule, Feed(u8), Cut, |
| 120 | Image { path, width, align }, |
| 121 | Barcode { mode, symbology, data, height, align, show_text }, |
| 122 | Qr { mode, data, size, ecc, version, align }, |
| 123 | Date { format, align }, |
| 124 | Time { format, align }, |
| 125 | } |
| 126 | enum Inline { Text(String), Param(String), CheckboxParam(String), Checkbox { checked } } |
| 127 | |
| 128 | // io/ |
| 129 | struct PosMetadata { title, page_width_mm, chars_per_line, codepage } |
| 130 | // printable_dots() = chars_per_line() * 12 |
| 131 | |
| 132 | // print/ |
| 133 | enum PrinterTarget { Serial(String), UsbDirect { … }, WinSpooler(String) } |
| 134 | ``` |
| 135 | |
| 136 | Legacy JSON fields `preview_mode` and `cut_after_print` are ignored if present. |
| 137 | |
| 138 | --- |
| 139 | |
| 140 | ## Preview vs print fidelity |
| 141 | |
| 142 | | Aspect | Preview | Print | |
| 143 | |--------|---------|-------| |
| 144 | | Text | egui monospace (print-matched size) | Printer Font A | |
| 145 | | Line width | `chars_per_line` / `printable_dots` | Same wrap model | |
| 146 | | Images / barcode / QR | Raster bitmaps | ESC/POS native or GS v 0 | |
| 147 | | Blank lines | Spacer = line spacing dots | ESC d | |
| 148 | | Parameters | Sample / dialog values | Substituted values | |
| 149 | |
| 150 | --- |
| 151 | |
| 152 | ## State persistence |
| 153 | |
| 154 | | Data | Storage | |
| 155 | |------|---------| |
| 156 | | Template + metadata | `.pos` file | |
| 157 | | Last parameter values | In-memory (`print_dialog.last_params`) | |
| 158 | | Default page width / last printer | `config.rs` → platform config JSON | |
| 159 | | Recent files | Not persisted | |
| 160 | |
| 161 | --- |
| 162 | |
| 163 | ## Testing |
| 164 | |
| 165 | | Layer | Location | |
| 166 | |-------|----------| |
| 167 | | DSL, params, ESC/POS, preview, wrap, I/O, print mocks | `src/**` unit tests | |
| 168 | | App / shell helpers | `src/main.rs` tests | |
| 169 | |
| 170 | Run: `cargo test` (~100 tests). CI: tests on merge requests; release artifacts on tags. |
| 171 | |
| 172 | --- |
| 173 | |
| 174 | ## Build and release |
| 175 | |
| 176 | - **CI:** GitLab (`.gitlab-ci.yml`) |
| 177 | - **Artifacts:** Windows `.exe`, Debian `.deb`, Arch `.pkg.tar.zst` |
| 178 | - **Versioning:** Semver in `Cargo.toml`; `.pos` `version` for file-format migrations |
| 179 | |
| 180 | See [PRINTING.md](PRINTING.md), [DSL-SPEC.md](DSL-SPEC.md), and [BUILD.md](BUILD.md). |