# cht-oj/oj architecture

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

- Interactive diagram: https://gitdiagram.com/cht-oj/oj
- Repository: https://github.com/cht-oj/oj

## Overview

##### Main Components
- Django Web Application: At the core is the Django project (files like manage.py, dmoj/settings.py, and a plethora of templates under the “templates” directory). This includes admin interfaces, user registration, contest listings, problem management, etc.
- Judge Engine and Bridge: The “judge” module (with subdirectories such as admin, bridge, models, views, tasks, etc.) encapsulates the judging logic. The “bridge” subdirectory shows components for interacting with external judge servers, handling submissions, and relaying data.
- Worker Processes / Celery: Files like dmoj/celery.py, dmoj_celery.py, and the commands under “judge/management/commands” indicate asynchronous background processing (for tasks such as evaluating submissions, sending notifications, etc.). These typically run as Celery workers.
- Problem Data & Test Files: The README calls out that you must define DMOJ_PROBLEM_DATA_ROOT. This means there’s an external repository of problem test cases that the judge system references.
- Frontend Assets & WebSockets: The “resources” folder contains extensive SCSS, JavaScript, and static assets. There is also a “websocket” directory which indicates real-time communication components (perhaps for updates on submissions or contest events).
- Auxiliary Services: Based on the README, a caching service (memcached or redis) is suggested for synchronizing the judge server and caching responses. In addition, an external compile-time precompiled header for testlib.h and possibly a message broker (often RabbitMQ, though not explicitly stated) is used by the Celery configuration.

##### Relationships and Data Flow
- Users interact with the Web Frontend (Django templates) via HTTP(S), submitting solutions and accessing contest/problem information.
- The Django Backend processes these requests, invoking business logic from various “judge” modules and managing database transactions.
- When a submission is received, it is queued via Celery and passed to judge processes (or separate judge daemons via the “judge/bridge” components) that execute the submission against the problem’s test cases.
- The judge server sends back status/results to the Django application, which then updates the user’s view.
- Real-time updates (e.g., for submission status) could be managed via the WebSocket components.
- Data persistence is handled by the project’s configured database (e.g., PostgreSQL/MySQL—implied by Django’s usage).
- Caching (memcached/redis) enhances performance, particularly for high-traffic contest events.

##### Architectural Patterns and Design Principles
- MVC (Model-View-Controller) Pattern: Django’s structure inherently employs this, evident in the “models”, “views”, “templates” directories.
- Modular Decomposition: The separation of “judge”, “dmoj”, and “django_ace” demonstrates clear division of concerns.
- Asynchronous Processing: The use of Celery and separate background tasks for judging submissions highlights the separation of real-time user interaction from computationally heavy processes.
- Extensibility: With a well-structured admin interface, pluggable “bridge” components, and clearly defined management commands, the system is designed for extensibility and adaptation.

##### Relevant Technologies & Frameworks
- Django Framework for the web application.
- Celery for asynchronous task processing.
- WebSockets (with accompanying JavaScript and TypeScript components) for real-time communications.
- Frontend libraries/assets (SCSS, JavaScript) for user interface rendering.
- External cache systems (memcached/redis) as per deployment needs.
- Possibly a message queue (commonly RabbitMQ) that underlies Celery tasks.

##### Detailing the Architecture
- Different modules like contest formatting (judge/contest_format) and middleware aspects (judge/middleware).
- Relationship between the management commands (under judge/management/commands) that help administer and maintain the judge system.
- Do note the “bridge” subdirectory that handles the interface between Django and the submission judging daemons.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        A["User"]:::external
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        B["Web Interface"]:::frontend
        C["Frontend Assets"]:::frontend
        D["WebSocket Server"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        E["Django Application"]:::backend
        subgraph "Django Application Components"
            E1["manage.py"]:::backend
            E2["Settings & URL Routing"]:::backend
            E3["Templates"]:::backend
        end
        F["Celery Workers"]:::worker
        G["Management Commands"]:::worker
        H["Judge Engine"]:::judge
        subgraph "Judge Engine Modules"
            H1["Judge Core"]:::judge
            H2["Bridge Component"]:::judge
            H3["Problem Data Model"]:::data
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        I["Database"]:::data
        J["Cache"]:::data
    end

    %% Auxiliary Services
    subgraph "Auxiliary Services"
        K["External Services"]:::external
    end

    %% Connections
    A -->|"initiates"| B
    B -->|"requests"| E
    C -->|"loads assets"| B
    D -->|"pushes updates"| B

    E -->|"handles request"| I
    E -->|"queues task"| F
    E -->|"invokes commands"| G

    F -->|"processes submissions"| H
    G -->|"admin operations"| H

    H -->|"updates status"| I
    H -->|"updates cache"| J

    %% Auxiliary interactions
    E ---|"integrates alerts"| K
    F ---|"uses broker"| K

    %% Click Events
    click E1 "https://github.com/cht-oj/oj/blob/master/manage.py"
    click E2 "https://github.com/cht-oj/oj/blob/master/dmoj/settings.py"
    click E3 "https://github.com/cht-oj/oj/tree/master/templates/"
    click F "https://github.com/cht-oj/oj/blob/master/dmoj/celery.py"
    click F "https://github.com/cht-oj/oj/blob/master/dmoj_celery.py"
    click F "https://github.com/cht-oj/oj/tree/master/judge/tasks/"
    click G "https://github.com/cht-oj/oj/tree/master/judge/management/commands/"
    click H1 "https://github.com/cht-oj/oj/tree/master/judge/"
    click H2 "https://github.com/cht-oj/oj/tree/master/judge/bridge/"
    click H3 "https://github.com/cht-oj/oj/blob/master/judge/models/problem_data.py"
    click C "https://github.com/cht-oj/oj/tree/master/resources/"
    click D "https://github.com/cht-oj/oj/tree/master/websocket/"
    click K "https://github.com/cht-oj/oj/blob/master/dmoj/throttle_discord_webhook.py"
    click K "https://github.com/cht-oj/oj/blob/master/dmoj/throttle_mail.py"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef worker fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef judge fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef data fill:#e2e3e5,stroke:#41464b,stroke-width:2px;
    classDef external fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
```
