BlueGit

timfa posprint

Files

posprint / docs / ARCHITECTURE.md

ARCHITECTURE.md

ARCHITECTURE.md 7.5 KiB Download Raw

System architecture

Overview

posprint is a desktop application with a web-based UI (Tauri) and a Rust backend that owns parsing, rendering, file I/O, and printer communication.

┌──────────────────────────────────────────────────────────────────┐
│                         Application                              │
├────────────────────────────┬─────────────────────────────────────┤
│         UI Layer           │           Core Layer (Rust)       │
│  (TypeScript / Tauri WebView)                                    │
│                            │                                     │
│  DocumentEditor ───────────┼──► parse_dsl() → Document AST       │
│  PreviewPane ◄─────────────┼─── render_preview(ast, width)     │
│  SettingsPanel             │                                     │
│  ParameterDialog           │                                     │
│  PrinterPicker             │                                     │
│                            │                                     │
│  File menu ────────────────┼──► load_pos() / save_pos()          │
│  Print button ─────────────┼──► list_printers()                  │
│                            │    print_document(ast, params, dev) │
└────────────────────────────┴─────────────────────────────────────┘
                                      │
                    ┌─────────────────┼─────────────────┐
                    ▼                 ▼                 ▼
              Preview bitmap    ESC/POS bytes     .pos JSON file

---

Modules (Rust crate layout)

posprint-core/          # Library — no UI, unit-testable
├── dsl/
│   ├── lexer.rs        # Tokenize source
│   ├── parser.rs       # Build AST
│   └── ast.rs          # Document, Block, Inline, Directive nodes
├── render/
│   ├── preview.rs      # Layout for UI (lines, images, barcode placeholders)
│   └── escpos.rs       # AST → ESC/POS byte buffer
├── params/
│   ├── collect.rs      # Find unique ${Name} tokens
│   └── substitute.rs   # Apply user values before render/print
├── io/
│   └── pos_file.rs     # Serde types, load/save
└── print/
    ├── discover.rs     # Enumerate serial / USB / BT devices
    ├── transport.rs    # Trait: write(bytes), read optional status
    └── pipeline.rs     # substitute → escpos → transport

posprint-app/           # Tauri binary
├── commands/           # #[tauri::command] wrappers
├── state.rs            # App state (last params, recent files)
└── main.rs

Frontend (src/):

src/
├── components/
│   ├── Editor.tsx
│   ├── Preview.tsx
│   ├── Toolbar.tsx
│   ├── ParameterModal.tsx
│   └── PrinterDialog.tsx
├── hooks/
│   ├── useDocument.ts
│   └── usePreview.ts
└── lib/
    └── tauri.ts        # Typed invoke wrappers

---

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 desktop application with a **web-based UI** (Tauri) and a **Rust backend** that owns parsing, rendering, file I/O, and printer communication.
6
7```
8┌──────────────────────────────────────────────────────────────────┐
9│ Application │
10├────────────────────────────┬─────────────────────────────────────┤
11│ UI Layer │ Core Layer (Rust) │
12│ (TypeScript / Tauri WebView) │
13│ │ │
14│ DocumentEditor ───────────┼──► parse_dsl() → Document AST │
15│ PreviewPane ◄─────────────┼─── render_preview(ast, width) │
16│ SettingsPanel │ │
17│ ParameterDialog │ │
18│ PrinterPicker │ │
19│ │ │
20│ File menu ────────────────┼──► load_pos() / save_pos() │
21│ Print button ─────────────┼──► list_printers() │
22│ │ print_document(ast, params, dev) │
23└────────────────────────────┴─────────────────────────────────────┘
24 │
25 ┌─────────────────┼─────────────────┐
26 ▼ ▼ ▼
27 Preview bitmap ESC/POS bytes .pos JSON file
28```
29
30---
31
32## Modules (Rust crate layout)
33
34```
35posprint-core/ # Library — no UI, unit-testable
36├── dsl/
37│ ├── lexer.rs # Tokenize source
38│ ├── parser.rs # Build AST
39│ └── ast.rs # Document, Block, Inline, Directive nodes
40├── render/
41│ ├── preview.rs # Layout for UI (lines, images, barcode placeholders)
42│ └── escpos.rs # AST → ESC/POS byte buffer
43├── params/
44│ ├── collect.rs # Find unique ${Name} tokens
45│ └── substitute.rs # Apply user values before render/print
46├── io/
47│ └── pos_file.rs # Serde types, load/save
48└── print/
49 ├── discover.rs # Enumerate serial / USB / BT devices
50 ├── transport.rs # Trait: write(bytes), read optional status
51 └── pipeline.rs # substitute → escpos → transport
52
53posprint-app/ # Tauri binary
54├── commands/ # #[tauri::command] wrappers
55├── state.rs # App state (last params, recent files)
56└── main.rs
57```
58
59Frontend (`src/`):
60
61```
62src/
63├── components/
64│ ├── Editor.tsx
65│ ├── Preview.tsx
66│ ├── Toolbar.tsx
67│ ├── ParameterModal.tsx
68│ └── PrinterDialog.tsx
69├── hooks/
70│ ├── useDocument.ts
71│ └── usePreview.ts
72└── lib/
73 └── tauri.ts # Typed invoke wrappers
74```
75
76---
77
78## Data flow
79
80### Edit loop (live preview)
81
821. User types in editor → debounced (e.g. 150 ms) invoke `preview_document(source, settings)`.
832. Core parses DSL → AST (or returns parse errors with line/col).
843. Core renders preview model: text lines, image refs, barcode/QR placeholders sized to page width.
854. UI displays preview scaled to panel width (auto) or fixed mm width.
86
87### Save / load
88
891. **Save:** UI sends `{ metadata, body }` → `save_pos(path)` → JSON on disk.
902. **Load:** `load_pos(path)` → populate editor and settings.
91
92### Print
93
941. User clicks Print → `collect_parameters(ast)` → unique sorted names.
952. UI shows modal; pre-fill from `last_print_params` in app state.
963. On confirm → `print_document(ast, params, printer_id)`.
974. Core: substitute → build ESC/POS → open transport → write bytes → cut (if configured).
98
99---
100
101## Key types (conceptual)
102
103```rust
104struct Document {
105 blocks: Vec<Block>,
106}
107
108enum Block {
109 Paragraph { inlines: Vec<Inline>, align: Align },
110 Heading { level: u8, text: String },
111 Rule,
112 Image { src: String, width: ImageWidth }, // src may be ${Param}
113 Barcode { symbology: BarcodeKind, data: String, height: u8 },
114 Qr { data: String, size: QrSize },
115 Feed { lines: u8 },
116 Cut,
117}
118
119struct PosFile {
120 version: u32,
121 metadata: Metadata,
122 body: String,
123}
124
125struct Metadata {
126 title: Option<String>,
127 page_width_mm: f32, // 58, 80, etc.
128 preview_mode: PreviewMode, // AutoScale | Fixed
129 codepage: Option<String>,
130 cut_after_print: bool,
131}
132
133struct PrinterDevice {
134 id: String, // stable key for session
135 name: String,
136 transport: TransportKind,
137 // ...
138}
139```
140
141---
142
143## Tauri commands (IPC surface)
144
145| Command | Input | Output |
146|---------|-------|--------|
147| `parse_document` | `body: string` | `{ ast \| errors }` |
148| `preview_document` | `body, metadata` | `PreviewModel` |
149| `collect_parameters` | `body` | `string[]` (unique, sorted) |
150| `save_pos` | `path, PosFile` | `Result<()>` |
151| `load_pos` | `path` | `PosFile` |
152| `list_printers` | — | `PrinterDevice[]` |
153| `print_document` | `body, metadata, params, printer_id` | `Result<()>` |
154
155---
156
157## Preview vs print fidelity
158
159| Aspect | Preview | Print |
160|--------|---------|-------|
161| Text font | UI monospace, scaled | Printer built-in font |
162| Line width | Computed from `page_width_mm` | ESC/POS dot width |
163| Images | Resized bitmap in canvas | Raster ESC/POS |
164| Barcodes | SVG/canvas placeholder | Native printer barcode commands |
165| Alignment | CSS / canvas | ESC/POS justify commands |
166
167Both paths share the **same AST and substitution**; preview and print each have their own backend (preview renderer vs `escpos` encoder).
168
169---
170
171## State persistence
172
173| Data | Storage |
174|------|---------|
175| Recent files | App config (Tauri `app_data_dir`) |
176| Last parameter values | `params.json` keyed by template path or global |
177| Window layout | Optional, Tauri store |
178| Selected printer | Per-machine preference |
179
180---
181
182## Testing strategy
183
184| Layer | Approach |
185|-------|----------|
186| DSL parser | Unit tests + snapshot fixtures |
187| Parameter collect/substitute | Unit tests |
188| ESC/POS encoder | Byte snapshot tests |
189| Preview layout | Snapshot images (optional) |
190| Printer I/O | Manual hardware matrix; mock `Transport` trait in CI |
191| UI | Component tests; E2E with mocked Tauri commands |
192
193---
194
195## Build and release
196
197- **CI:** GitHub Actions — `cargo test`, `cargo clippy`, frontend lint, build Windows + Linux artifacts.
198- **Artifacts:** `.msi` or `.exe` (Windows), `.deb` / AppImage (Linux).
199- **Versioning:** Semver; `.pos` `version` field for file format migrations.
200
201See [PRINTING.md](PRINTING.md) for the device layer and [DSL-SPEC.md](DSL-SPEC.md) for language details.