# ctfer-io/24hiut2025 architecture

> Architecture diagram of the GitHub repository ctfer-io/24hiut2025, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ctfer-io/24hiut2025
- Repository: https://github.com/ctfer-io/24hiut2025

## Overview

##### Project type and purpose
- This is a CTF (Capture-The-Flag) repository for the “24h IUT 2025” event.
- It contains:
- A set of challenge definitions (static files, code, Dockerfiles, YAML) under `challenges/`.
- Infrastructure-as-code scenarios (Pulumi Go programs) for spinning up dynamic challenge instances under each `challenges/*/infra/` or `challenges/*/dist/`.
- A top-level `infra/` directory with microservices (auth, players, memes) and deployment manifests for the shared platform.
- CI/CD artifacts in `.github/` and configuration files (`.ctfd.yaml`, Dockerfiles, docker-compose).

##### File structure
- Top-level:
- `.github/`: GitHub Actions workflows and PR templates.
- `challenges/`: grouped by category (crypto, forensic, infra, web, etc.), each with:
– Challenge metadata (`WU.md`, `challenge.yaml`).
– Build artifacts under `dist/` or code under `wu/`.
– An `infra/scenario/` or `infra/` subfolder containing Pulumi programs (Go) or Docker Compose to launch the challenge.
- `infra/`: three self-contained services—`auth/`, `players/`, `memes/`—each with its own Dockerfile/Pulumi template or Kubernetes YAML.
- Patterns and choices:
- Microservices for platform components.
- Pulumi IaC in Go to provision both platform and per-challenge environments.
- Docker/Docker Compose and static site assets for certain challenges.
- A static web front-end for memes and challenge landing pages.

##### README for additional insights
- The README lists all challenges, their types (`dynamic`, `dynamic_iac`, `standard`), and release timeline.
- It indicates the platform uses CTFd (via `.ctfd.yaml`) and Pulumi as IaC.

##### Components
a. Source & CI/CD
- GitHub repository (code + challenges + IaC).
- GitHub Actions pipelines (build challenge images, run Pulumi deploy).
b. IaC Layer
- Pulumi controller that reads each `challenges/*/infra/scenario/Pulumi.yaml` + Go program to provision:
- Kubernetes Namespaces or VM instances per challenge
- Docker images pushed to registry
- Challenge containers or pods behind services
- Pulumi deployments for `infra/auth`, `infra/players`, `infra/memes`.
c. Runtime Cluster / Hosting Environment
- Kubernetes cluster (or Docker-Compose host)
- API Gateway / Load Balancer → routes traffic to platform and microservices
- CTFd platform service (frontend + backend)
- Database (MySQL/MariaDB) and optional Redis for session caching
- Auth microservice
- Players microservice
- Memes static-site service
- Challenge namespaces/pods: each challenge runs in its own sandbox (Docker container) exposing a port or service
d. External integrations
- Discord webhook for announcements
- Artifact registry (Docker Hub or private registry)
- Pulumi state backend (S3 / Pulumi Service)

##### Relationships & data flow
1. Developer pushes to GitHub → triggers GitHub Actions.
2. CI builds challenge Docker images, pushes to registry; builds microservice images.
3. CI invokes Pulumi to update infrastructure:
– Shared platform services
– Individual challenge deployments
4. Pulumi applies changes to the Kubernetes cluster.
5. Users connect via the Internet to the Load Balancer → routed to:
– CTFd web UI to select challenges
– Direct challenge endpoints (e.g., web, pwn, forensic services)
– Static site (memes)
6. CTFd backend interacts with DB and calls Auth/Players microservices as needed.

##### Architectural patterns & design principles
- Microservices: separate concerns (Auth, Players, Memes) as independent deployable units
- Infrastructure-as-Code: Pulumi Go programs define both platform and per-challenge environments
- Immutable infrastructure: challenge containers are built once (`dist/`) and deployed unchanged
- Namespace isolation: each challenge environment runs in its own namespace or Docker Compose project
- CI/CD pipeline: fully automated build and deploy on GitHub push

##### Technologies & frameworks
- Pulumi (Go) for IaC
- Docker / Docker Compose for challenge sandboxing
- Kubernetes for orchestration (optional, inferred from Pulumi scenario)
- CTFd (configured via `.ctfd.yaml`)
- Go for microservices (auth, players, Pulumi programs)
- Python / Flask for some challenge web apps
- Static HTML/CSS/JS for memes and challenge landing pages

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actors
    Users["Users (Browser)"]:::external
    Discord["Discord Webhook"]:::external

    %% Source & CI/CD
    GitHubRepo["GitHub Repository\n(.github workflows,\nchallenges/*, infra/*)"]:::code
    CICD["CI/CD Pipeline"]:::code
    Registry["Container Registry"]:::code
    PulumiIaC["Pulumi IaC Controller"]:::code

    %% Runtime Cluster
    subgraph "Kubernetes Cluster" 
        direction TB
        LB["API Gateway / Load Balancer"]:::cluster
        CTFd["CTFd Platform"]:::cluster
        AuthService["Auth Service"]:::micro
        PlayersService["Players Service"]:::micro
        MemesService["Memes Static-Site Service"]:::micro
        DB["Database\n(MySQL/MariaDB)"]:::datastore
        Redis["Redis Cache"]:::datastore
        subgraph "Challenge Sandboxes"
            direction TB
            CronpaCola["Cronpa Cola Pod"]:::challenge
            Entrainement["Entrainement Pod"]:::challenge
            Kubrac["Kubrac Pod"]:::challenge
            Shamir["Crypto/Shamir Pod"]:::challenge
            Vernam["Crypto/Vernam Pod"]:::challenge
            Ret2Popacola["Pwn/Ret2Popacola Pod"]:::challenge
        end
    end

    %% Flows
    GitHubRepo -->|"push"| CICD
    CICD -->|"build images"| Registry
    CICD -->|"deploy IaC"| PulumiIaC
    CICD -->|"notify"| Discord
    PulumiIaC -->|"provision"| LB
    PulumiIaC -->|"provision"| CTFd
    PulumiIaC -->|"provision"| AuthService
    PulumiIaC -->|"provision"| PlayersService
    PulumiIaC -->|"provision"| MemesService
    PulumiIaC -->|"provision"| CronpaCola
    PulumiIaC -->|"provision"| Entrainement
    PulumiIaC -->|"provision"| Kubrac
    PulumiIaC -->|"provision"| Shamir
    PulumiIaC -->|"provision"| Vernam
    PulumiIaC -->|"provision"| Ret2Popacola

    Users -->|"HTTP Requests"| LB
    LB -->|"routes to"| CTFd
    LB -->|"routes to"| AuthService
    LB -->|"routes to"| PlayersService
    LB -->|"routes to"| MemesService
    LB -->|"routes to"| CronpaCola
    LB -->|"routes to"| Entrainement
    LB -->|"routes to"| Kubrac
    LB -->|"routes to"| Shamir
    LB -->|"routes to"| Vernam
    LB -->|"routes to"| Ret2Popacola

    CTFd -->|"reads/writes"| DB
    CTFd -->|"caches sessions"| Redis
    AuthService -->|"stores data"| DB
    PlayersService -->|"stores data"| DB

    %% Click Events
    click GitHubRepo "https://github.com/ctfer-io/24hiut2025/tree/main/.github/"
    click CTFd "https://github.com/ctfer-io/24hiut2025/blob/main/challenges/.ctfd.yaml"
    click AuthService "https://github.com/ctfer-io/24hiut2025/blob/main/infra/auth/main.go"
    click PlayersService "https://github.com/ctfer-io/24hiut2025/blob/main/infra/players/main.go"
    click MemesService "https://github.com/ctfer-io/24hiut2025/blob/main/infra/memes/index.html"
    click CronpaCola "https://github.com/ctfer-io/24hiut2025/blob/main/challenges/infra/cronpa-cola/infra/scenario/Pulumi.yaml"
    click Entrainement "https://github.com/ctfer-io/24hiut2025/blob/main/challenges/infra/entrainement/infra/scenario/Pulumi.yaml"
    click Kubrac "https://github.com/ctfer-io/24hiut2025/blob/main/challenges/infra/kubrac/infra/scenario/Pulumi.yaml"
    click Shamir "https://github.com/ctfer-io/24hiut2025/blob/main/challenges/crypto/shamir/wu/index.js"
    click Vernam "https://github.com/ctfer-io/24hiut2025/blob/main/challenges/crypto/vernam/dist/main.go"
    click Ret2Popacola "https://github.com/ctfer-io/24hiut2025/blob/main/challenges/pwn/ret2popacola/infra/scenario/Pulumi.yaml"

    %% Styles
    classDef code fill:#D8B4FE,stroke:#8B5CF6,color:#000
    classDef micro fill:#FDBA74,stroke:#EA580C,color:#000
    classDef datastore fill:#BBF7D0,stroke:#059669,color:#000
    classDef challenge fill:#E5E7EB,stroke:#6B7280,color:#000
    classDef external fill:#F3F4F6,stroke:#9CA3AF,color:#000
    classDef cluster fill:#DBEAFE,stroke:#3B82F6,color:#000
```
