# Architecture

This page is for contributors and AI agents getting oriented in the codebase.

## Stack

- Desktop shell: Tauri 2
- Backend: Rust
- Frontend: React, TypeScript, Vite
- Parsers: tree-sitter grammars for TypeScript/JavaScript, Rust, Go, Python, Java, C#, Kotlin, and Swift
- Git access: `git2`
- Watcher: `notify` and `notify-debouncer-full`
- Tests: Rust unit tests, Playwright web E2E, Playwright native Tauri E2E; CI runs cargo test + clippy (Windows) and tsc + web E2E (Ubuntu)

## Backend Flow

1. `src-tauri/src/lib.rs` exposes Tauri commands; `main.rs` routes `check` to the headless CLI first.
2. `git.rs` discovers repo roots, branch names, changed files (vs `HEAD` or any baseline commit), and file contents at any rev.
3. `session.rs` resolves the per-repo baseline (`resolve_baseline`), orchestrates file analysis, and assembles `SessionData` (including per-node review marking).
4. `parse.rs` parses supported source languages (`Lang`) into a small `Parsed` tree.
5. `diff.rs` compares before/after parsed trees and assigns stable node IDs.
6. `rules.rs` evaluates security heuristics; `heuristics.rs` walks nodes and attaches flags.
7. `deps_diff.rs` renders a drifted package.json's dependency/script sections as drift nodes with lockfile-aware rules.
8. `watcher.rs` keeps a debounced live session cache, re-resolves the baseline on git-state changes, and emits `drift://updated`.
9. `store.rs` persists per repo: dismissed flags, reviewed fingerprint, baseline choice, trust point, and per-node review hashes.
10. `report.rs` renders Markdown or JSON exports.
11. `cli.rs` implements `diff-drift check` — read-only headless analysis with severity exit codes.

## Frontend Flow

1. `src/lib/session.ts` wraps Tauri commands and provides browser-mode mock behavior.
2. `src/App.tsx` owns app state, repo opening, live updates, selection, triage, review, and export.
3. `src/components/Toolbar.tsx` renders repo, branch, counts, and review actions.
4. `src/components/Sidebar.tsx` renders session counts and analyzed files.
5. `src/components/Center.tsx` renders the selected file's node tree.
6. `src/components/NodeCard.tsx` renders node state, diff body, and flag chips.
7. `src/components/RightPanel.tsx` renders active and dismissed flags.

## Data Contract

The shared TypeScript shape is in `src/types.ts`; the Rust mirror is in `src-tauri/src/model.rs`.

Important objects:

- `SessionData`: full payload sent to React; carries `schemaVersion` (currently 4 — bump it when the shape changes in ways consumers could misread).
- `Session`: repo, branch, baseline (spec/label/trust point), counts, review progress, reviewed state.
- `FileEntry`: analyzed file metadata, review progress, and node tree.
- `AstNode`: parsed structure, before/after lines, and per-node `reviewed` state.
- `Flag`: heuristic finding attached to a node.

Keep these contracts in sync. If a field changes in Rust, update TypeScript, mock data, reports, tests — and `SCHEMA_VERSION` in `model.rs` when the change is breaking.

## Design Constraints

- Stay local-only. Do not add telemetry, model calls, or remote repo uploads.
- Prefer focused heuristics over broad static-analysis claims.
- Keep docs and UI honest about scope: structural drift for supported source languages plus package.json dependency drift; heuristic flags are strongest for JS/TS and package drift.
- The headless `check` command stays read-only: it must never mutate triage state.
- Make surgical changes. Avoid large rewrites unless a specific bug requires them.