Skip to content

Architecture

vibecoder880 edited this page Nov 19, 2026 · 1 revision

Architecture

DiffLens is a Tauri 2 desktop app: a plain Rust library (difflens-core) that does all the work, a thin Tauri shell (src-tauri) exposing IPC commands and persistence, and a React 19 frontend (src). The core has no UI-framework ties and is fully testable headless with cargo test.

Component diagram

┌───────────────────────────── DiffLens (Tauri 2) ─────────────────────────────┐
│                                                                              │
│  React 19 + Tailwind + TanStack Router        src-tauri (thin shell)         │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────┐   ┌──────────────────────┐  │
│  │ Home/wizard  │  │ Diff report  │  │ Downloads│  │ commands.rs (IPC)    │  │
│  │ Settings     │  │ + detail     │  │ manager │──▶│ state.rs (sqlite     │  │
│  │ History      │  │ drawer       │  │ (only   │   │ session store)       │  │
│  └──────┬───────┘  └──────┬───────┘  │ egress  │   └──────────┬───────────┘  │
│         │                 │          │ in UI)  │              │              │
└─────────┼─────────────────┼──────────┴─────────┘──────────────┼──────────────┘
          ▼                 ▼                                   ▼
┌─────────────────────── difflens-core (Rust library) ─────────────────────────┐
│                                                                              │
│  extract/ ──▶ diff/ ──▶ align/ ──▶ heuristic/ ──▶ report/                    │
│  pdf (PDFium)  similar    e5-small      money/date/     HTML/Markdown         │
│  docx (zip+roxmltree)    semantic      percent/duration  export + audit      │
│  xlsx (calamine)         3-pass      rules (deterministic)  trail            │
│  pptx / txt                                                        │         │
│                                                                    ▼         │
│  embeddings/ (ort + ONNX e5)   llm/ (llama-server sidecar, loopback)         │
│  ocr/ (optional Tesseract CLI) store/ (rusqlite sessions)                    │
│                                                                              │
│  download/ — the ONLY module allowed to touch the network                    │
│  (manifest-pinned URLs, SHA-256 verified; enforced by scripts/audit-egress.sh│
│   and the egress-audit CI job)                                               │
└──────────────────────────────────────────────────────────────────────────────┘

(ASCII is used deliberately so it renders everywhere — GitHub wikis do not reliably render mermaid.)

Workspace layout

/
├── core/                  # difflens-core (the Rust library; MSRV 1.88)
│   └── src/
│       ├── extract/       # pdf / docx / xlsx / pptx / txt → DocumentModel (+ zip budgets)
│       ├── align/         # anchors.rs, needleman.rs, 3-pass orchestration
│       ├── diff/          # similar-based word diff, stats
│       ├── heuristic/     # entities.rs, deltas.rs, severity.rs, labels.rs (i18n keys)
│       ├── embeddings/    # Embedder trait, ort e5 (feature "embeddings-ort"), fake hash embedder
│       ├── llm/           # sidecar.rs (llama-server lifecycle), client.rs (SSE), explain.rs
│       ├── download/      # DownloadManager, manifest.rs, archive.rs — the only egress
│       ├── ocr/           # detect.rs, rasterize.rs, engine.rs (Tesseract path)
│       ├── store/         # rusqlite session history (WAL, parameterized queries)
│       ├── report/        # html.rs / markdown.rs exporters + audit trail
│       └── pipeline.rs    # extract → ocr → align → diff → enrich
├── src-tauri/             # thin shell: commands.rs (IPC), state.rs (jobs, sqlite handle)
├── src/                   # React 19 + TypeScript frontend
│   ├── routes/            # Home.tsx, Diff.tsx, Downloads.tsx, Settings.tsx
│   ├── components/        # compare/ diff/ llm/ history/ ui/
│   ├── lib/               # tauri.ts (typed invoke), i18n, prefs, theme
│   └── i18n/              # en.json / vi.json (parity-tested)
├── scripts/               # fetch-pdfium.sh, fetch-models.sh, audit-egress.sh, export-labels.mjs
└── resources/manifests/   # llm-manifest.json — the only allowed download URLs

Tech stack (decision table)

From the v1 stack selection (Nov 2026), all versions as pinned in the repo:

Component Chosen Version License
Desktop framework Tauri 2 2.12.6 MIT OR Apache-2.0
PDF extraction pdfium-render + pinned PDFium build 0.9.5 / chromium 8165 MIT OR Apache-2.0 / BSD-3
DOCX/PPTX parsing zip + roxmltree (own parser) 9.7.0 / 0.21.2 MIT / MIT OR Apache-2.0
XLSX reading calamine 0.38.0 MIT
Diff engine similar (Myers/Patience, inline) 3.2.1 Apache-2.0
Embeddings runtime ort (ONNX Runtime bindings) 2.0.0-rc.15 MIT OR Apache-2.0
Embedding model Xenova/multilingual-e5-small ONNX (118M params, 384-dim) pinned commit MIT
Tokenization tokenizers (HF) + mean pooling 0.23.2 Apache-2.0
LLM server llama.cpp llama-server sidecar b12503 MIT
Explanation models Qwen3-4B-Instruct-2507 / Qwen2.5-3B GGUF Q4_K_M current Apache-2.0
OCR Tesseract CLI (detected, not bundled) 5.x Apache-2.0
Persistence rusqlite (bundled SQLite) 0.32.1 MIT / public-domain SQLite
HTTP (download only) ureq 2.12.1 MIT OR Apache-2.0
Frontend React 19 + TypeScript + Vite + Tailwind CSS 4 19.3.1 / 8.3.8 / 4.3.5 MIT (TypeScript: Apache-2.0)
UI state/routing TanStack Query / Router / Virtual 5.108.0 / 1.170.46 / 3.14.26 MIT
i18n i18next + react-i18next 27.1.5 / 18.0.2 MIT

No AGPL/GPL components anywhere; full attributions in THIRD-PARTY-NOTICES.md.

Data flow (one comparison)

  1. UI run_diff(old, new, ocr?) → shell validates both paths (existing regular files) → job registered (job-* id) → pipeline runs on the blocking pool (a long diff cannot starve the async runtime).
  2. Pipeline emits progress via a callback; the shell turns it into diff://progress events ({job_id, stage, percent}) — stages extract → ocr → align → diff → enrich, terminal done/failed/cancelled. Cancel is a flag checked at stage boundaries (cancel_diff).
  3. Extraction produces two DocumentModels; OCR may append provenance-marked blocks.
  4. Alignment pairs blocks (anchors → NW → move repair); word diff produces inline spans; heuristics attach flags + severity + audit entries.
  5. The finished DiffResult is persisted (fire-and-forget) to SQLite and served via get_diff; session-<id> ids hydrate history rows.
  6. Optional: explain_change resolves the change, picks the first present model, ensures the loopback sidecar, streams llm://token events, finishes with llm://done (summary/impact). It cannot alter the result.
  7. export_report renders HTML/Markdown to a validated path.

Tauri command/event surface

Exact IPC surface (mirrored by the fully-typed src/lib/tauri.ts):

Command Signature (abridged) Purpose
run_diff (old_path, new_path, ocr_enabled?) → JobSnapshot start a diff job
get_diff (job_id) → JobSnapshot? poll snapshot; session-* ids hydrate history
cancel_diff (job_id) → bool flag cancel; honored at stage boundaries
list_sessions / get_session / delete_session standard CRUD history management
export_report (id, format: "html"|"md", target_path, lang?) → bytes write standalone report
ocr_status () → {available, binary, langs, has_vie} OCR availability snapshot
llm_status () → {server_tag, server_installed, server_on_path, server_running, models[]} Downloads screen snapshot
llm_install_server () → job_id (server-) download+extract pinned llama-server
llm_download_model (model_id) → job_id (model-) download GGUF (SHA-256 gated)
explain_change (diff_job_id, change_id, lang) → job_id (explain-*) stream one explanation
llm_cancel (job_id) → bool cancel explain or download
Event Payload Emitted during
diff://progress {job_id, stage, percent} pipeline stages + terminal
llm://download {job_id, kind: "server"|"model", model_id, state, bytes_done, bytes_total?, percent, error?} server/model installs
llm://token {job_id, delta} streaming explanation
llm://done {job_id, ok, cancelled, summary?, impact?, error?, elapsed_ms} explanation terminal

Clone this wiki locally