# markusbauer/saarctf-servers architecture

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

- Interactive diagram: https://gitdiagram.com/markusbauer/saarctf-servers
- Repository: https://github.com/markusbauer/saarctf-servers

## Overview

This repository provisions and configures the server infrastructure for running an attack-defense CTF. Its central runtime workflow connects team traffic through VPN services, accepts flag submissions, processes checker jobs on Celery workers, and exposes competition state through the scoreboard and control panel. Separate branches provide traffic capture and statistics, monitoring, and centralized log infrastructure. The graph reflects the README and sampled scripts; several services are documented but their application source is not present in the tree, so their internal wiring is not expanded.

Main entry points: [`tofu/saarctf-setup/main.tf`](https://github.com/markusbauer/saarctf-servers/blob/master/tofu/saarctf-setup/main.tf) (VM Infrastructure), [`vpn/files/services/vpn@.service`](https://github.com/markusbauer/saarctf-servers/blob/master/vpn/files/services/vpn%40.service) (Team VPN Services), [`controller/playbook.yml`](https://github.com/markusbauer/saarctf-servers/blob/master/controller/playbook.yml) (Databases), [`controller/files/grafana/saarctf-dashboards.yml`](https://github.com/markusbauer/saarctf-servers/blob/master/controller/files/grafana/saarctf-dashboards.yml) (Metrics and Dashboards)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_provisioning["Infrastructure"]
  node_terraform["VM Infrastructure<br/>[main.tf]"]
  node_network_module["Network Module<br/>[main.tf]"]
  node_controller_image["Controller Image<br/>[playbook.yml]"]
  node_vpn_image["VPN Image<br/>[playbook.yml]"]
  node_checker_image["Checker Image<br/>[playbook.yml]"]
end

subgraph group_gameserver["Gameserver"]
  node_databases[("Databases<br/>[playbook.yml]")]
  node_control_panel["Control Panel<br/>[playbook.yml]"]
  node_timer["CTF Timer<br/>[ctftimer.service]"]
  node_submission["Flag Submission"]
  node_scoreboard["Scoreboard<br/>[scoreboard.service]"]
  node_test_client["Test Run Client<br/>[start_testrun.py]"]
  node_traffic_database[("Traffic Database<br/>[playbook.yml]")]
end

subgraph group_network["VPN and Traffic"]
  node_vpn_services["Team VPN Services<br/>[vpn@.service]"]
  node_firewall["Firewall Manager"]
  node_traffic_capture["Traffic Capture"]
  node_traffic_stats["Traffic Statistics"]
end

subgraph group_operations["Workers and Operations"]
  node_celery_queue["Celery Queue<br/>[rabbitmq-setup.sh]"]
  node_checker_worker["Checker Worker<br/>[celery.service]"]
  node_monitoring["Metrics and Dashboards"]
  node_log_stack["Central Log Stack<br/>[docker-compose.yml]"]
  node_service_status["Service Status<br/>[service.py]"]
end

node_organizer(("Organizer"))
node_teams(("CTF Teams"))

node_organizer -->|"provisions"| node_terraform
node_terraform -->|"creates network"| node_network_module
node_terraform -->|"deploys role"| node_controller_image
node_terraform -->|"deploys role"| node_vpn_image
node_terraform -->|"deploys role"| node_checker_image
node_teams -->|"connects through"| node_vpn_services
node_vpn_services -->|"uses rules"| node_firewall
node_teams -->|"submits flags"| node_submission
node_submission -->|"records submissions"| node_databases
node_control_panel -->|"schedules checker jobs"| node_celery_queue
node_celery_queue -->|"dispatches jobs"| node_checker_worker
node_checker_worker -->|"stores results"| node_databases
node_test_client -->|"uploads and queries"| node_control_panel
node_timer -->|"triggers rebuild"| node_scoreboard
node_databases -->|"provides competition data"| node_scoreboard
node_vpn_services -->|"carries captured traffic"| node_traffic_capture
node_traffic_capture -->|"supplies traffic"| node_traffic_stats
node_traffic_stats -->|"writes summaries"| node_traffic_database
node_monitoring -->|"monitors"| node_databases
node_monitoring -->|"monitors"| node_vpn_services
node_log_stack -.->|"collects logs"| node_controller_image
node_log_stack -.->|"collects logs"| node_vpn_image
node_service_status -.->|"reports status"| node_monitoring

click node_terraform "https://github.com/markusbauer/saarctf-servers/blob/master/tofu/saarctf-setup/main.tf"
click node_network_module "https://github.com/markusbauer/saarctf-servers/blob/master/tofu/modules/network/main.tf"
click node_controller_image "https://github.com/markusbauer/saarctf-servers/blob/master/controller/playbook.yml"
click node_vpn_image "https://github.com/markusbauer/saarctf-servers/blob/master/vpn/playbook.yml"
click node_checker_image "https://github.com/markusbauer/saarctf-servers/blob/master/checker/playbook.yml"
click node_databases "https://github.com/markusbauer/saarctf-servers/blob/master/controller/playbook.yml"
click node_control_panel "https://github.com/markusbauer/saarctf-servers/blob/master/controller/playbook.yml"
click node_timer "https://github.com/markusbauer/saarctf-servers/blob/master/controller/files/ctftimer.service"
click node_submission "https://github.com/markusbauer/saarctf-servers/blob/master/controller/files/submission-server.service"
click node_scoreboard "https://github.com/markusbauer/saarctf-servers/blob/master/controller/files/scoreboard.service"
click node_celery_queue "https://github.com/markusbauer/saarctf-servers/blob/master/controller/files/scripts/rabbitmq-setup.sh"
click node_checker_worker "https://github.com/markusbauer/saarctf-servers/blob/master/checker/files/services/celery.service"
click node_test_client "https://github.com/markusbauer/saarctf-servers/blob/master/controller/files/codeeditor/scripts/start_testrun.py"
click node_vpn_services "https://github.com/markusbauer/saarctf-servers/blob/master/vpn/files/services/vpn%40.service"
click node_firewall "https://github.com/markusbauer/saarctf-servers/blob/master/vpn/files/services/manage-iptables.service"
click node_traffic_capture "https://github.com/markusbauer/saarctf-servers/blob/master/vpn/files/services/tcpdump-team.service"
click node_traffic_stats "https://github.com/markusbauer/saarctf-servers/blob/master/vpn/files/services/trafficstats.service"
click node_traffic_database "https://github.com/markusbauer/saarctf-servers/blob/master/controller/playbook.yml"
click node_monitoring "https://github.com/markusbauer/saarctf-servers/blob/master/controller/files/grafana/saarctf-dashboards.yml"
click node_log_stack "https://github.com/markusbauer/saarctf-servers/blob/master/elastic/files/docker-compose.yml"
click node_service_status "https://github.com/markusbauer/saarctf-servers/blob/master/srvstatus/service.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_terraform,node_network_module,node_controller_image,node_vpn_image,node_checker_image toneBlue
class node_databases,node_control_panel,node_timer,node_submission,node_scoreboard,node_test_client,node_traffic_database toneAmber
class node_vpn_services,node_firewall,node_traffic_capture,node_traffic_stats toneMint
class node_celery_queue,node_checker_worker,node_monitoring,node_log_stack,node_service_status toneRose
class node_organizer,node_teams toneIndigo
```

## Components

### Infrastructure

- [VM Infrastructure](https://github.com/markusbauer/saarctf-servers/blob/master/tofu/saarctf-setup/main.tf): `tofu/saarctf-setup/main.tf`
- [Network Module](https://github.com/markusbauer/saarctf-servers/blob/master/tofu/modules/network/main.tf): `tofu/modules/network/main.tf`
- [Controller Image](https://github.com/markusbauer/saarctf-servers/blob/master/controller/playbook.yml): `controller/playbook.yml`
- [VPN Image](https://github.com/markusbauer/saarctf-servers/blob/master/vpn/playbook.yml): `vpn/playbook.yml`
- [Checker Image](https://github.com/markusbauer/saarctf-servers/blob/master/checker/playbook.yml): `checker/playbook.yml`

### Gameserver

- [Databases](https://github.com/markusbauer/saarctf-servers/blob/master/controller/playbook.yml): `controller/playbook.yml`
- [Control Panel](https://github.com/markusbauer/saarctf-servers/blob/master/controller/playbook.yml): `controller/playbook.yml`
- [CTF Timer](https://github.com/markusbauer/saarctf-servers/blob/master/controller/files/ctftimer.service): `controller/files/ctftimer.service`
- [Flag Submission](https://github.com/markusbauer/saarctf-servers/blob/master/controller/files/submission-server.service): `controller/files/submission-server.service`
- [Scoreboard](https://github.com/markusbauer/saarctf-servers/blob/master/controller/files/scoreboard.service): `controller/files/scoreboard.service`
- [Test Run Client](https://github.com/markusbauer/saarctf-servers/blob/master/controller/files/codeeditor/scripts/start_testrun.py): `controller/files/codeeditor/scripts/start_testrun.py`
- [Traffic Database](https://github.com/markusbauer/saarctf-servers/blob/master/controller/playbook.yml): `controller/playbook.yml`

### VPN and Traffic

- [Team VPN Services](https://github.com/markusbauer/saarctf-servers/blob/master/vpn/files/services/vpn%40.service): `vpn/files/services/vpn@.service`
- [Firewall Manager](https://github.com/markusbauer/saarctf-servers/blob/master/vpn/files/services/manage-iptables.service): `vpn/files/services/manage-iptables.service`
- [Traffic Capture](https://github.com/markusbauer/saarctf-servers/blob/master/vpn/files/services/tcpdump-team.service): `vpn/files/services/tcpdump-team.service`
- [Traffic Statistics](https://github.com/markusbauer/saarctf-servers/blob/master/vpn/files/services/trafficstats.service): `vpn/files/services/trafficstats.service`

### Workers and Operations

- [Celery Queue](https://github.com/markusbauer/saarctf-servers/blob/master/controller/files/scripts/rabbitmq-setup.sh): `controller/files/scripts/rabbitmq-setup.sh`
- [Checker Worker](https://github.com/markusbauer/saarctf-servers/blob/master/checker/files/services/celery.service): `checker/files/services/celery.service`
- [Metrics and Dashboards](https://github.com/markusbauer/saarctf-servers/blob/master/controller/files/grafana/saarctf-dashboards.yml): `controller/files/grafana/saarctf-dashboards.yml`
- [Central Log Stack](https://github.com/markusbauer/saarctf-servers/blob/master/elastic/files/docker-compose.yml): `elastic/files/docker-compose.yml`
- [Service Status](https://github.com/markusbauer/saarctf-servers/blob/master/srvstatus/service.py): `srvstatus/service.py`

### Other components

- **Organizer**
- **CTF Teams**

## Connections

- Organizer → VM Infrastructure: provisions
- VM Infrastructure → Network Module: creates network
- VM Infrastructure → Controller Image: deploys role
- VM Infrastructure → VPN Image: deploys role
- VM Infrastructure → Checker Image: deploys role
- CTF Teams → Team VPN Services: connects through
- Team VPN Services → Firewall Manager: uses rules
- CTF Teams → Flag Submission: submits flags
- Flag Submission → Databases: records submissions
- Control Panel → Celery Queue: schedules checker jobs
- Celery Queue → Checker Worker: dispatches jobs
- Checker Worker → Databases: stores results
- Test Run Client → Control Panel: uploads and queries
- CTF Timer → Scoreboard: triggers rebuild
- Databases → Scoreboard: provides competition data
- Team VPN Services → Traffic Capture: carries captured traffic
- Traffic Capture → Traffic Statistics: supplies traffic
- Traffic Statistics → Traffic Database: writes summaries
- Metrics and Dashboards → Databases: monitors
- Metrics and Dashboards → Team VPN Services: monitors
- Central Log Stack → Controller Image: collects logs
- Central Log Stack → VPN Image: collects logs
- Service Status → Metrics and Dashboards: reports status