# lugvitc/pwncore architecture

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

- Interactive diagram: https://gitdiagram.com/lugvitc/pwncore
- Repository: https://github.com/lugvitc/pwncore

## Overview

##### Main Components
- API Layer: Represent FastAPI as the central HTTP server. Mark that the FastAPI app facilitates auto-generated documentation (via /docs and /redoc endpoints).
- Routes: Distinguish the different sets of routes such as:
– Authentication routes (admin.py, auth.py)
– CTF functionality routes (in the ctf sub-directory; e.g., start, pre_event)
– Other endpoints like leaderboard and team management.
- Business Logic / Controllers: Indicate that the actual handling of logic is split into different modules. For instance, container management (containerASD.py) and additional route-specific business logic.
- Models/ORM Layer: Emphasize using Tortoise-ORM with clearly defined models (user, container, ctf, pre_event). Show that these models handle data persistence.
- Configuration: Include a configuration block (from config.py) responsible for setting parameters such as the database URL and Docker service URL.
- Docker / Container Integration: Highlight that the platform can launch or manage Docker containers (see container modules and Docker configurations in both config.py and Dockerfile/docker-compose.yaml).
- Testing: Although not a runtime component, include an indication of testing infrastructure using tox and tests (which are designed to validate critical functionalities).

##### Relationships and Interactions
- Route to Controller: Demonstrate how each route (e.g., authentication, leaderboard, CTF routes) maps to underlying business logic modules.
- External Services: If Docker functionality is enabled, show that certain routes invoke container management services, communicating with the Docker engine (or a simulated Docker endpoint using the provided Docker URL).
- Documentation: Mention that FastAPI’s auto-generated OpenAPI docs are a natural byproduct of well-documented route implementations.

##### Architectural Patterns & Design Principles
- Layered Architecture: The project separates concerns into configuration, routing, business logic, and models, making it easier to maintain.
- RESTful API Principles: Since the service uses FastAPI, the routes follow REST-like conventions to expose endpoints for various CTF functionalities.
- Dependency Injection (implicit): While not explicitly detailed, the project likely uses dependency injection patterns (common in FastAPI) to inject settings and database connections.
- Containerization: The Dockerfiles and docker-compose.yaml files indicate an architecture that is designed with both local and containerized execution in mind.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client and API Layer
    Client["Client Requests"]:::external
    FastAPI["FastAPI Server\n(Serves /docs and /redoc)"]:::api
    Docs["API Documentation\n(/docs, /redoc)"]:::api

    %% Routes Subgraphs
    subgraph "Routes Layer"
        direction TB
        AuthRoutes["Authentication Routes"]:::routes
        Auth1["Auth Routes"]:::routes
        Auth2["Admin Routes"]:::routes

        CTFRoutes["CTF Functionality Routes"]:::routes
        CTF1["Pre Event Route"]:::routes
        CTF2["Start Route"]:::routes

        OtherRoutes["Other Endpoints"]:::routes
        Other1["Leaderboard Route"]:::routes
        Other2["Team Route"]:::routes
    end

    %% Business Logic / Controllers
    BL["Container Management Controller"]:::logic

    %% Models / ORM Layer
    subgraph "ORM Models"
        direction TB
        Model1["User Model"]:::models
        Model2["Container Model"]:::models
        Model3["CTF Model"]:::models
        Model4["Pre Event Model"]:::models
    end

    %% Configuration Service
    Config["Configuration Service"]:::config

    %% Docker / Container Integration
    subgraph "Container Integration"
        direction TB
        Docker1["Dockerfile"]:::container
        Docker2["Docker Compose"]:::container
    end

    %% Testing Infrastructure
    subgraph "Testing & CI"
        direction TB
        Tox["tox.ini"]:::testing
        Tests["tests/ Directory"]:::testing
        CI["GitHub Workflow\n(.github/workflows/tox.yml)"]:::testing
    end

    %% Relationships
    Client -->|"HTTP Request"| FastAPI
    FastAPI -->|"Auto-generate docs"| Docs
    FastAPI -->|"Routes call"| AuthRoutes
    FastAPI -->|"Routes call"| CTFRoutes
    FastAPI -->|"Routes call"| OtherRoutes

    %% Routes linking to specific implementations
    AuthRoutes --> Auth1
    AuthRoutes --> Auth2
    CTFRoutes --> CTF1
    CTFRoutes --> CTF2
    OtherRoutes --> Other1
    OtherRoutes --> Other2

    %% Routes to Business Logic
    Auth1 -->|"Process authentication"| BL
    Auth2 -->|"Process admin logic"| BL
    CTF1 -->|"Handle CTF pre-event"| BL
    CTF2 -->|"Initiate CTF challenge"| BL
    Other1 -->|"Fetch leaderboard"| BL
    Other2 -->|"Manage teams"| BL

    %% Business Logic interactions
    BL -->|"Database operations"| Model1
    BL -->|"Database operations"| Model2
    BL -->|"Database operations"| Model3
    BL -->|"Database operations"| Model4
    BL -->|"Manage containers"| Docker1
    BL -->|"Manage containers"| Docker2

    %% Configuration feeds both Business Logic and Container Integration
    Config -->|"Settings injected into"| BL
    Config -->|"Docker URL settings"| Docker2

    %% Click Events for API Layer
    click FastAPI "https://github.com/lugvitc/pwncore/blob/master/src/pwncore/__main__.py"
    click Docs "https://github.com/lugvitc/pwncore/blob/master/src/pwncore/docs.py"

    %% Click Events for Routes - Authentication
    click Auth1 "https://github.com/lugvitc/pwncore/blob/master/src/pwncore/routes/auth.py"
    click Auth2 "https://github.com/lugvitc/pwncore/blob/master/src/pwncore/routes/admin.py"

    %% Click Events for Routes - CTF Functionality
    click CTF1 "https://github.com/lugvitc/pwncore/blob/master/src/pwncore/routes/ctf/pre_event.py"
    click CTF2 "https://github.com/lugvitc/pwncore/blob/master/src/pwncore/routes/ctf/start.py"

    %% Click Events for Routes - Other Endpoints
    click Other1 "https://github.com/lugvitc/pwncore/blob/master/src/pwncore/routes/leaderboard.py"
    click Other2 "https://github.com/lugvitc/pwncore/blob/master/src/pwncore/routes/team.py"

    %% Click Event for Business Logic
    click BL "https://github.com/lugvitc/pwncore/blob/master/src/pwncore/containerASD.py"

    %% Click Events for ORM Models
    click Model1 "https://github.com/lugvitc/pwncore/blob/master/src/pwncore/models/user.py"
    click Model2 "https://github.com/lugvitc/pwncore/blob/master/src/pwncore/models/container.py"
    click Model3 "https://github.com/lugvitc/pwncore/blob/master/src/pwncore/models/ctf.py"
    click Model4 "https://github.com/lugvitc/pwncore/blob/master/src/pwncore/models/pre_event.py"

    %% Click Event for Configuration
    click Config "https://github.com/lugvitc/pwncore/blob/master/src/pwncore/config.py"

    %% Click Events for Docker / Container Integration
    click Docker1 "https://github.com/lugvitc/pwncore/tree/master/Dockerfile"
    click Docker2 "https://github.com/lugvitc/pwncore/blob/master/docker-compose.yaml"

    %% Click Events for Testing Infrastructure
    click Tox "https://github.com/lugvitc/pwncore/blob/master/tox.ini"
    click Tests "https://github.com/lugvitc/pwncore/tree/master/tests/"
    click CI "https://github.com/lugvitc/pwncore/blob/master/.github/workflows/tox.yml"

    %% Styling classes and colors
    classDef external fill:#ffefc3,stroke:#d58512,stroke-width:2px;
    classDef api fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef routes fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef logic fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef models fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef config fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef container fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef testing fill:#fefefe,stroke:#818182,stroke-width:2px;
```
