# aaa1234fdja/candix architecture

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

- Interactive diagram: https://gitdiagram.com/aaa1234fdja/candix
- Repository: https://github.com/aaa1234fdja/candix

## Overview

Candix is an authorization-first web security testing harness. Operators invoke scans through the CLI or API; the engine performs scope-aware preflight and reconnaissance, runs detectors over discovered endpoints, and optionally attempts gated proofs of impact. Findings feed a shared report model for multiple formats and delivery integrations. The README also documents fuzzing, scan comparison, playbooks, interactive interfaces, and a vulnerable lab. Relationships reflect excerpts, SOURCE INDEX references, and README claims; unsampled subsystem links are omitted where wiring is not shown.

Main entry points: [`candix/cli/commands.py`](https://github.com/aaa1234fdja/candix/blob/main/candix/cli/commands.py) (CLI commands), [`candix/engine.py`](https://github.com/aaa1234fdja/candix/blob/main/candix/engine.py) (Scan engine), [`candix/core/context.py`](https://github.com/aaa1234fdja/candix/blob/main/candix/core/context.py) (Scan context), [`candix/net/http.py`](https://github.com/aaa1234fdja/candix/blob/main/candix/net/http.py) (HTTP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Operator interfaces"]
  node_cli["CLI commands<br/>[commands.py]"]
  node_api["HTTP API<br/>[server.py]"]
end

subgraph group_scan["Scan runtime"]
  node_context["Scan context<br/>[context.py]"]
  node_scope["Authorization scope<br/>[scope.py]"]
  node_engine["Scan engine<br/>[engine.py]"]
  node_network["HTTP client<br/>[http.py]"]
  node_recon["Reconnaissance<br/>[crawler.py]"]
  node_endpoint["Endpoint model<br/>[endpoint.py]"]
end

subgraph group_assess["Assessment capabilities"]
  node_detectors["Detector framework<br/>[base.py]"]
  node_finding["Findings<br/>[finding.py]"]
  node_proof["Exploit verification<br/>[engine.py]"]
  node_fuzz["Mutation fuzzing<br/>[runner.py]"]
  node_playbooks["Verification playbooks<br/>[engine.py]"]
end

subgraph group_results["Results and delivery"]
  node_reportmodel["Report model<br/>[model.py]"]
  node_reportbuilder["Report rendering<br/>[builder.py]"]
  node_integrations["Result integrations<br/>[base.py]"]
end

subgraph group_support["Auxiliary workflows"]
  node_compare["Scan comparison<br/>[diff.py]"]
  node_repl["Interactive shell<br/>[repl.py]"]
  node_tui["Terminal dashboard<br/>[app.py]"]
  node_lab["Vulnerable lab<br/>[app.py]"]
end

node_operator(("Operator"))
node_target(("Authorized target"))
node_consumers(("Report consumers"))
node_delivery(("Notification services"))

node_operator -->|"invokes"| node_cli
node_cli -->|"starts scans"| node_engine
node_operator -.->|"submits jobs"| node_api
node_api -->|"runs scans"| node_engine
node_cli -->|"builds context"| node_context
node_api -->|"builds context"| node_context
node_context -->|"provides scope"| node_scope
node_context -->|"creates client"| node_network
node_engine -->|"preflights targets"| node_network
node_engine -->|"runs recon"| node_recon
node_recon -->|"fetches pages"| node_network
node_recon -->|"emits endpoints"| node_endpoint
node_engine -->|"runs detectors"| node_detectors
node_detectors -->|"yields findings"| node_finding
node_engine -->|"runs gated proofs"| node_proof
node_proof -->|"updates proofs"| node_finding
node_engine -->|"uses shared state"| node_context
node_finding -->|"populates report"| node_reportmodel
node_reportmodel -.->|"renders formats"| node_reportbuilder
node_reportbuilder -.->|"exports reports"| node_consumers
node_cli -.->|"runs fuzzing"| node_fuzz
node_cli -.->|"compares scans"| node_compare
node_cli -.->|"lists playbooks"| node_playbooks
node_cli -.->|"sends notifications"| node_integrations
node_integrations -.->|"delivers results"| node_delivery
node_operator -.->|"uses shell"| node_repl
node_operator -.->|"uses dashboard"| node_tui
node_cli -.->|"starts lab"| node_lab
node_network -.->|"sends requests"| node_target

click node_cli "https://github.com/aaa1234fdja/candix/blob/main/candix/cli/commands.py"
click node_api "https://github.com/aaa1234fdja/candix/blob/main/candix/api/server.py"
click node_context "https://github.com/aaa1234fdja/candix/blob/main/candix/core/context.py"
click node_scope "https://github.com/aaa1234fdja/candix/blob/main/candix/core/scope.py"
click node_engine "https://github.com/aaa1234fdja/candix/blob/main/candix/engine.py"
click node_network "https://github.com/aaa1234fdja/candix/blob/main/candix/net/http.py"
click node_recon "https://github.com/aaa1234fdja/candix/blob/main/candix/recon/crawler.py"
click node_endpoint "https://github.com/aaa1234fdja/candix/blob/main/candix/core/endpoint.py"
click node_detectors "https://github.com/aaa1234fdja/candix/blob/main/candix/detectors/base.py"
click node_finding "https://github.com/aaa1234fdja/candix/blob/main/candix/core/finding.py"
click node_proof "https://github.com/aaa1234fdja/candix/blob/main/candix/exploit/engine.py"
click node_fuzz "https://github.com/aaa1234fdja/candix/blob/main/candix/fuzz/runner.py"
click node_playbooks "https://github.com/aaa1234fdja/candix/blob/main/candix/playbooks/engine.py"
click node_reportmodel "https://github.com/aaa1234fdja/candix/blob/main/candix/report/model.py"
click node_reportbuilder "https://github.com/aaa1234fdja/candix/blob/main/candix/report/builder.py"
click node_integrations "https://github.com/aaa1234fdja/candix/blob/main/candix/integrations/base.py"
click node_compare "https://github.com/aaa1234fdja/candix/blob/main/candix/analysis/diff.py"
click node_repl "https://github.com/aaa1234fdja/candix/blob/main/candix/cli/repl.py"
click node_tui "https://github.com/aaa1234fdja/candix/blob/main/candix/tui/app.py"
click node_lab "https://github.com/aaa1234fdja/candix/blob/main/candix/lab/app.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_api toneBlue
class node_context,node_scope,node_engine,node_network,node_recon,node_endpoint toneAmber
class node_detectors,node_finding,node_proof,node_fuzz,node_playbooks toneMint
class node_reportmodel,node_reportbuilder,node_integrations toneRose
class node_compare,node_repl,node_tui,node_lab,node_operator,node_target,node_consumers,node_delivery toneIndigo
```

## Components

### Operator interfaces

- [CLI commands](https://github.com/aaa1234fdja/candix/blob/main/candix/cli/commands.py): `candix/cli/commands.py`
- [HTTP API](https://github.com/aaa1234fdja/candix/blob/main/candix/api/server.py): `candix/api/server.py`

### Scan runtime

- [Scan context](https://github.com/aaa1234fdja/candix/blob/main/candix/core/context.py): `candix/core/context.py`
- [Authorization scope](https://github.com/aaa1234fdja/candix/blob/main/candix/core/scope.py): `candix/core/scope.py`
- [Scan engine](https://github.com/aaa1234fdja/candix/blob/main/candix/engine.py): `candix/engine.py`
- [HTTP client](https://github.com/aaa1234fdja/candix/blob/main/candix/net/http.py): `candix/net/http.py`
- [Reconnaissance](https://github.com/aaa1234fdja/candix/blob/main/candix/recon/crawler.py): `candix/recon/crawler.py`
- [Endpoint model](https://github.com/aaa1234fdja/candix/blob/main/candix/core/endpoint.py): `candix/core/endpoint.py`

### Assessment capabilities

- [Detector framework](https://github.com/aaa1234fdja/candix/blob/main/candix/detectors/base.py): `candix/detectors/base.py`
- [Findings](https://github.com/aaa1234fdja/candix/blob/main/candix/core/finding.py): `candix/core/finding.py`
- [Exploit verification](https://github.com/aaa1234fdja/candix/blob/main/candix/exploit/engine.py): `candix/exploit/engine.py`
- [Mutation fuzzing](https://github.com/aaa1234fdja/candix/blob/main/candix/fuzz/runner.py): `candix/fuzz/runner.py`
- [Verification playbooks](https://github.com/aaa1234fdja/candix/blob/main/candix/playbooks/engine.py): `candix/playbooks/engine.py`

### Results and delivery

- [Report model](https://github.com/aaa1234fdja/candix/blob/main/candix/report/model.py): `candix/report/model.py`
- [Report rendering](https://github.com/aaa1234fdja/candix/blob/main/candix/report/builder.py): `candix/report/builder.py`
- [Result integrations](https://github.com/aaa1234fdja/candix/blob/main/candix/integrations/base.py): `candix/integrations/base.py`

### Auxiliary workflows

- [Scan comparison](https://github.com/aaa1234fdja/candix/blob/main/candix/analysis/diff.py): `candix/analysis/diff.py`
- [Interactive shell](https://github.com/aaa1234fdja/candix/blob/main/candix/cli/repl.py): `candix/cli/repl.py`
- [Terminal dashboard](https://github.com/aaa1234fdja/candix/blob/main/candix/tui/app.py): `candix/tui/app.py`
- [Vulnerable lab](https://github.com/aaa1234fdja/candix/blob/main/candix/lab/app.py): `candix/lab/app.py`

### Other components

- **Operator**
- **Authorized target**
- **Report consumers**
- **Notification services**

## Connections

- Operator → CLI commands: invokes
- CLI commands → Scan engine: starts scans (evidence: `candix/cli/commands.py`)
- Operator → HTTP API: submits jobs
- HTTP API → Scan engine: runs scans (evidence: `candix/api/server.py`)
- CLI commands → Scan context: builds context (evidence: `candix/cli/commands.py`)
- HTTP API → Scan context: builds context (evidence: `candix/api/server.py`)
- Scan context → Authorization scope: provides scope (evidence: `candix/core/context.py`)
- Scan context → HTTP client: creates client (evidence: `candix/core/context.py`)
- Scan engine → HTTP client: preflights targets (evidence: `candix/engine.py`)
- Scan engine → Reconnaissance: runs recon (evidence: `candix/engine.py`)
- Reconnaissance → HTTP client: fetches pages (evidence: `candix/recon/crawler.py`)
- Reconnaissance → Endpoint model: emits endpoints (evidence: `candix/recon/crawler.py`)
- Scan engine → Detector framework: runs detectors (evidence: `candix/engine.py`)
- Detector framework → Findings: yields findings (evidence: `candix/detectors/base.py`)
- Scan engine → Exploit verification: runs gated proofs (evidence: `candix/engine.py`)
- Exploit verification → Findings: updates proofs (evidence: `candix/exploit/engine.py`)
- Scan engine → Scan context: uses shared state (evidence: `candix/engine.py`)
- Findings → Report model: populates report (evidence: `candix/report/model.py`)
- Report model → Report rendering: renders formats
- Report rendering → Report consumers: exports reports
- CLI commands → Mutation fuzzing: runs fuzzing (evidence: `candix/cli/commands.py`)
- CLI commands → Scan comparison: compares scans
- CLI commands → Verification playbooks: lists playbooks (evidence: `candix/cli/commands.py`)
- CLI commands → Result integrations: sends notifications (evidence: `candix/cli/commands.py`)
- Result integrations → Notification services: delivers results
- Operator → Interactive shell: uses shell
- Operator → Terminal dashboard: uses dashboard
- CLI commands → Vulnerable lab: starts lab
- HTTP client → Authorized target: sends requests
