# anhelinabodak/kubebit architecture

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

- Interactive diagram: https://gitdiagram.com/anhelinabodak/kubebit
- Repository: https://github.com/anhelinabodak/kubebit

## Overview

Kubebit is a Flask-backed CTF management platform. Players submit flags and receive solve/point results; administrators manage users, teams, challenges, categories, and competition scoring, while container challenges can be started or stopped in team namespaces. The graph includes those documented product stages and the persistence, scoring, and Kubernetes-orchestration layers. Some API routes and frontend wiring are unsampled, so links without direct excerpt evidence are omitted; namespace operations and static challenges are included as documented capabilities.

Main entry points: [`src/app.py`](https://github.com/anhelinabodak/kubebit/blob/main/src/app.py) (Flask API), [`src/db.py`](https://github.com/anhelinabodak/kubebit/blob/main/src/db.py) (SQLAlchemy database), [`src/core/competition.py`](https://github.com/anhelinabodak/kubebit/blob/main/src/core/competition.py) (Competition settings), [`src/core/submission.py`](https://github.com/anhelinabodak/kubebit/blob/main/src/core/submission.py) (Flag submissions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Platform API"]
  node_api["Flask API<br/>[app.py]"]
  node_adminui["Admin interface<br/>[app.js]"]
  node_playerui["Player interface<br/>[app.js]"]
end

subgraph group_domain["CTF Domain"]
  node_users["User accounts<br/>[user.py]"]
  node_teams["Team management<br/>[team.py]"]
  node_challenges["Challenge catalog<br/>[challenge.py]"]
  node_submissions["Flag submissions<br/>[submission.py]"]
  node_competition["Competition settings<br/>[competition.py]"]
  node_scoring["Scoring rules<br/>[scoring.py]"]
end

subgraph group_runtime["Challenge Runtime"]
  node_runtime_data["Container config lookup<br/>[runtime.py]"]
  node_deployment["Challenge deployment"]
  node_namespaces["Team namespaces"]
end

subgraph group_persistence["Persistence"]
  node_models["Domain models<br/>[models.py]"]
  node_db[("SQLAlchemy database<br/>[db.py]")]
end

node_actor(("Player or admin"))
node_kubernetes{{"Kubernetes cluster"}}
node_postgres[("PostgreSQL")]

node_actor -->|"uses"| node_api
node_adminui -.->|"calls API"| node_api
node_playerui -.->|"calls API"| node_api
node_api -.->|"authenticates users"| node_users
node_api -->|"manages teams"| node_teams
node_api -->|"manages challenges"| node_challenges
node_api -->|"submits flags"| node_submissions
node_api -.->|"manages competition"| node_competition
node_submissions -->|"calculates awarded points"| node_competition
node_competition -->|"uses scoring rule"| node_scoring
node_users -->|"reads and writes"| node_db
node_teams -->|"reads and writes"| node_db
node_challenges -->|"reads and writes"| node_db
node_submissions -->|"reads and writes"| node_db
node_competition -->|"reads and writes"| node_db
node_models -->|"uses ORM"| node_db
node_db -->|"persists data"| node_postgres
node_api -->|"starts and stops"| node_deployment
node_deployment -->|"gets container config"| node_runtime_data
node_runtime_data -->|"reads challenge"| node_models
node_deployment -->|"creates and deletes pods/services"| node_kubernetes
node_api -.->|"manages namespaces"| node_namespaces
node_namespaces -->|"creates namespaces"| node_kubernetes

click node_api "https://github.com/anhelinabodak/kubebit/blob/main/src/app.py"
click node_adminui "https://github.com/anhelinabodak/kubebit/blob/main/src/static/admin/app.js"
click node_playerui "https://github.com/anhelinabodak/kubebit/blob/main/src/static/users/app.js"
click node_users "https://github.com/anhelinabodak/kubebit/blob/main/src/core/user.py"
click node_teams "https://github.com/anhelinabodak/kubebit/blob/main/src/core/team.py"
click node_challenges "https://github.com/anhelinabodak/kubebit/blob/main/src/core/challenge.py"
click node_submissions "https://github.com/anhelinabodak/kubebit/blob/main/src/core/submission.py"
click node_competition "https://github.com/anhelinabodak/kubebit/blob/main/src/core/competition.py"
click node_scoring "https://github.com/anhelinabodak/kubebit/blob/main/src/core/scoring.py"
click node_models "https://github.com/anhelinabodak/kubebit/blob/main/src/models.py"
click node_db "https://github.com/anhelinabodak/kubebit/blob/main/src/db.py"
click node_runtime_data "https://github.com/anhelinabodak/kubebit/blob/main/src/core/runtime.py"
click node_deployment "https://github.com/anhelinabodak/kubebit/blob/main/src/start_stop_challenge.py"
click node_namespaces "https://github.com/anhelinabodak/kubebit/blob/main/src/namespaces_logic.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_api,node_adminui,node_playerui toneBlue
class node_users,node_teams,node_challenges,node_submissions,node_competition,node_scoring,node_postgres toneAmber
class node_runtime_data,node_deployment,node_namespaces toneMint
class node_models,node_db toneRose
class node_actor,node_kubernetes toneIndigo
```

## Components

### Platform API

- [Flask API](https://github.com/anhelinabodak/kubebit/blob/main/src/app.py): `src/app.py`
- [Admin interface](https://github.com/anhelinabodak/kubebit/blob/main/src/static/admin/app.js): `src/static/admin/app.js`
- [Player interface](https://github.com/anhelinabodak/kubebit/blob/main/src/static/users/app.js): `src/static/users/app.js`

### CTF Domain

- [User accounts](https://github.com/anhelinabodak/kubebit/blob/main/src/core/user.py): `src/core/user.py`
- [Team management](https://github.com/anhelinabodak/kubebit/blob/main/src/core/team.py): `src/core/team.py`
- [Challenge catalog](https://github.com/anhelinabodak/kubebit/blob/main/src/core/challenge.py): `src/core/challenge.py`
- [Flag submissions](https://github.com/anhelinabodak/kubebit/blob/main/src/core/submission.py): `src/core/submission.py`
- [Competition settings](https://github.com/anhelinabodak/kubebit/blob/main/src/core/competition.py): `src/core/competition.py`
- [Scoring rules](https://github.com/anhelinabodak/kubebit/blob/main/src/core/scoring.py): `src/core/scoring.py`

### Challenge Runtime

- [Container config lookup](https://github.com/anhelinabodak/kubebit/blob/main/src/core/runtime.py): `src/core/runtime.py`
- [Challenge deployment](https://github.com/anhelinabodak/kubebit/blob/main/src/start_stop_challenge.py): `src/start_stop_challenge.py`
- [Team namespaces](https://github.com/anhelinabodak/kubebit/blob/main/src/namespaces_logic.py): `src/namespaces_logic.py`

### Persistence

- [Domain models](https://github.com/anhelinabodak/kubebit/blob/main/src/models.py): `src/models.py`
- [SQLAlchemy database](https://github.com/anhelinabodak/kubebit/blob/main/src/db.py): `src/db.py`

### Other components

- **Player or admin**
- **Kubernetes cluster**
- **PostgreSQL**

## Connections

- Player or admin → Flask API: uses (evidence: `README.md`)
- Admin interface → Flask API: calls API
- Player interface → Flask API: calls API
- Flask API → User accounts: authenticates users (evidence: `src/app.py`)
- Flask API → Team management: manages teams (evidence: `src/app.py`)
- Flask API → Challenge catalog: manages challenges (evidence: `src/app.py`)
- Flask API → Flag submissions: submits flags (evidence: `src/app.py`)
- Flask API → Competition settings: manages competition (evidence: `src/app.py`)
- Flag submissions → Competition settings: calculates awarded points (evidence: `src/core/submission.py`)
- Competition settings → Scoring rules: uses scoring rule (evidence: `src/core/competition.py`)
- User accounts → SQLAlchemy database: reads and writes (evidence: `src/core/user.py`)
- Team management → SQLAlchemy database: reads and writes (evidence: `src/core/team.py`)
- Challenge catalog → SQLAlchemy database: reads and writes (evidence: `src/core/challenge.py`)
- Flag submissions → SQLAlchemy database: reads and writes (evidence: `src/core/submission.py`)
- Competition settings → SQLAlchemy database: reads and writes (evidence: `src/core/competition.py`)
- Domain models → SQLAlchemy database: uses ORM (evidence: `src/models.py`)
- SQLAlchemy database → PostgreSQL: persists data (evidence: `README.md`)
- Flask API → Challenge deployment: starts and stops (evidence: `src/app.py`)
- Challenge deployment → Container config lookup: gets container config (evidence: `src/start_stop_challenge.py`)
- Container config lookup → Domain models: reads challenge (evidence: `src/core/runtime.py`)
- Challenge deployment → Kubernetes cluster: creates and deletes pods/services (evidence: `src/start_stop_challenge.py`)
- Flask API → Team namespaces: manages namespaces
- Team namespaces → Kubernetes cluster: creates namespaces (evidence: `src/namespaces_logic.py`)
