how to contribute patterns and conventions

Patterns and conventions

QA Scribe uses Rust-owned domain and persistence logic, typed Tauri commands, generated TypeScript bindings, and action-factory-based React workflows. Product terminology follows CONTEXT.md.

Naming

Use Session, Entry, Evidence, Finding, Testware, Draft, AI Run, Generation Context, and Record. Avoid old terms called out in CONTEXT.md, such as Project, Notebook, Artifact, Item, Proof, or AI output.

Validation and ownership

Domain validation is handled in crates/qa-scribe-core/src/domain/validation.rs and service modules under crates/qa-scribe-core/src/services/session_service. Cross-session ownership is guarded by service methods such as row-in-session checks rather than frontend assumptions.

Error handling

Core methods return QaScribeError from crates/qa-scribe-core/src/error.rs. Tauri commands map those errors through src-tauri/src/commands/error.rs into structured frontend-facing variants.

Bridge contract

src-tauri/src/specta_bindings.rs registers commands and exports TypeScript bindings. Frontend code imports wrappers from frontend/src/tauri.ts and stable command helpers from frontend/src/tauriCommands.ts. Avoid hand-writing DTO shapes when they already exist in frontend/src/bindings.ts.

Frontend state

frontend/src/app/useAppController.ts owns the app workflow context and delegates operations to action factories. Views receive props from frontend/src/app/AppShell.tsx and should avoid duplicating backend orchestration.

Local-first AI

Generation is always explicit and user-triggered. Provider authentication belongs to local CLIs. Core prompt and response logic lives in crates/qa-scribe-core/src/generation, while Tauri process execution lives in src-tauri/src/commands/ai.