Development Architecture and Contributing

Stack

• React 19 + TypeScript + Vite;
• Tauri 2 + Rust;
• SQLite schema 27;
• Vitest, architecture/source/UX-DATA gates, Rust tests and Clippy;
• GitHub Actions for CI and Windows/Linux packaging.

Modular monolith

The project remains one desktop application and one repository. Feature modules expose public entry points; domain and persistence contracts keep provider, session, Training, Research and AI Center rules separate.

Current migration chain

src-tauri/src/migrations.rs is the ordered registry through 027. The accepted current-epoch transitions are exact-green 23→24, 24→25, 25→26 and 26→27. Do not add a migration without matching registry, checksums, compatibility tests and documentation.

Provider boundaries

• Rust performs one physical provider attempt.
• TypeScript owns transport retry.
• Analytical output recovery is a new logical request.
• Domain recovery remains owned by the relevant feature.
• Provider-native continuation is validated, bounded, persisted outside transcript text and replayed only with a compatible fingerprint.

Required checks

npm ci
npm run verify:source
npm run verify:ux-data
npm run verify:architecture
npm run typecheck
npm test -- --run
npm run build
cargo test --manifest-path src-tauri/Cargo.toml --all-targets --locked
cargo clippy --manifest-path src-tauri/Cargo.toml --all-targets --locked -- -D warnings

Release rules

Windows and Linux release workflows publish from main. Test artifacts do not become public releases automatically. Keep Cargo.lock committed and do not let CI modify or push repository content.

Contribution invariants

• do not leak Reveal into blind context;
• do not rewrite sealed/frozen history;
• do not transfer Viewer Learning between identities;
• do not place continuation payloads in ordinary exports or logs;
• do not bypass named SQL writes or native credential binding;
• update living documentation with behavior changes while leaving historical reports intact.