# domysh/ctfbox architecture

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

- Interactive diagram: https://gitdiagram.com/domysh/ctfbox
- Repository: https://github.com/domysh/ctfbox

## Overview

CTFBox is an open attack/defense CTF platform. Organizers configure a competition, start it, and manage teams, services, and network state; players access team VMs, attack services, and submit flags, while checkers and the game server produce scores shown on the scoreboard. Its runtime spans deployment, distributed nodes, routers, isolated team boxes, service workloads, and game operations. The README documents the broad workflow and capabilities; source excerpts show selected UI and service implementations, so some subsystem links are documented rather than source-verified.

Main entry points: [`gameserver/src/main.go`](https://github.com/domysh/ctfbox/blob/main/gameserver/src/main.go) (Game server), [`run.py`](https://github.com/domysh/ctfbox/blob/main/run.py) (Platform launcher), [`vm/services`](https://github.com/domysh/ctfbox/tree/main/vm/services) (Team VMs), [`gameserver/frontend/src/components/MainLayout.tsx`](https://github.com/domysh/ctfbox/blob/main/gameserver/frontend/src/components/MainLayout.tsx) (Game web UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Configuration"]
  node_config_editor["Config editor<br/>[page.tsx]"]
  node_topology_editor["Topology preview<br/>[NodesSection.tsx]"]
  node_config_model["Config model<br/>[config.ts]"]
  node_topology_logic["Topology logic<br/>[topology.ts]"]
end

subgraph group_deployment["Deployment and network"]
  node_launcher["Platform launcher<br/>[run.py]"]
  node_incus["VM provisioning<br/>[customize-vm.py]"]
  node_router_agent["Router agent<br/>[agent.py]"]
  node_route_control["Route commands<br/>[confgen.py]"]
  node_simulation["Local simulation<br/>[simulate.py]"]
end

subgraph group_competition["Competition operations"]
  node_game_server["Game server<br/>[main.go]"]
  node_database[("Competition database<br/>[models.go]")]
  node_checker_worker["Checker worker<br/>[worker.go]"]
  node_flag_submission["Flag submissions<br/>[submission_api.go]"]
  node_scoreboard_logic["Score calculation<br/>[scoreboard.go]"]
end

subgraph group_player_services["Player services"]
  node_service_checkers["Service checkers"]
  node_team_vms["Team VMs"]
  node_pcss_service["PCSS service<br/>[main.py]"]
  node_shop_service["Pwnzer0tt1Shop<br/>[app.py]"]
  node_shop_ui["Shop frontend<br/>[App.tsx]"]
end

subgraph group_interfaces["Web interfaces"]
  node_game_frontend["Game web UI<br/>[MainLayout.tsx]"]
  node_admin_ui["Admin console<br/>[AdminPage.tsx]"]
  node_scoreboard_ui["Scoreboard UI<br/>[ScoreboardPage.tsx]"]
end

node_organizers(("Organizers"))
node_players(("Players"))

node_organizers -->|"configure"| node_config_editor
node_config_editor -->|"preview topology"| node_topology_editor
node_topology_editor -->|"validates topology"| node_topology_logic
node_topology_logic -->|"uses config types"| node_config_model
node_organizers -->|"start platform"| node_launcher
node_launcher -.->|"provisions boxes"| node_team_vms
node_launcher -.->|"starts game server"| node_game_server
node_launcher -.->|"deploys routers"| node_router_agent
node_router_agent -->|"reconciles network"| node_route_control
node_router_agent -->|"reads network state"| node_game_server
node_team_vms -.->|"hosts service"| node_pcss_service
node_team_vms -.->|"hosts service"| node_shop_service
node_players -->|"connect"| node_team_vms
node_players -.->|"submit flags"| node_flag_submission
node_service_checkers -.->|"checks services"| node_checker_worker
node_checker_worker -.->|"supplies check results"| node_scoreboard_logic
node_flag_submission -.->|"records submissions"| node_database
node_scoreboard_logic -.->|"reads competition data"| node_database
node_game_frontend -.->|"requests game data"| node_game_server
node_admin_ui -->|"admin requests"| node_game_server
node_scoreboard_ui -.->|"loads scores"| node_game_server
node_game_frontend -->|"routes admin page"| node_admin_ui
node_game_frontend -->|"routes scoreboard"| node_scoreboard_ui
node_players -.->|"use service app"| node_shop_ui
node_shop_ui -.->|"calls service API"| node_shop_service
node_organizers -->|"run local simulation"| node_simulation

click node_config_editor "https://github.com/domysh/ctfbox/blob/main/editor/app/page.tsx"
click node_topology_editor "https://github.com/domysh/ctfbox/blob/main/editor/components/NodesSection.tsx"
click node_config_model "https://github.com/domysh/ctfbox/blob/main/editor/lib/config.ts"
click node_topology_logic "https://github.com/domysh/ctfbox/blob/main/editor/lib/topology.ts"
click node_launcher "https://github.com/domysh/ctfbox/blob/main/run.py"
click node_incus "https://github.com/domysh/ctfbox/blob/main/incus/customize-vm.py"
click node_router_agent "https://github.com/domysh/ctfbox/blob/main/router/agent.py"
click node_route_control "https://github.com/domysh/ctfbox/blob/main/router/confgen.py"
click node_game_server "https://github.com/domysh/ctfbox/blob/main/gameserver/src/main.go"
click node_database "https://github.com/domysh/ctfbox/blob/main/gameserver/src/db/models.go"
click node_checker_worker "https://github.com/domysh/ctfbox/blob/main/gameserver/src/worker.go"
click node_flag_submission "https://github.com/domysh/ctfbox/blob/main/gameserver/src/submission_api.go"
click node_scoreboard_logic "https://github.com/domysh/ctfbox/blob/main/gameserver/src/scoreboard.go"
click node_game_frontend "https://github.com/domysh/ctfbox/blob/main/gameserver/frontend/src/components/MainLayout.tsx"
click node_admin_ui "https://github.com/domysh/ctfbox/blob/main/gameserver/frontend/src/pages/AdminPage.tsx"
click node_scoreboard_ui "https://github.com/domysh/ctfbox/blob/main/gameserver/frontend/src/pages/ScoreboardPage.tsx"
click node_service_checkers "https://github.com/domysh/ctfbox/tree/main/gameserver/checkers"
click node_team_vms "https://github.com/domysh/ctfbox/tree/main/vm/services"
click node_pcss_service "https://github.com/domysh/ctfbox/blob/main/vm/services/PCSS/main.py"
click node_shop_service "https://github.com/domysh/ctfbox/blob/main/vm/services/Pwnzer0tt1Shop/backend/app.py"
click node_shop_ui "https://github.com/domysh/ctfbox/blob/main/vm/services/Pwnzer0tt1Shop/frontend/src/App.tsx"
click node_simulation "https://github.com/domysh/ctfbox/blob/main/simulation/simulate.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_config_editor,node_topology_editor,node_config_model,node_topology_logic toneBlue
class node_launcher,node_incus,node_router_agent,node_route_control,node_simulation toneAmber
class node_game_server,node_database,node_checker_worker,node_flag_submission,node_scoreboard_logic toneMint
class node_service_checkers,node_team_vms,node_pcss_service,node_shop_service,node_shop_ui toneRose
class node_game_frontend,node_admin_ui,node_scoreboard_ui,node_organizers,node_players toneIndigo
```

## Components

### Configuration

- [Config editor](https://github.com/domysh/ctfbox/blob/main/editor/app/page.tsx): `editor/app/page.tsx`
- [Topology preview](https://github.com/domysh/ctfbox/blob/main/editor/components/NodesSection.tsx): `editor/components/NodesSection.tsx`
- [Config model](https://github.com/domysh/ctfbox/blob/main/editor/lib/config.ts): `editor/lib/config.ts`
- [Topology logic](https://github.com/domysh/ctfbox/blob/main/editor/lib/topology.ts): `editor/lib/topology.ts`

### Deployment and network

- [Platform launcher](https://github.com/domysh/ctfbox/blob/main/run.py): `run.py`
- [VM provisioning](https://github.com/domysh/ctfbox/blob/main/incus/customize-vm.py): `incus/customize-vm.py`
- [Router agent](https://github.com/domysh/ctfbox/blob/main/router/agent.py): `router/agent.py`
- [Route commands](https://github.com/domysh/ctfbox/blob/main/router/confgen.py): `router/confgen.py`
- [Local simulation](https://github.com/domysh/ctfbox/blob/main/simulation/simulate.py): `simulation/simulate.py`

### Competition operations

- [Game server](https://github.com/domysh/ctfbox/blob/main/gameserver/src/main.go): `gameserver/src/main.go`
- [Competition database](https://github.com/domysh/ctfbox/blob/main/gameserver/src/db/models.go): `gameserver/src/db/models.go`
- [Checker worker](https://github.com/domysh/ctfbox/blob/main/gameserver/src/worker.go): `gameserver/src/worker.go`
- [Flag submissions](https://github.com/domysh/ctfbox/blob/main/gameserver/src/submission_api.go): `gameserver/src/submission_api.go`
- [Score calculation](https://github.com/domysh/ctfbox/blob/main/gameserver/src/scoreboard.go): `gameserver/src/scoreboard.go`

### Player services

- [Service checkers](https://github.com/domysh/ctfbox/tree/main/gameserver/checkers): `gameserver/checkers`
- [Team VMs](https://github.com/domysh/ctfbox/tree/main/vm/services): `vm/services`
- [PCSS service](https://github.com/domysh/ctfbox/blob/main/vm/services/PCSS/main.py): `vm/services/PCSS/main.py`
- [Pwnzer0tt1Shop](https://github.com/domysh/ctfbox/blob/main/vm/services/Pwnzer0tt1Shop/backend/app.py): `vm/services/Pwnzer0tt1Shop/backend/app.py`
- [Shop frontend](https://github.com/domysh/ctfbox/blob/main/vm/services/Pwnzer0tt1Shop/frontend/src/App.tsx): `vm/services/Pwnzer0tt1Shop/frontend/src/App.tsx`

### Web interfaces

- [Game web UI](https://github.com/domysh/ctfbox/blob/main/gameserver/frontend/src/components/MainLayout.tsx): `gameserver/frontend/src/components/MainLayout.tsx`
- [Admin console](https://github.com/domysh/ctfbox/blob/main/gameserver/frontend/src/pages/AdminPage.tsx): `gameserver/frontend/src/pages/AdminPage.tsx`
- [Scoreboard UI](https://github.com/domysh/ctfbox/blob/main/gameserver/frontend/src/pages/ScoreboardPage.tsx): `gameserver/frontend/src/pages/ScoreboardPage.tsx`

### Other components

- **Organizers**
- **Players**

## Connections

- Organizers → Config editor: configure (evidence: `README.md`)
- Config editor → Topology preview: preview topology (evidence: `README.md`)
- Topology preview → Topology logic: validates topology (evidence: `editor/components/NodesSection.tsx`)
- Topology logic → Config model: uses config types (evidence: `editor/lib/topology.ts`)
- Organizers → Platform launcher: start platform (evidence: `README.md`)
- Platform launcher → Team VMs: provisions boxes
- Platform launcher → Game server: starts game server
- Platform launcher → Router agent: deploys routers
- Router agent → Route commands: reconciles network (evidence: `README.md`)
- Router agent → Game server: reads network state (evidence: `README.md`)
- Team VMs → PCSS service: hosts service
- Team VMs → Pwnzer0tt1Shop: hosts service (evidence: `vm/services/Pwnzer0tt1Shop/backend/app.py`)
- Players → Team VMs: connect (evidence: `README.md`)
- Players → Flag submissions: submit flags
- Service checkers → Checker worker: checks services
- Checker worker → Score calculation: supplies check results
- Flag submissions → Competition database: records submissions
- Score calculation → Competition database: reads competition data
- Game web UI → Game server: requests game data
- Admin console → Game server: admin requests
- Scoreboard UI → Game server: loads scores
- Game web UI → Admin console: routes admin page (evidence: `gameserver/frontend/src/components/MainLayout.tsx`)
- Game web UI → Scoreboard UI: routes scoreboard (evidence: `gameserver/frontend/src/components/MainLayout.tsx`)
- Players → Shop frontend: use service app
- Shop frontend → Pwnzer0tt1Shop: calls service API
- Organizers → Local simulation: run local simulation (evidence: `README.md`)
