BlueGit

timfa posprint

Files

posprint / docs / ARCHITECTURE.md

ARCHITECTURE.md

ARCHITECTURE.md 6.5 KiB Download Raw

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

CrateRole
eframe / eguiNative UI
serde / serde_json.pos file format
serialportSerial enumeration and I/O
rusbUSB printer-class devices
imageDecode/resize images
rfdNative open/save dialogs
barcoders / qrcodeRaster barcodes and QR
clapCLI
flate2 / base64posprint:// payloads
ureq@image http(s) download
chronoDate/time
pulldown-cmarkIn-app Help markdown

ESC/POS generation is in-tree (escpos.rs), not the escpos crates.io package.

---

UI structure

AreaModuleDescription
Designapp.rsEditor + side preview
Helphelp_view.rsdocs/HELP.md via include_str!
Settingsapp.rsDefault page width for new documents
Toolbarapp.rsNew, Open, Save, Save As, Insert, Print
Document page width / zoomapp.rsPer-document width (mm), preview zoom
Print dialogprint_dialog.rsParameters + multi-transport printer picker
App configconfig.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 / 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

AspectPreviewPrint
Textegui monospace (print-matched size)Printer Font A
Line widthchars_per_line / printable_dotsSame wrap model
Images / barcode / QRRaster bitmapsESC/POS native or GS v 0
Blank linesSpacer = line spacing dotsESC d
ParametersSample / dialog valuesSubstituted values

---

State persistence

DataStorage
Template + metadata.pos file
Last parameter valuesIn-memory (print_dialog.last_params)
Default page width / last printerconfig.rs → platform config JSON
Recent filesNot persisted

---

Testing

LayerLocation
DSL, params, ESC/POS, preview, wrap, I/O, print mockssrc/** unit tests
App / shell helperssrc/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; .pos version for file-format migrations

See PRINTING.md, DSL-SPEC.md, and BUILD.md.

Source
1# System architecture
2
3## Overview
4
5posprint 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```
20src/
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
64ESC/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
80While 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
881. User edits the template on the Design tab.
892. Each frame, `parse(&body)` runs; errors show in the toolbar.
903. `render_preview` builds a `PreviewModel` (text, rules, bitmaps, spacers).
914. Canvas draws with calibrated zoom (`PREVIEW_SCREEN_CALIBRATION`) and Font A–matched text size.
92
93### Save / load
94
951. **Open:** `rfd` → `PosFile::load_from_path`.
962. **Save / Save As:** pretty-printed JSON.
97
98`@image` paths resolve relative to the `.pos` directory on preview and print.
99
100### Print
101
1021. **Print** → parse → `collect_parameter_names`.
1032. Dialog: text field per `${Name}`, checkbox per `$[Name]`; `list_printers()` for USB / spooler / serial.
1043. `substitute_document` → `EscPosEncoder` → `open_printer` → `print_bytes`.
1054. Serial baud is probed (`115200` first, then `9600`, …).
106
107---
108
109## Key types
110
111```rust
112// dsl/
113struct Document { blocks: Vec<Block> }
114enum 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}
126enum Inline { Text(String), Param(String), CheckboxParam(String), Checkbox { checked } }
127
128// io/
129struct PosMetadata { title, page_width_mm, chars_per_line, codepage }
130// printable_dots() = chars_per_line() * 12
131
132// print/
133enum PrinterTarget { Serial(String), UsbDirect { … }, WinSpooler(String) }
134```
135
136Legacy 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
170Run: `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
180See [PRINTING.md](PRINTING.md), [DSL-SPEC.md](DSL-SPEC.md), and [BUILD.md](BUILD.md).