# nirjxr26/trace architecture

> Architecture diagram of the GitHub repository nirjxr26/trace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nirjxr26/trace
- Repository: https://github.com/nirjxr26/trace

## Overview

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: [`src/trace_core/cli/shell.py`](https://github.com/nirjxr26/trace/blob/main/src/trace_core/cli/shell.py) (Interactive shell), [`src/trace_core/audit/shell_handler.py`](https://github.com/nirjxr26/trace/blob/main/src/trace_core/audit/shell_handler.py) (Audit commands), [`src/trace_core/cases/service.py`](https://github.com/nirjxr26/trace/blob/main/src/trace_core/cases/service.py) (Case lifecycle), [`src/trace_core/cli/main.py`](https://github.com/nirjxr26/trace/blob/main/src/trace_core/cli/main.py) (Trace CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["Trace CLI<br/>[main.py]"]
  node_shell["Interactive shell<br/>[shell.py]"]
  node_tui["Fullscreen TUI<br/>[app.py]"]
  node_case_handler["Case commands<br/>[shell_handler.py]"]
  node_audit_handler["Audit commands<br/>[shell_handler.py]"]
  node_update_handler["Update commands<br/>[shell_handler.py]"]
end

subgraph group_casework["Case management"]
  node_case_service["Case lifecycle<br/>[service.py]"]
  node_case_domain["Case rules<br/>[domain.py]"]
  node_case_repo["Case repository<br/>[repository.py]"]
  node_case_views["Case screens<br/>[cases.py]"]
end

subgraph group_custody["Audit custody"]
  node_audit_service["Audit service<br/>[service.py]"]
  node_audit_domain["Chain and events<br/>[domain.py]"]
  node_audit_repo["Audit repository<br/>[repository.py]"]
  node_audit_export["Audit export<br/>[exporter.py]"]
  node_audit_verify["Audit verification<br/>[verifier.py]"]
  node_audit_vault["Key vault<br/>[vault.py]"]
end

subgraph group_platform["Platform and updates"]
  node_update_commands["Update workflows<br/>[commands.py]"]
  node_update_checker["Release checking<br/>[checker.py]"]
  node_update_service["Update history<br/>[service.py]"]
  node_uow["Unit of work<br/>[service.py]"]
  node_db_session["Database sessions<br/>[session.py]"]
end

node_investigator(("Investigator"))
node_database[("Configured database")]

node_investigator -->|"invokes"| node_cli
node_cli -->|"launches by default"| node_shell
node_investigator -->|"opens TUI"| node_tui
node_cli -->|"launches"| node_tui
node_shell -->|"dispatches commands"| node_case_handler
node_shell -->|"dispatches commands"| node_audit_handler
node_shell -->|"dispatches commands"| node_update_handler
node_case_handler -->|"executes lifecycle"| node_case_service
node_case_service -->|"validates transitions"| node_case_domain
node_case_service -->|"reads and writes"| node_case_repo
node_case_service -->|"runs transaction"| node_uow
node_audit_handler -->|"handles audit actions"| node_audit_service
node_audit_service -->|"reads and appends"| node_audit_repo
node_audit_repo -->|"builds chain records"| node_audit_domain
node_audit_repo -->|"signs records"| node_audit_vault
node_audit_handler -->|"exports ledger"| node_audit_export
node_audit_handler -->|"verifies ledger"| node_audit_verify
node_update_handler -->|"checks releases"| node_update_checker
node_update_handler -->|"lists history"| node_update_service
node_update_commands -->|"resolves releases"| node_update_checker
node_update_service -->|"records history"| node_uow
node_uow -->|"opens session"| node_db_session
node_db_session -->|"connects"| node_database
node_tui -->|"composes case screen"| node_case_views

click node_cli "https://github.com/nirjxr26/trace/blob/main/src/trace_core/cli/main.py"
click node_shell "https://github.com/nirjxr26/trace/blob/main/src/trace_core/cli/shell.py"
click node_tui "https://github.com/nirjxr26/trace/blob/main/src/trace_core/tui/app.py"
click node_case_handler "https://github.com/nirjxr26/trace/blob/main/src/trace_core/cases/shell_handler.py"
click node_audit_handler "https://github.com/nirjxr26/trace/blob/main/src/trace_core/audit/shell_handler.py"
click node_update_handler "https://github.com/nirjxr26/trace/blob/main/src/trace_core/updates/shell_handler.py"
click node_case_service "https://github.com/nirjxr26/trace/blob/main/src/trace_core/cases/service.py"
click node_case_domain "https://github.com/nirjxr26/trace/blob/main/src/trace_core/cases/domain.py"
click node_case_repo "https://github.com/nirjxr26/trace/blob/main/src/trace_core/cases/repository.py"
click node_case_views "https://github.com/nirjxr26/trace/blob/main/src/trace_core/tui/screens/cases.py"
click node_audit_service "https://github.com/nirjxr26/trace/blob/main/src/trace_core/audit/service.py"
click node_audit_domain "https://github.com/nirjxr26/trace/blob/main/src/trace_core/audit/domain.py"
click node_audit_repo "https://github.com/nirjxr26/trace/blob/main/src/trace_core/audit/repository.py"
click node_audit_export "https://github.com/nirjxr26/trace/blob/main/src/trace_core/audit/exporter.py"
click node_audit_verify "https://github.com/nirjxr26/trace/blob/main/src/trace_core/audit/verifier.py"
click node_audit_vault "https://github.com/nirjxr26/trace/blob/main/src/trace_core/audit/vault.py"
click node_update_commands "https://github.com/nirjxr26/trace/blob/main/src/trace_core/updates/commands.py"
click node_update_checker "https://github.com/nirjxr26/trace/blob/main/src/trace_core/updates/checker.py"
click node_update_service "https://github.com/nirjxr26/trace/blob/main/src/trace_core/updates/service.py"
click node_uow "https://github.com/nirjxr26/trace/blob/main/src/trace_core/core/service.py"
click node_db_session "https://github.com/nirjxr26/trace/blob/main/src/trace_core/core/database/session.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_shell,node_tui,node_case_handler,node_audit_handler,node_update_handler toneBlue
class node_case_service,node_case_domain,node_case_repo,node_case_views,node_database toneAmber
class node_audit_service,node_audit_domain,node_audit_repo,node_audit_export,node_audit_verify,node_audit_vault toneMint
class node_update_commands,node_update_checker,node_update_service,node_uow,node_db_session toneRose
class node_investigator toneIndigo
```

## Components

### User interfaces

- [Trace CLI](https://github.com/nirjxr26/trace/blob/main/src/trace_core/cli/main.py): `src/trace_core/cli/main.py`
- [Interactive shell](https://github.com/nirjxr26/trace/blob/main/src/trace_core/cli/shell.py): `src/trace_core/cli/shell.py`
- [Fullscreen TUI](https://github.com/nirjxr26/trace/blob/main/src/trace_core/tui/app.py): `src/trace_core/tui/app.py`
- [Case commands](https://github.com/nirjxr26/trace/blob/main/src/trace_core/cases/shell_handler.py): `src/trace_core/cases/shell_handler.py`
- [Audit commands](https://github.com/nirjxr26/trace/blob/main/src/trace_core/audit/shell_handler.py): `src/trace_core/audit/shell_handler.py`
- [Update commands](https://github.com/nirjxr26/trace/blob/main/src/trace_core/updates/shell_handler.py): `src/trace_core/updates/shell_handler.py`

### Case management

- [Case lifecycle](https://github.com/nirjxr26/trace/blob/main/src/trace_core/cases/service.py): `src/trace_core/cases/service.py`
- [Case rules](https://github.com/nirjxr26/trace/blob/main/src/trace_core/cases/domain.py): `src/trace_core/cases/domain.py`
- [Case repository](https://github.com/nirjxr26/trace/blob/main/src/trace_core/cases/repository.py): `src/trace_core/cases/repository.py`
- [Case screens](https://github.com/nirjxr26/trace/blob/main/src/trace_core/tui/screens/cases.py): `src/trace_core/tui/screens/cases.py`

### Audit custody

- [Audit service](https://github.com/nirjxr26/trace/blob/main/src/trace_core/audit/service.py): `src/trace_core/audit/service.py`
- [Chain and events](https://github.com/nirjxr26/trace/blob/main/src/trace_core/audit/domain.py): `src/trace_core/audit/domain.py`
- [Audit repository](https://github.com/nirjxr26/trace/blob/main/src/trace_core/audit/repository.py): `src/trace_core/audit/repository.py`
- [Audit export](https://github.com/nirjxr26/trace/blob/main/src/trace_core/audit/exporter.py): `src/trace_core/audit/exporter.py`
- [Audit verification](https://github.com/nirjxr26/trace/blob/main/src/trace_core/audit/verifier.py): `src/trace_core/audit/verifier.py`
- [Key vault](https://github.com/nirjxr26/trace/blob/main/src/trace_core/audit/vault.py): `src/trace_core/audit/vault.py`

### Platform and updates

- [Update workflows](https://github.com/nirjxr26/trace/blob/main/src/trace_core/updates/commands.py): `src/trace_core/updates/commands.py`
- [Release checking](https://github.com/nirjxr26/trace/blob/main/src/trace_core/updates/checker.py): `src/trace_core/updates/checker.py`
- [Update history](https://github.com/nirjxr26/trace/blob/main/src/trace_core/updates/service.py): `src/trace_core/updates/service.py`
- [Unit of work](https://github.com/nirjxr26/trace/blob/main/src/trace_core/core/service.py): `src/trace_core/core/service.py`
- [Database sessions](https://github.com/nirjxr26/trace/blob/main/src/trace_core/core/database/session.py): `src/trace_core/core/database/session.py`

### Other components

- **Investigator**
- **Configured database**

## Connections

- 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