# noppakorn001/project-ctf_agent architecture

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

- Interactive diagram: https://gitdiagram.com/noppakorn001/project-ctf_agent
- Repository: https://github.com/noppakorn001/project-ctf_agent

## Overview

CTF Agent is a local-first orchestration console for authorized CTF challenges. The principal workflow imports a bounded challenge and artifacts, preprocesses and classifies them, applies scope and token policies, routes work through deterministic tools or an explicitly enabled model, records evidence, and verifies candidate flags before marking a challenge solved. The graph reflects the README’s documented architecture and capabilities; unsampled implementation details are represented only where the README explicitly documents them.

Main entry points: [`ctf_agent/service.py`](https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/service.py) (CTFService), [`ctf_agent/static`](https://github.com/noppakorn001/project-ctf_agent/tree/main/ctf_agent/static) (Dashboard UI), [`ctf_agent/http.py`](https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/http.py) (HTTP API), [`ctf_agent/__main__.py`](https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/__main__.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Operator experience"]
  node_ui["Dashboard UI"]
  node_http["HTTP API<br/>[http.py]"]
  node_cli["CLI<br/>[__main__.py]"]
end

subgraph group_orchestration["Challenge orchestration"]
  node_service["CTFService<br/>[service.py]"]
  node_core["Deterministic core<br/>[core.py]"]
end

subgraph group_solving["Solving capabilities"]
  node_provider["Model providers<br/>[providers.py]"]
  node_recipes["Offline recipes<br/>[recipes.py]"]
  node_solvers["Deterministic solvers"]
  node_playbooks["Category playbooks<br/>[playbooks.py]"]
  node_websolvers["Web solvers<br/>[web_solvers.py]"]
  node_archive["CryptoHack archive"]
  node_sandbox["Approved sandbox<br/>[sandbox.py]"]
  node_knowledge["Knowledge base"]
end

subgraph group_state["State and evidence"]
  node_storage[("SQLite state<br/>[storage.py]")]
end

node_operator(("Operator"))
node_browser(("Browser"))
node_model(("External model"))
node_codex(("Codex workflow"))

node_operator -->|"uses"| node_browser
node_browser -->|"opens"| node_ui
node_ui -->|"JSON requests"| node_http
node_operator -->|"runs"| node_cli
node_cli -->|"starts and invokes"| node_service
node_http -->|"dispatches requests"| node_service
node_service -->|"triages and verifies"| node_core
node_service -->|"requests model work"| node_provider
node_service -->|"reads and writes"| node_storage
node_provider -.->|"calls when enabled"| node_model
node_service -->|"uses offline transforms"| node_recipes
node_service -->|"runs evidenced routes"| node_solvers
node_service -->|"discovers guidance"| node_playbooks
node_service -.->|"routes web work"| node_websolvers
node_service -->|"runs archive commands"| node_archive
node_service -.->|"requests approved inspection"| node_sandbox
node_codex -.->|"uses"| node_playbooks
node_codex -.->|"consults"| node_knowledge

click node_ui "https://github.com/noppakorn001/project-ctf_agent/tree/main/ctf_agent/static"
click node_http "https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/http.py"
click node_cli "https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/__main__.py"
click node_service "https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/service.py"
click node_core "https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/core.py"
click node_storage "https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/storage.py"
click node_provider "https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/providers.py"
click node_recipes "https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/recipes.py"
click node_solvers "https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/deterministic_solvers.py"
click node_playbooks "https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/playbooks.py"
click node_websolvers "https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/web_solvers.py"
click node_archive "https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/cryptohack_archive.py"
click node_sandbox "https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/sandbox.py"
click node_knowledge "https://github.com/noppakorn001/project-ctf_agent/tree/main/knowledge"

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_ui,node_http,node_cli,node_browser toneBlue
class node_service,node_core toneAmber
class node_provider,node_recipes,node_solvers,node_playbooks,node_websolvers,node_archive,node_sandbox,node_knowledge toneMint
class node_storage toneRose
class node_operator,node_model,node_codex toneIndigo
```

## Components

### Operator experience

- [Dashboard UI](https://github.com/noppakorn001/project-ctf_agent/tree/main/ctf_agent/static): `ctf_agent/static`
- [HTTP API](https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/http.py): `ctf_agent/http.py`
- [CLI](https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/__main__.py): `ctf_agent/__main__.py`

### Challenge orchestration

- [CTFService](https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/service.py): `ctf_agent/service.py`
- [Deterministic core](https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/core.py): `ctf_agent/core.py`

### Solving capabilities

- [Model providers](https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/providers.py): `ctf_agent/providers.py`
- [Offline recipes](https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/recipes.py): `ctf_agent/recipes.py`
- [Deterministic solvers](https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/deterministic_solvers.py): `ctf_agent/deterministic_solvers.py`
- [Category playbooks](https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/playbooks.py): `ctf_agent/playbooks.py`
- [Web solvers](https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/web_solvers.py): `ctf_agent/web_solvers.py`
- [CryptoHack archive](https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/cryptohack_archive.py): `ctf_agent/cryptohack_archive.py`
- [Approved sandbox](https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/sandbox.py): `ctf_agent/sandbox.py`
- [Knowledge base](https://github.com/noppakorn001/project-ctf_agent/tree/main/knowledge): `knowledge`

### State and evidence

- [SQLite state](https://github.com/noppakorn001/project-ctf_agent/blob/main/ctf_agent/storage.py): `ctf_agent/storage.py`

### Other components

- **Operator**
- **Browser**
- **External model**
- **Codex workflow**

## Connections

- Operator → Browser: uses
- Browser → Dashboard UI: opens
- Dashboard UI → HTTP API: JSON requests
- Operator → CLI: runs
- CLI → CTFService: starts and invokes
- HTTP API → CTFService: dispatches requests
- CTFService → Deterministic core: triages and verifies
- CTFService → Model providers: requests model work
- CTFService → SQLite state: reads and writes
- Model providers → External model: calls when enabled
- CTFService → Offline recipes: uses offline transforms
- CTFService → Deterministic solvers: runs evidenced routes
- CTFService → Category playbooks: discovers guidance
- CTFService → Web solvers: routes web work
- CTFService → CryptoHack archive: runs archive commands
- CTFService → Approved sandbox: requests approved inspection
- Codex workflow → Category playbooks: uses
- Codex workflow → Knowledge base: consults