# 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 / BT SPP │ │ - `.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. ### Print 1. **Print** → parse → `collect_parameter_names`. 2. Dialog: text field per `${Name}`, checkbox per `$[Name]`; `list_printers()` for USB / spooler / USB-serial / paired Bluetooth SPP. 3. `substitute_document` → `EscPosEncoder` → `open_printer` → `print_bytes`. 4. Serial baud is probed (`115200` first, then `9600`, …). --- ## Key types ```rust // dsl/ struct Document { blocks: Vec } enum Block { Paragraph { align, inlines }, AlignedRow { parts }, // same-line :left:/:center:/:right: → space pad List { align, items: Vec }, // 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 | Print | |--------|---------|-------| | 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`, Linux `posprint--x86_64.tar.gz` (AUR `posprint-bin`) - **AUR:** source package `posprint` and binary package `posprint-bin` (see [AUR.md](AUR.md)) - **Versioning:** Semver in `Cargo.toml`; `.pos` `version` for file-format migrations See [PRINTING.md](PRINTING.md), [DSL-SPEC.md](DSL-SPEC.md), and [BUILD.md](BUILD.md).