# a0xnirudh/kurukshetra architecture

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

- Interactive diagram: https://gitdiagram.com/a0xnirudh/kurukshetra
- Repository: https://github.com/a0xnirudh/kurukshetra

## Overview

##### Main Components
- Frontend – Divide this into two parts:
◦ The User Interface: Served from the “challenges” directory (challenge listing, challenge execution, results view, and public pages).
◦ The Admin Portal: Located in the “admin” directory, which includes pages for viewing and editing challenges, FAQs, container management, and statistics.
- Backend/API – Several PHP endpoints exist throughout directories such as “api” and “admin/api”. These endpoints handle:
◦ Challenge analytics (e.g., challenges_per_difficulty, challenges_per_language, challenges_per_type).
◦ User state updates and administrative actions (e.g., approve challenges, update user/faq state, kill challenges).
- Authentication Module – Managed via the “login” directory which integrates with Google OAuth. This portion encapsulates:
◦ Google API client libraries
◦ Authentication, token caching, and user session management.
- Database – Housed under the “database” directory, it consists of scripts for connection credentials and DB setup. It stores user data, challenge configuration, logs, and scores.
- Docker/Sandbox Integration – The backend framework utilizes Docker to securely run user-submitted code inside isolated containers. The “installation/optional” directory contains a Dockerfile and installation scripts to build the Kurukshetra sandbox image.
- Static Files – In “staticfiles”, you have assets such as CSS, JS (including Ace editor components), images (logos, screenshots), and fonts. This component supports both frontend UI and interactive coding functionalities.

##### Relationships and Interactions
- API Communication: Illustrate the connections between the admin API endpoints and backend services for updating challenge states, retrieving statistics, etc.
- Authentication Flow: Outline how the login module (Google OAuth in “login”) manages user authentication and bridges with other components.
- Docker Integration: Clearly map that when a challenge is submitted, the request passes from the backend to a Docker container (sandbox) for secure execution, then the result is relayed back to the user interface.

##### Architectural Patterns or Design Principles
- API-Based Communication: The use of REST-like endpoints (as seen in the “api” and “admin/api” directories) suggests a modular design where frontends consume backend services.
- Secure Execution: The integration of Docker for sandboxed execution is a key architectural element – mark this clearly as an isolated environment that the backend “orchestrates” for code execution.
- Third-Party Integration: Note the integration with Google OAuth for user authentication and external API calls managed by subcomponents in the “login/src/contrib” directory.

##### Technologies and Frameworks
- PHP is the primary server-side language.
- MySQL (as indicated by the database scripts) is used for data persistence.
- Docker is leveraged for creating a secure, isolated challenge execution environment.
- Frontend technologies include HTML/CSS/JavaScript and third-party libraries like Ace (from “staticfiles/ace”) for code editing and interactivity.
- Google OAuth libraries in PHP for authentication.

##### Specific Elements
- Clear labels for each component:
- “Frontend User Interface” (from challenges/)
- “Admin Portal” (from admin/)
- “REST API Endpoints” (backend PHP scripts in api/ and admin/api/)
- “Database” (MySQL, accessed via scripts in database/)
- “Authentication Service” (Google OAuth integration in login/)
- “Docker Sandbox” (execution environment built from installation/optional/)
- User request flow from browser to frontend and then backend.
- API and data exchanges between backend and database.
- Docker container interactions triggered by challenge submissions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    Browser["User Browser"]:::browser

    subgraph "Frontend Components"
        UI["Frontend User Interface"]:::frontend
        Admin["Admin Portal"]:::frontend
        SF["Static Files"]:::frontend
    end

    subgraph "Backend Components"
        API["REST API Endpoints"]:::backend
        Auth["Authentication Service"]:::auth
        GAuth["Google OAuth Libraries"]:::auth
    end

    subgraph "Database"
        DB1["DB Credentials"]:::database
        DB2["DB Setup"]:::database
    end

    subgraph "Docker Sandbox"
        Dockerfile["Dockerfile"]:::docker
        Install["Install Script"]:::docker
    end

    %% Data Flow from Browser to Frontend
    Browser -->|"challenge_req"| UI
    Browser -->|"admin_req"| Admin

    %% Frontend interactions with Backend
    UI -->|"API_calls"| API
    Admin -->|"API_calls"| API
    UI -->|"auth_req"| Auth

    %% Authentication Service utilizing Google OAuth libraries
    Auth -->|"uses"| GAuth

    %% Backend interacting with Database
    API -->|"DB_query"| DB1
    API -->|"DB_query"| DB2

    %% Backend triggers Docker Sandbox for secure code execution
    API -->|"execute_code"| Dockerfile
    Dockerfile -->|"run_install"| Install

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef backend fill:#ABEBC6,stroke:#1D8348,stroke-width:2px;
    classDef auth fill:#D2B4DE,stroke:#7D3C98,stroke-width:2px;
    classDef database fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef docker fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef browser fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;

    %% Click Events
    click UI "https://github.com/a0xnirudh/kurukshetra/tree/master/challenges/"
    click Admin "https://github.com/a0xnirudh/kurukshetra/tree/master/admin/"
    click API "https://github.com/a0xnirudh/kurukshetra/tree/master/api/"
    click Auth "https://github.com/a0xnirudh/kurukshetra/tree/master/login/"
    click GAuth "https://github.com/a0xnirudh/kurukshetra/tree/master/login/src/contrib/"
    click DB1 "https://github.com/a0xnirudh/kurukshetra/blob/master/database/db_credentials.php"
    click DB2 "https://github.com/a0xnirudh/kurukshetra/blob/master/database/db_setup.php"
    click Dockerfile "https://github.com/a0xnirudh/kurukshetra/tree/master/installation/optional/Dockerfile"
    click Install "https://github.com/a0xnirudh/kurukshetra/blob/master/installation/optional/install.py"
    click SF "https://github.com/a0xnirudh/kurukshetra/tree/master/staticfiles/"
```
