How nirjxr26/trace works
Trace is a local-first forensic case-management application. Investigators enter through the CLI, interactive shell, or fullscreen TUI; case commands validate lifecycle operations, allocate safe case numbers, persist changes transactionally, and present case dossiers. Audit provides a separate signed, verifiable custody ledger with export and anchoring capabilities. The repository also contains update and recovery workflows. The tree and excerpts support the primary entry points and several service/repository relationships; unsampled feature internals are represented at their enclosing directories, and uncertain wiring is omitted.
Main entry points: shell.py Interactive shell · shell_handler.py Audit commands · service.py Case lifecycle · main.py Trace CLI
Components 23
User interfaces
- Trace CLI
src/trace_core/cli/main.py - Interactive shell
src/trace_core/cli/shell.py - Fullscreen TUI
src/trace_core/tui/app.py - Case commands
src/trace_core/cases/shell_handler.py - Audit commands
src/trace_core/audit/shell_handler.py - Update commands
src/trace_core/updates/shell_handler.py
Case management
- Case lifecycle
src/trace_core/cases/service.py - Case rules
src/trace_core/cases/domain.py - Case repository
src/trace_core/cases/repository.py - Case screens
src/trace_core/tui/screens/cases.py
Audit custody
- Audit service
src/trace_core/audit/service.py - Chain and events
src/trace_core/audit/domain.py - Audit repository
src/trace_core/audit/repository.py - Audit export
src/trace_core/audit/exporter.py - Audit verification
src/trace_core/audit/verifier.py - Key vault
src/trace_core/audit/vault.py
Platform and updates
- Update workflows
src/trace_core/updates/commands.py - Release checking
src/trace_core/updates/checker.py - Update history
src/trace_core/updates/service.py - Unit of work
src/trace_core/core/service.py - Database sessions
src/trace_core/core/database/session.py
Other components
- Investigator
- Configured database
Connections 24
- Investigator → Trace CLI: invokes
- Trace CLI → Interactive shell: launches by default
- Investigator → Fullscreen TUI: opens TUI
- Trace CLI → Fullscreen TUI: launches
- Interactive shell → Case commands: dispatches commands
- Interactive shell → Audit commands: dispatches commands
- Interactive shell → Update commands: dispatches commands
- Case commands → Case lifecycle: executes lifecycle
- Case lifecycle → Case rules: validates transitions
- Case lifecycle → Case repository: reads and writes
- Case lifecycle → Unit of work: runs transaction
- Audit commands → Audit service: handles audit actions
- Audit service → Audit repository: reads and appends
- Audit repository → Chain and events: builds chain records
- Audit repository → Key vault: signs records
- Audit commands → Audit export: exports ledger
- Audit commands → Audit verification: verifies ledger
- Update commands → Release checking: checks releases
- Update commands → Update history: lists history
- Update workflows → Release checking: resolves releases
- Update history → Unit of work: records history
- Unit of work → Database sessions: opens session
- Database sessions → Configured database: connects
- Fullscreen TUI → Case screens: composes case screen