BlueGit

timfa posprint

Files

posprint / docs / ARCHITECTURE.md

ARCHITECTURE.md

ARCHITECTURE.md 4.9 KiB Download Raw

System architecture

Overview

posprint is a single Rust binary using egui (eframe). No separate frontend language.

┌─────────────────────────────────────────┐
│  posprint (Rust + egui)                 │
│  - Editor / Preview / Help tabs         │
│  - DSL parse → AST                      │
│  - Preview layout + ESC/POS encode      │
│  - USB-serial printer discovery/print   │
│  - `.pos` serde                         │
└─────────────────────────────────────────┘

Crate layout

src/
├── main.rs, app.rs     # egui application
├── lib.rs
├── dsl/                # Parser and AST
├── params.rs           # Parameter collect/substitute
├── escpos.rs           # ESC/POS byte encoder
├── preview.rs          # Preview model
├── io/                 # .pos file format
└── print/              # USB-serial discovery and I/O

---

Data flow

Edit loop (live preview)

1. User types in editor → debounced (e.g. 150 ms) invoke preview_document(source, settings). 2. Core parses DSL → AST (or returns parse errors with line/col). 3. Core renders preview model: text lines, image refs, barcode/QR placeholders sized to page width. 4. UI displays preview scaled to panel width (auto) or fixed mm width.

Save / load

1. Save: UI sends { metadata, body } → save_pos(path) → JSON on disk. 2. Load: load_pos(path) → populate editor and settings.

Print

1. User clicks Print → collect_parameters(ast) → unique sorted names. 2. UI shows modal; pre-fill from last_print_params in app state. 3. On confirm → print_document(ast, params, printer_id). 4. Core: substitute → build ESC/POS → open transport → write bytes → cut (if configured).

---

Key types (conceptual)

struct Document {
    blocks: Vec<Block>,
}

enum Block {
    Paragraph { inlines: Vec<Inline>, align: Align },
    Heading { level: u8, text: String },
    Rule,
    Image { src: String, width: ImageWidth },  // src may be ${Param}
    Barcode { symbology: BarcodeKind, data: String, height: u8 },
    Qr { data: String, size: QrSize },
    Feed { lines: u8 },
    Cut,
}

struct PosFile {
    version: u32,
    metadata: Metadata,
    body: String,
}

struct Metadata {
    title: Option<String>,
    page_width_mm: f32,       // 58, 80, etc.
    preview_mode: PreviewMode, // AutoScale | Fixed
    codepage: Option<String>,
    cut_after_print: bool,
}

struct PrinterDevice {
    id: String,               // stable key for session
    name: String,
    transport: TransportKind,
    // ...
}

---

Tauri commands (IPC surface)

CommandInputOutput
parse_documentbody: string`{ ast \errors }`
preview_documentbody, metadataPreviewModel
collect_parametersbodystring[] (unique, sorted)
save_pospath, PosFileResult<()>
load_pospathPosFile
list_printers—PrinterDevice[]
print_documentbody, metadata, params, printer_idResult<()>

---

Preview vs print fidelity

AspectPreviewPrint
Text fontUI monospace, scaledPrinter built-in font
Line widthComputed from page_width_mmESC/POS dot width
ImagesResized bitmap in canvasRaster ESC/POS
BarcodesSVG/canvas placeholderNative printer barcode commands
AlignmentCSS / canvasESC/POS justify commands

Both paths share the same AST and substitution; preview and print each have their own backend (preview renderer vs escpos encoder).

---

State persistence

DataStorage
Recent filesApp config (Tauri app_data_dir)
Last parameter valuesparams.json keyed by template path or global
Window layoutOptional, Tauri store
Selected printerPer-machine preference

---

Testing strategy

LayerApproach
DSL parserUnit tests + snapshot fixtures
Parameter collect/substituteUnit tests
ESC/POS encoderByte snapshot tests
Preview layoutSnapshot images (optional)
Printer I/OManual hardware matrix; mock Transport trait in CI
UIComponent tests; E2E with mocked Tauri commands

---

Build and release

  • CI: GitHub Actions — cargo test, cargo clippy, frontend lint, build Windows + Linux artifacts.
  • Artifacts: .msi or .exe (Windows), .deb / AppImage (Linux).
  • Versioning: Semver; .pos version field for file format migrations.

See PRINTING.md for the device layer and DSL-SPEC.md for language details.

Source
1# System architecture
2
3## Overview
4
5posprint is a **single Rust binary** using **egui** (eframe). No separate frontend language.
6
7```
8┌─────────────────────────────────────────┐
9│ posprint (Rust + egui) │
10│ - Editor / Preview / Help tabs │
11│ - DSL parse → AST │
12│ - Preview layout + ESC/POS encode │
13│ - USB-serial printer discovery/print │
14│ - `.pos` serde │
15└─────────────────────────────────────────┘
16```
17
18### Crate layout
19
20```
21src/
22├── main.rs, app.rs # egui application
23├── lib.rs
24├── dsl/ # Parser and AST
25├── params.rs # Parameter collect/substitute
26├── escpos.rs # ESC/POS byte encoder
27├── preview.rs # Preview model
28├── io/ # .pos file format
29└── print/ # USB-serial discovery and I/O
30```
31
32---
33
34## Data flow
35
36### Edit loop (live preview)
37
381. User types in editor → debounced (e.g. 150 ms) invoke `preview_document(source, settings)`.
392. Core parses DSL → AST (or returns parse errors with line/col).
403. Core renders preview model: text lines, image refs, barcode/QR placeholders sized to page width.
414. UI displays preview scaled to panel width (auto) or fixed mm width.
42
43### Save / load
44
451. **Save:** UI sends `{ metadata, body }` → `save_pos(path)` → JSON on disk.
462. **Load:** `load_pos(path)` → populate editor and settings.
47
48### Print
49
501. User clicks Print → `collect_parameters(ast)` → unique sorted names.
512. UI shows modal; pre-fill from `last_print_params` in app state.
523. On confirm → `print_document(ast, params, printer_id)`.
534. Core: substitute → build ESC/POS → open transport → write bytes → cut (if configured).
54
55---
56
57## Key types (conceptual)
58
59```rust
60struct Document {
61 blocks: Vec<Block>,
62}
63
64enum Block {
65 Paragraph { inlines: Vec<Inline>, align: Align },
66 Heading { level: u8, text: String },
67 Rule,
68 Image { src: String, width: ImageWidth }, // src may be ${Param}
69 Barcode { symbology: BarcodeKind, data: String, height: u8 },
70 Qr { data: String, size: QrSize },
71 Feed { lines: u8 },
72 Cut,
73}
74
75struct PosFile {
76 version: u32,
77 metadata: Metadata,
78 body: String,
79}
80
81struct Metadata {
82 title: Option<String>,
83 page_width_mm: f32, // 58, 80, etc.
84 preview_mode: PreviewMode, // AutoScale | Fixed
85 codepage: Option<String>,
86 cut_after_print: bool,
87}
88
89struct PrinterDevice {
90 id: String, // stable key for session
91 name: String,
92 transport: TransportKind,
93 // ...
94}
95```
96
97---
98
99## Tauri commands (IPC surface)
100
101| Command | Input | Output |
102|---------|-------|--------|
103| `parse_document` | `body: string` | `{ ast \| errors }` |
104| `preview_document` | `body, metadata` | `PreviewModel` |
105| `collect_parameters` | `body` | `string[]` (unique, sorted) |
106| `save_pos` | `path, PosFile` | `Result<()>` |
107| `load_pos` | `path` | `PosFile` |
108| `list_printers` | — | `PrinterDevice[]` |
109| `print_document` | `body, metadata, params, printer_id` | `Result<()>` |
110
111---
112
113## Preview vs print fidelity
114
115| Aspect | Preview | Print |
116|--------|---------|-------|
117| Text font | UI monospace, scaled | Printer built-in font |
118| Line width | Computed from `page_width_mm` | ESC/POS dot width |
119| Images | Resized bitmap in canvas | Raster ESC/POS |
120| Barcodes | SVG/canvas placeholder | Native printer barcode commands |
121| Alignment | CSS / canvas | ESC/POS justify commands |
122
123Both paths share the **same AST and substitution**; preview and print each have their own backend (preview renderer vs `escpos` encoder).
124
125---
126
127## State persistence
128
129| Data | Storage |
130|------|---------|
131| Recent files | App config (Tauri `app_data_dir`) |
132| Last parameter values | `params.json` keyed by template path or global |
133| Window layout | Optional, Tauri store |
134| Selected printer | Per-machine preference |
135
136---
137
138## Testing strategy
139
140| Layer | Approach |
141|-------|----------|
142| DSL parser | Unit tests + snapshot fixtures |
143| Parameter collect/substitute | Unit tests |
144| ESC/POS encoder | Byte snapshot tests |
145| Preview layout | Snapshot images (optional) |
146| Printer I/O | Manual hardware matrix; mock `Transport` trait in CI |
147| UI | Component tests; E2E with mocked Tauri commands |
148
149---
150
151## Build and release
152
153- **CI:** GitHub Actions — `cargo test`, `cargo clippy`, frontend lint, build Windows + Linux artifacts.
154- **Artifacts:** `.msi` or `.exe` (Windows), `.deb` / AppImage (Linux).
155- **Versioning:** Semver; `.pos` `version` field for file format migrations.
156
157See [PRINTING.md](PRINTING.md) for the device layer and [DSL-SPEC.md](DSL-SPEC.md) for language details.