# Language and platform choice

## Requirements driving the decision

| Requirement | Technical implication |
|-------------|----------------------|
| Windows + Linux binaries | Cross-compile friendly toolchain, native I/O |
| Raw USB / serial / Bluetooth | Low-level device access, not browser-only |
| ESC/POS byte generation | Binary buffers, barcode/image encoding |
| Live preview UI | Responsive editor + rendered preview |
| Small distributable | Avoid heavy runtime (no full JVM, prefer no Chromium if possible) |
| Long-term maintainability | Strong typing, good deps for hardware |

---

## Candidates evaluated

### Rust + Tauri 2 (recommended)

| Pros | Cons |
|------|------|
| Excellent ESC/POS ecosystem (`escpos`, `nusb`, `serialport`) | Rust learning curve |
| Tauri 2: small binaries, web UI for editor | Two languages (Rust + TS) |
| Proven pattern for serial/USB desktop tools | WebView rendering for preview |
| First-class Windows + Linux support | |
| `serde` for `.pos` files | |

**Verdict:** Best fit. Hardware logic stays in Rust; React/Svelte/Vue handles editor UX.

### Rust + egui / iced (native UI)

| Pros | Cons |
|------|------|
| Single language, single binary | Editor UX more work (no Monaco/CodeMirror out of the box) |
| No WebView dependency | Syntax highlighting needs extra crates |
| Fast iteration for tools | Less familiar to web developers |

**Verdict:** Strong alternative if minimizing dependencies matters more than rich editor UX.

### C# + Avalonia

| Pros | Cons |
|------|------|
| Good desktop UI | USB/BT raw I/O less ergonomic than Rust |
| Cross-platform .NET | Larger runtime |
| Familiar if team is .NET | ESC/POS libs thinner than Rust |

**Verdict:** Viable if the team is already .NET-heavy.

### Go + Fyne / Wails

| Pros | Cons |
|------|------|
| Simple deployment | Weaker ESC/POS and USB ecosystem |
| Fast compile | Fyne UI less polished for split editor/preview |

**Verdict:** Possible but fighting the ecosystem for printer I/O.

### Python + PyQt / PySide

| Pros | Cons |
|------|------|
| Rapid prototyping | Packaging on Windows/Linux painful |
| `python-escpos`, `pyserial` exist | GIL, dependency hell in frozen binaries |

**Verdict:** Good for a throwaway prototype, poor for a shipped product.

### Electron + native Node addon

| Pros | Cons |
|------|------|
| Best editor UX (Monaco) | Large bundle (~150 MB+) |
| `serialport` npm package | Native addon build complexity per platform |

**Verdict:** Overkill footprint unless team is JS-only.

### C++ + Qt

| Pros | Cons |
|------|------|
| Mature, fast | Slowest development velocity |
| Qt Serial Port | ESC/POS mostly roll-your-own |

**Verdict:** Over-engineered for a *small* application.

---

## Decision (updated)

### Selected: **Rust + egui (eframe)** — single-language, minimal dependencies

See [ARCHITECTURE.md](ARCHITECTURE.md) for the current layout.

### Previously considered: **Rust (core) + Tauri 2 + TypeScript (UI)**

```
┌─────────────────────────────────────────┐
│  Frontend (TypeScript + React/Svelte)   │
│  - CodeMirror/Monaco editor             │
│  - Preview canvas (width-scaled)        │
│  - Parameter modal, printer picker        │
└─────────────────┬───────────────────────┘
                  │ Tauri commands / events
┌─────────────────▼───────────────────────┐
│  Rust backend                           │
│  - DSL parse → AST                      │
│  - Preview layout + ESC/POS encode      │
│  - Printer discovery (serial, USB, BT)  │
│  - `.pos` serde                         │
└─────────────────────────────────────────┘
```

#### Rust crates (planned)

| Crate | Role |
|-------|------|
| `escpos` | ESC/POS commands, barcodes, QR, raster |
| `serialport` | USB-serial / COM ports |
| `nusb` or `rusb` | USB printer class (bulk) |
| `serde` + `serde_json` | `.pos` file format |
| `image` | Decode/resize images for raster print |
| `tauri` 2.x | App shell, IPC |

#### Frontend (planned)

| Library | Role |
|---------|------|
| CodeMirror 6 or Monaco | Syntax-aware editor |
| Vite + React (or Svelte) | UI framework |
| Tailwind or similar | Layout |

### Fallback: **Rust + egui**

Choose this if you want a single-language codebase and can accept a simpler text editor (egui text edit + optional syntect highlighting).

---

## Platform-specific notes

### Windows

- USB-serial: `COMx` via `serialport` crate
- USB printer class: `escpos` `usbprint` feature (uses `usbprint.sys`, no Zadig)
- Bluetooth SPP: paired devices as COM ports; discovery via Windows APIs (later phase)
- Build: MSVC toolchain, WiX or NSIS for installer

### Linux

- USB-serial: `/dev/ttyUSB*`, `/dev/ttyACM*` — user must be in `dialout` group
- USB printer class: `nusb` + udev rules optional for non-root
- Bluetooth: BlueZ, `/dev/rfcomm*` after binding
- Build: `cargo deb` / AppImage via Tauri bundler

---

## Decision record

| Decision | Choice | Rationale |
|----------|--------|-----------|
| Core language | **Rust** | ESC/POS + USB/serial ecosystem |
| UI shell | **Tauri 2** | Small binary, modern editor UX |
| UI language | **TypeScript** | Editor component ecosystem |
| Print protocol | **ESC/POS** | De facto POS standard |
| MVP transport | **USB-serial** | Highest compatibility, lowest risk |

This decision should be revisited only if the implementing team has strong expertise elsewhere (e.g. Avalonia) *and* accepts additional printer I/O work.
