# andreipath26/whaxon-ai-forensics architecture

> Architecture diagram of the GitHub repository andreipath26/whaxon-ai-forensics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/andreipath26/whaxon-ai-forensics
- Repository: https://github.com/andreipath26/whaxon-ai-forensics

## Overview

WHAXON is a defensive security-assessment application: operators define authorized scope, run supported assessments, interpret and validate observations, preserve evidence, report results, and retest remediation. The CLI, browser API, and optional TUI/desktop interfaces expose a shared core, while Engine V2 adds durable, approval-bound workflow plans and run requests. The graph combines documented product stages with source-index-supported connections; unsampled subsystems are represented by their exact directories, and uncertain internal links are omitted.

Main entry points: [`src/whaxon/core/__init__.py`](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/__init__.py) (Shared core), [`src/whaxon/interfaces/web/server.py`](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/interfaces/web/server.py) (Web workspace/API), [`src/whaxon/core/runner.py`](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/runner.py) (Assessment runner), [`src/whaxon/core/workflow.py`](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/workflow.py) (Workflow contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Operator interfaces"]
  node_cli["Command-line<br/>[cli.py]"]
  node_web["Web workspace/API<br/>[server.py]"]
  node_tui["Terminal interface<br/>[main.py]"]
  node_desktop["Desktop shell<br/>[app.py]"]
end

subgraph group_assessment["Assessment execution"]
  node_core["Shared core<br/>[__init__.py]"]
  node_scope["Scope and policy<br/>[scope.py]"]
  node_catalog["Tool catalog<br/>[catalog.py]"]
  node_runner["Assessment runner<br/>[runner.py]"]
  node_adapters["Tool adapters<br/>[base.py]"]
  node_recon["Recon services<br/>[recon_v2.py]"]
end

subgraph group_evidence["Evidence and reporting"]
  node_validator["Finding validation<br/>[validator.py]"]
  node_findings["Finding analysis<br/>[findings.py]"]
  node_store[("Assessment store<br/>[store.py]")]
  node_reports["Reports<br/>[report.py]"]
  node_retest["Remediation retesting<br/>[remediation.py]"]
end

subgraph group_engine["Workflow engine"]
  node_workflow["Workflow contracts<br/>[workflow.py]"]
  node_providers["Capability providers<br/>[providers.py]"]
  node_proposals["Plan proposals"]
  node_scheduler["Workflow scheduler<br/>[scheduler.py]"]
  node_worker["Workflow worker<br/>[worker.py]"]
end

subgraph group_ai["AI assistance"]
  node_ai["AI bridge<br/>[ai_bridge.py]"]
  node_llm["LLM provider<br/>[llm.py]"]
end

node_operator(("Operator"))
node_security_tools["External security tools"]
node_llm_service["LLM service"]

node_operator -->|"initiates assessment"| node_cli
node_cli -.->|"requests operations"| node_core
node_operator -->|"uses workspace"| node_web
node_web -->|"routes API calls"| node_core
node_operator -->|"uses terminal UI"| node_tui
node_tui -->|"uses shared core"| node_core
node_desktop -->|"embeds web UI"| node_web
node_core -->|"checks authorization"| node_scope
node_core -->|"loads catalog"| node_catalog
node_core -->|"orchestrates tools"| node_runner
node_runner -.->|"dispatches tools"| node_adapters
node_adapters -.->|"invokes tools"| node_security_tools
node_core -.->|"offers recon services"| node_recon
node_operator -->|"defines authorized scope"| node_scope
node_operator -->|"runs assessment"| node_runner
node_runner -->|"collects observations"| node_findings
node_findings -->|"validates supported cases"| node_validator
node_validator -.->|"preserves evidence"| node_store
node_findings -.->|"stores assessment data"| node_store
node_reports -->|"reads assessment data"| node_store
node_reports -->|"reads scope context"| node_scope
node_operator -->|"produces assessment report"| node_reports
node_operator -->|"retests remediation"| node_retest
node_web -->|"exposes workflow APIs"| node_workflow
node_cli -->|"offers workflow commands"| node_workflow
node_workflow -.->|"schedules plans"| node_scheduler
node_scheduler -.->|"dispatches tasks"| node_worker
node_proposals -->|"constructs plans"| node_workflow
node_proposals -->|"checks provider contracts"| node_providers
node_ai -->|"prepares reviewable plans"| node_proposals
node_ai -->|"uses LLM provider"| node_llm
node_llm -.->|"requests suggestions"| node_llm_service

click node_cli "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/cli.py"
click node_web "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/interfaces/web/server.py"
click node_tui "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/interfaces/tui/screens/main.py"
click node_desktop "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/interfaces/gui/app.py"
click node_core "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/__init__.py"
click node_scope "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/scope.py"
click node_catalog "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/catalog.py"
click node_runner "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/runner.py"
click node_adapters "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/adapters/base.py"
click node_recon "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/recon_v2.py"
click node_validator "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/validator.py"
click node_findings "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/findings.py"
click node_store "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/store.py"
click node_reports "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/report.py"
click node_retest "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/remediation.py"
click node_workflow "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/workflow.py"
click node_providers "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/providers.py"
click node_proposals "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/workflow_proposals.py"
click node_scheduler "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/scheduler.py"
click node_worker "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/worker.py"
click node_ai "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/ai_bridge.py"
click node_llm "https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/ai/providers/llm.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_web,node_tui,node_desktop toneBlue
class node_core,node_scope,node_catalog,node_runner,node_adapters,node_recon toneAmber
class node_validator,node_findings,node_store,node_reports,node_retest toneMint
class node_workflow,node_providers,node_proposals,node_scheduler,node_worker toneRose
class node_ai,node_llm,node_operator,node_security_tools,node_llm_service toneIndigo
```

## Components

### Operator interfaces

- [Command-line](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/cli.py): `src/whaxon/cli.py`
- [Web workspace/API](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/interfaces/web/server.py): `src/whaxon/interfaces/web/server.py`
- [Terminal interface](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/interfaces/tui/screens/main.py): `src/whaxon/interfaces/tui/screens/main.py`
- [Desktop shell](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/interfaces/gui/app.py): `src/whaxon/interfaces/gui/app.py`

### Assessment execution

- [Shared core](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/__init__.py): `src/whaxon/core/__init__.py`
- [Scope and policy](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/scope.py): `src/whaxon/core/scope.py`
- [Tool catalog](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/catalog.py): `src/whaxon/core/catalog.py`
- [Assessment runner](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/runner.py): `src/whaxon/core/runner.py`
- [Tool adapters](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/adapters/base.py): `src/whaxon/adapters/base.py`
- [Recon services](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/recon_v2.py): `src/whaxon/core/recon_v2.py`

### Evidence and reporting

- [Finding validation](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/validator.py): `src/whaxon/core/validator.py`
- [Finding analysis](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/findings.py): `src/whaxon/core/findings.py`
- [Assessment store](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/store.py): `src/whaxon/core/store.py`
- [Reports](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/report.py): `src/whaxon/core/report.py`
- [Remediation retesting](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/remediation.py): `src/whaxon/core/remediation.py`

### Workflow engine

- [Workflow contracts](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/workflow.py): `src/whaxon/core/workflow.py`
- [Capability providers](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/providers.py): `src/whaxon/core/providers.py`
- [Plan proposals](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/workflow_proposals.py): `src/whaxon/core/workflow_proposals.py`
- [Workflow scheduler](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/scheduler.py): `src/whaxon/core/scheduler.py`
- [Workflow worker](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/worker.py): `src/whaxon/core/worker.py`

### AI assistance

- [AI bridge](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/core/ai_bridge.py): `src/whaxon/core/ai_bridge.py`
- [LLM provider](https://github.com/andreipath26/whaxon-ai-forensics/blob/main/src/whaxon/ai/providers/llm.py): `src/whaxon/ai/providers/llm.py`

### Other components

- **Operator**
- **External security tools**
- **LLM service**

## Connections

- Operator → Command-line: initiates assessment (evidence: `src/whaxon/cli.py`)
- Command-line → Shared core: requests operations
- Operator → Web workspace/API: uses workspace (evidence: `README.md`)
- Web workspace/API → Shared core: routes API calls (evidence: `src/whaxon/interfaces/web/server.py`)
- Operator → Terminal interface: uses terminal UI (evidence: `README.md`)
- Terminal interface → Shared core: uses shared core (evidence: `src/whaxon/interfaces/tui/app.py`)
- Desktop shell → Web workspace/API: embeds web UI (evidence: `src/whaxon/interfaces/gui/app.py`)
- Shared core → Scope and policy: checks authorization (evidence: `src/whaxon/core/__init__.py`)
- Shared core → Tool catalog: loads catalog (evidence: `src/whaxon/core/__init__.py`)
- Shared core → Assessment runner: orchestrates tools (evidence: `src/whaxon/core/__init__.py`)
- Assessment runner → Tool adapters: dispatches tools
- Tool adapters → External security tools: invokes tools
- Shared core → Recon services: offers recon services (evidence: `src/whaxon/core/__init__.py`)
- Operator → Scope and policy: defines authorized scope (evidence: `README.md`)
- Operator → Assessment runner: runs assessment (evidence: `README.md`)
- Assessment runner → Finding analysis: collects observations (evidence: `README.md`)
- Finding analysis → Finding validation: validates supported cases (evidence: `README.md`)
- Finding validation → Assessment store: preserves evidence
- Finding analysis → Assessment store: stores assessment data
- Reports → Assessment store: reads assessment data (evidence: `src/whaxon/core/report.py`)
- Reports → Scope and policy: reads scope context (evidence: `src/whaxon/core/report.py`)
- Operator → Reports: produces assessment report (evidence: `README.md`)
- Operator → Remediation retesting: retests remediation (evidence: `README.md`)
- Web workspace/API → Workflow contracts: exposes workflow APIs (evidence: `src/whaxon/interfaces/web/server.py`)
- Command-line → Workflow contracts: offers workflow commands
- Workflow contracts → Workflow scheduler: schedules plans
- Workflow scheduler → Workflow worker: dispatches tasks
- Plan proposals → Workflow contracts: constructs plans (evidence: `src/whaxon/core/workflow_proposals.py`)
- Plan proposals → Capability providers: checks provider contracts (evidence: `src/whaxon/core/workflow_proposals.py`)
- AI bridge → Plan proposals: prepares reviewable plans (evidence: `src/whaxon/core/ai_bridge.py`)
- AI bridge → LLM provider: uses LLM provider (evidence: `src/whaxon/core/ai_bridge.py`)
- LLM provider → LLM service: requests suggestions