Repository navigation
Architecture
vibecoder880 edited this page Nov 19, 2026
·
1 revision
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.
┌───────────────────────────── 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.)
/
├── 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
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.
- 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). - Pipeline emits progress via a callback; the shell turns it into
diff://progressevents ({job_id, stage, percent}) — stagesextract → ocr → align → diff → enrich, terminaldone/failed/cancelled. Cancel is a flag checked at stage boundaries (cancel_diff). - Extraction produces two
DocumentModels; OCR may append provenance-marked blocks. - Alignment pairs blocks (anchors → NW → move repair); word diff produces inline spans; heuristics attach flags + severity + audit entries.
- The finished
DiffResultis persisted (fire-and-forget) to SQLite and served viaget_diff;session-<id>ids hydrate history rows. - Optional:
explain_changeresolves the change, picks the first present model, ensures the loopback sidecar, streamsllm://tokenevents, finishes withllm://done(summary/impact). It cannot alter the result. -
export_reportrenders HTML/Markdown to a validated path.
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 |