# pwncollege/dojo architecture

> Architecture diagram of the GitHub repository pwncollege/dojo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pwncollege/dojo
- Repository: https://github.com/pwncollege/dojo

## Overview

- Frontend (User Interface): Represented primarily by the dojo_theme directory which contains HTML templates, CSS, and JavaScript. This layer is responsible for rendering the user interface (dashboard, challenge pages, admin pages, etc.).
- Backend/API Layer: Centered in the dojo_plugin directory, which is segmented into API endpoints (dojo_plugin/api/v1), page rendering handlers (dojo_plugin/pages), and utility modules. This layer processes requests from the frontend and coordinates with other services.
- CTF Integration: The ctfd directory indicates built-in integration with a CTFd platform, which may be used for scoring, challenge management, or event tracking.
- Databases and Storage: The db directory (with its Dockerfile and startup scripts) represents the project's data persistence layer. Additionally, components like homefs, workspace, and dojofs indicate specialized file or volume management services.
- Orchestration & Containerization: With a docker-compose.yml and multiple Dockerfiles scattered across directories (ctfd, db, dojo, dojofs, sshd, watchdog, workspace, workspacefs), the architecture is containerized. Create a container cluster node or a “Docker” boundary that groups these services.
- Reverse Proxy & Load Balancer: The nginx-proxy directory contains configuration files for NGINX, which likely routes incoming web requests to the appropriate backend containers.
- Monitoring & Logging: The grafana and prometheus directories provide monitoring and metric dashboards for the system.
- System Integration & Timers: The etc/systemd directory comprises unit files (services and timers) that schedule backups, cache warmers, image pulling, and overall system health.
- Additional Services: Components like sshd (providing SSH gateway functionality) and watchdog (for container cleanup or monitoring) form additional pieces of the architecture.

##### Relationships and Data Flows
- Container Orchestration: Encapsulate most of these functionalities within Docker containers (as defined by the Dockerfiles and docker-compose). Indicate the orchestration boundary and how systemd timers (found in etc/systemd) trigger maintenance tasks on these containers.
- Reverse Proxy Routing: The nginx-proxy container should be shown routing external requests to the appropriate service containers.

##### Architectural Patterns and Design Principles
- Microservices / Containerized Architecture: Emphasize that many of the components are independent, containerized services communicating over defined interfaces.
- Separation of Concerns: The clear division between the frontend (dojo_theme), backend/API (dojo_plugin), and supporting services (database, reverse proxy, workspace, etc.).
- Extensibility: The dojo_plugin structure with modular API endpoints indicates an architecture designed for extensibility (supporting plugins and adding new endpoints).
- Infrastructure as Code: The presence of multiple Dockerfiles, docker-compose.yml, and systemd unit files indicates an environment where the infrastructure is reproducible and version-controlled.

##### Further Details
- Subsystems: For instance, within the API backend (dojo_plugin), detail submodules such as API endpoints (like belts, docker, score, scoreboard) to illustrate how requests are routed internally.
- Deployment Flow: Optionally, add a high-level deployment pipeline that shows how code moves from development (with devcontainer support) to production, utilizing Dockerfiles, docker-compose, and systemd-managed services.
- Refer to Documentation: Acknowledge the existence of detailed documentation in docs/architecture.md, docs/deployment.md, etc., for further clarification on interactions and deployment setups.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User
    User("User"):::external

    %% Orchestration & System Management
    DC("Docker Compose & Containers"):::orchestration
    ST("Systemd Timers (etc/systemd/system)"):::system

    %% Docker Cluster (Containerized Services)
    subgraph "Docker Cluster"
        direction TB
        RP("Reverse Proxy (NGINX)"):::reverse
        FE("Frontend (dojo_theme)"):::frontend
        BE("Backend/API (dojo_plugin)"):::backend
        CT("CTFd Integration"):::backend
        DB("Database (db)"):::storage
        SSH("SSH Gateway (sshd)"):::additional
        WD("Watchdog"):::additional
        DF("Discord Integration (dojo_plugin/api/v1/discord.py)"):::backend
        subgraph "File Storage"
            direction TB
            HF("Home File Storage (homefs)"):::storage
            DF2("DOJO Files (dojofs)"):::storage
            WS("Workspace (workspace)"):::storage
            WFS("Workspace FileSystem (workspacefs)"):::storage
        end
    end

    %% Monitoring & Visualization
    PM("Prometheus"):::monitoring
    GF("Grafana"):::monitoring

    %% Relationships
    User -->|"routesTo"| DC

    DC -->|"orchestrates"| RP
    DC -->|"orchestrates"| FE
    DC -->|"orchestrates"| BE
    DC -->|"orchestrates"| CT
    DC -->|"orchestrates"| DB
    DC -->|"orchestrates"| SSH
    DC -->|"orchestrates"| WD
    DC -->|"orchestrates"| HF
    DC -->|"orchestrates"| DF2
    DC -->|"orchestrates"| WS
    DC -->|"orchestrates"| WFS

    RP -->|"forwardsTo"| FE
    RP -->|"forwardsTo"| BE

    BE -->|"calls"| DF
    BE -->|"integratesWith"| CT
    BE -->|"queries"| DB
    BE -->|"accesses"| SSH
    BE -->|"utilizes"| WS

    ST -->|"manages"| DC

    DC -->|"sendsMetrics"| PM
    PM -->|"visualizesIn"| GF

    %% Click Events
    click FE "https://github.com/pwncollege/dojo/tree/master/dojo_theme/"
    click BE "https://github.com/pwncollege/dojo/tree/master/dojo_plugin/"
    click CT "https://github.com/pwncollege/dojo/tree/master/ctfd/"
    click DB "https://github.com/pwncollege/dojo/tree/master/db/"
    click HF "https://github.com/pwncollege/dojo/tree/master/homefs/"
    click DF2 "https://github.com/pwncollege/dojo/tree/master/dojofs/"
    click WS "https://github.com/pwncollege/dojo/tree/master/workspace/"
    click WFS "https://github.com/pwncollege/dojo/tree/master/workspacefs/"
    click DC "https://github.com/pwncollege/dojo/blob/master/docker-compose.yml"
    click RP "https://github.com/pwncollege/dojo/tree/master/nginx-proxy/"
    click PM "https://github.com/pwncollege/dojo/tree/master/prometheus/"
    click GF "https://github.com/pwncollege/dojo/tree/master/grafana/"
    click ST "https://github.com/pwncollege/dojo/tree/master/etc/systemd/system/"
    click SSH "https://github.com/pwncollege/dojo/tree/master/sshd/"
    click WD "https://github.com/pwncollege/dojo/tree/master/watchdog/"
    click DF "https://github.com/pwncollege/dojo/blob/master/dojo_plugin/api/v1/discord.py"

    %% Styles
    classDef external fill:#e8daef,stroke:#8e44ad,stroke-width:2px;
    classDef frontend fill:#f9e79f,stroke:#d4ac0d,stroke-width:2px;
    classDef backend fill:#aed6f1,stroke:#2874a6,stroke-width:2px;
    classDef storage fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef orchestration fill:#f5cba7,stroke:#d35400,stroke-width:2px;
    classDef reverse fill:#fad7a0,stroke:#e67e22,stroke-width:2px;
    classDef monitoring fill:#d2b4de,stroke:#8e44ad,stroke-width:2px;
    classDef system fill:#c39bd3,stroke:#7d3c98,stroke-width:2px;
    classDef additional fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
```
