BlueGit

timfa posprint

Files

posprint / docs / ARCHITECTURE.md

ARCHITECTURE.md

ARCHITECTURE.md 5.8 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 (editor + preview) / Help              │
│  - 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, 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
├── 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/   # OS “Print” context menu helpers

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
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!
Toolbarapp.rsNew, Open, Save, Save As, Insert, Print
Settingsapp.rsPage width (mm), preview zoom
Print dialogprint_dialog.rsParameters + multi-transport printer picker

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: one field per parameter; 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 },
    List { align, items },
    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) }

// 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)
Recent files / selected printerNot 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 (editor + preview) / Help │
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, 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├── editor_assist.rs # @ autocomplete, Insert snippets
35├── help_view.rs # Markdown help renderer
36├── io/mod.rs # PosFile, PosMetadata
37├── pipeline.rs # Encode / print helpers
38├── print/
39│ ├── mod.rs # list_printers, SerialTransport, MockTransport
40│ ├── usb_direct.rs # USB printer-class (rusb)
41│ └── win_spool.rs # Windows spooler (Windows)
42└── shell_integration/ # OS “Print” context menu helpers
43```
44
45### External dependencies
46
47| Crate | Role |
48|-------|------|
49| `eframe` / `egui` | Native UI |
50| `serde` / `serde_json` | `.pos` file format |
51| `serialport` | Serial enumeration and I/O |
52| `rusb` | USB printer-class devices |
53| `image` | Decode/resize images |
54| `rfd` | Native open/save dialogs |
55| `barcoders` / `qrcode` | Raster barcodes and QR |
56| `clap` | CLI |
57| `chrono` | Date/time |
58| `pulldown-cmark` | In-app Help markdown |
59
60ESC/POS generation is **in-tree** (`escpos.rs`), not the `escpos` crates.io package.
61
62---
63
64## UI structure
65
66| Area | Module | Description |
67|------|--------|-------------|
68| **Design** | `app.rs` | Editor + side preview |
69| **Help** | `help_view.rs` | `docs/HELP.md` via `include_str!` |
70| Toolbar | `app.rs` | New, Open, Save, Save As, Insert, Print |
71| Settings | `app.rs` | Page width (mm), preview zoom |
72| Print dialog | `print_dialog.rs` | Parameters + multi-transport printer picker |
73
74While the print dialog is open, the main UI is disabled and editor autocomplete does not steal focus.
75
76---
77
78## Data flow
79
80### Edit loop (live preview)
81
821. User edits the template on the Design tab.
832. Each frame, `parse(&body)` runs; errors show in the toolbar.
843. `render_preview` builds a `PreviewModel` (text, rules, bitmaps, spacers).
854. Canvas draws with calibrated zoom (`PREVIEW_SCREEN_CALIBRATION`) and Font A–matched text size.
86
87### Save / load
88
891. **Open:** `rfd` → `PosFile::load_from_path`.
902. **Save / Save As:** pretty-printed JSON.
91
92`@image` paths resolve relative to the `.pos` directory on preview and print.
93
94### Print
95
961. **Print** → parse → `collect_parameter_names`.
972. Dialog: one field per parameter; `list_printers()` for USB / spooler / serial.
983. `substitute_document` → `EscPosEncoder` → `open_printer` → `print_bytes`.
994. Serial baud is probed (`115200` first, then `9600`, …).
100
101---
102
103## Key types
104
105```rust
106// dsl/
107struct Document { blocks: Vec<Block> }
108enum Block {
109 Paragraph { align, inlines },
110 List { align, items },
111 Heading { level, align, inlines },
112 Rule, Feed(u8), Cut,
113 Image { path, width, align },
114 Barcode { mode, symbology, data, height, align, show_text },
115 Qr { mode, data, size, ecc, version, align },
116 Date { format, align },
117 Time { format, align },
118}
119enum Inline { Text(String), Param(String) }
120
121// io/
122struct PosMetadata { title, page_width_mm, chars_per_line, codepage }
123// printable_dots() = chars_per_line() * 12
124
125// print/
126enum PrinterTarget { Serial(String), UsbDirect { … }, WinSpooler(String) }
127```
128
129Legacy JSON fields `preview_mode` and `cut_after_print` are ignored if present.
130
131---
132
133## Preview vs print fidelity
134
135| Aspect | Preview | Print |
136|--------|---------|-------|
137| Text | egui monospace (print-matched size) | Printer Font A |
138| Line width | `chars_per_line` / `printable_dots` | Same wrap model |
139| Images / barcode / QR | Raster bitmaps | ESC/POS native or GS v 0 |
140| Blank lines | Spacer = line spacing dots | ESC d |
141| Parameters | Sample / dialog values | Substituted values |
142
143---
144
145## State persistence
146
147| Data | Storage |
148|------|---------|
149| Template + metadata | `.pos` file |
150| Last parameter values | In-memory (`print_dialog.last_params`) |
151| Recent files / selected printer | Not persisted |
152
153---
154
155## Testing
156
157| Layer | Location |
158|-------|----------|
159| DSL, params, ESC/POS, preview, wrap, I/O, print mocks | `src/**` unit tests |
160| App / shell helpers | `src/main.rs` tests |
161
162Run: `cargo test` (~100 tests). CI: tests on merge requests; release artifacts on tags.
163
164---
165
166## Build and release
167
168- **CI:** GitLab (`.gitlab-ci.yml`)
169- **Artifacts:** Windows `.exe`, Debian `.deb`, Arch `.pkg.tar.zst`
170- **Versioning:** Semver in `Cargo.toml`; `.pos` `version` for file-format migrations
171
172See [PRINTING.md](PRINTING.md), [DSL-SPEC.md](DSL-SPEC.md), and [BUILD.md](BUILD.md).