# vnoi-admin/oj architecture

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

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

## Overview

##### Main Components
- Web Frontend & Presentation Layer:
– This includes all the Django templates (in the “templates” directory) and static assets (e.g., resources, django_ace/static).
– It serves the user interfaces for problem submission, contests, blog posts, account management, and the administration dashboard.
- Django Backend Application:
– Core Django projects are found in “dmoj” (settings, URL routing, WSGI, celery, etc.) and “judge” (which contains models, views, administration, middleware, and a number of management commands).
– This layer handles requests, interacts with the database, and dispatches tasks.
- Judging Engine / Evaluation Subsystem:
– The “judge” directory also contains submodules including “balancer”, “bridge”, and “contest_format” that coordinate the actual code evaluation and submission grading processes.
– Files like “runbalancer” and “runbridged”, in addition to celery integration (e.g., “dmoj/celery.py”), indicate asynchronous processing of judging tasks.
- Task Queue and Background Workers:
– Celery is configured for background processing, as seen via “celery.py” files and the “judge/tasks” scripts.
– This component handles asynchronous jobs (e.g., problem evaluation, sending notifications, updating caches) and may interact with message brokers.
- Caching & Data Storage:
– The configuration (described in the README) suggests the use of caching systems like Redis or Memcached for performance and synchronization between the judge server and the web backend.
- External Integrations & Services:
– Modules like “throttle_discord_webhook.py” and “throttle_mail.py” indicate integrations for notifications, while the instructions around “testlib.h” show external dependencies for compiling submissions.
- Real-Time Communication:
– The “websocket” directory (with its daemon.js and queue.js) implies a mechanism for real-time data (for status updates, judging progress, or live notifications).

##### Relationships & Interactions
- The user sends a request via the browser (rendered using Django templates and static resources).
– The Web Frontend communicates with the Django Backend (HTTP layer – forms, APIs, etc.).
- The Backend processes submissions and contest interactions, updates the database, and enqueues judging tasks to the Task Queue.
- The Task Queue processes jobs:
– Asynchronous workers pick up tasks (such as judging a submission) via Celery.
– The Judging Engine picks up these tasks (through components in “judge/balancer” and “judge/bridge”) and performs compilation, execution and evaluation.
- Once evaluated, results flow back via the queue to update the Django application, which in turn updates the user interfaces (scoreboards, submission status, notifications, etc.).
- Additionally, external services (Discord, email servers) are triggered to send notifications.

##### Architectural Patterns and Design Principles
- Modular Design: The system is split into multiple apps (e.g., “dmoj”, “judge”, “django_ace”), making it easier to maintain and scale individual components.
- Asynchronous Processing: Heavy tasks such as judging code submissions are handled in the background using Celery and dedicated judging daemons.
- MVC Pattern: Django’s structure facilitates a clear separation of concerns between models (in “judge/models”), views (in “judge/views”), and templates (in “templates”).
- Extension and Plugin Mechanism: The “contest_format” and “bridge” modules support multiple formats and judging strategies that can be extended for different contest rules or languages.

##### Technology, Frameworks & Libraries to Highlight
- Django (Core framework, URL routing, ORM, templating, and middleware).
- Celery for asynchronous task processing.
- Redis/Memcached for caching (as recommended in the README).
- Websocket components for real-time communications.
- Various front-end tools/libraries (e.g., Prettier, flake8, and static assets like SCSS/JS files in resources).
- Integration with external libraries (like testlib for compiling submissions).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes
    User["User Browser"]:::user

    subgraph "Web Frontend & Presentation Layer"
        templates["Django Templates"]:::frontend
        static_res["Static Assets (resources)"]:::frontend
        ace_static["Django Ace Static Assets"]:::frontend
    end

    subgraph "Django Backend Application"
        backend["Django Core (dmoj)"]:::backend
        judgeapp["Judge App (judge)"]:::backend
    end

    subgraph "Task Queue & Background Workers"
        celery["Celery Integration"]:::taskqueue
        tasks["Background Task Scripts"]:::taskqueue
    end

    subgraph "Judging Engine / Evaluation Subsystem"
        balancer["Balancer Modules"]:::judgeengine
        bridge["Bridge Modules"]:::judgeengine
        contest["Contest Format Support"]:::judgeengine
    end

    subgraph "Caching & Data Storage"
        cache["Caching Logic (Redis/Memcached)"]:::caching
    end

    subgraph "External Integrations & Services"
        discord["Discord Webhook Notifications"]:::external
        email["Email Notifications"]:::external
    end

    subgraph "Real-Time Communication"
        websocket["Websocket Components"]:::realtime
    end

    %% Connections
    User --> templates
    User --> static_res
    User --> ace_static
    templates --> backend
    backend --> judgeapp
    backend --> celery
    judgeapp --> celery
    celery --> tasks
    tasks --> balancer
    tasks --> bridge
    tasks --> contest
    balancer --> judgeapp
    bridge --> judgeapp
    contest --> judgeapp
    judgeapp --> cache
    backend --> discord
    backend --> email
    backend --> websocket
    websocket --> User

    %% Click Events
    click templates "https://github.com/vnoi-admin/oj/tree/master/templates"
    click static_res "https://github.com/vnoi-admin/oj/tree/master/resources"
    click ace_static "https://github.com/vnoi-admin/oj/tree/master/django_ace/static"
    click backend "https://github.com/vnoi-admin/oj/tree/master/dmoj"
    click judgeapp "https://github.com/vnoi-admin/oj/tree/master/judge"
    click celery "https://github.com/vnoi-admin/oj/blob/master/dmoj/celery.py"
    click tasks "https://github.com/vnoi-admin/oj/tree/master/judge/tasks"
    click balancer "https://github.com/vnoi-admin/oj/tree/master/judge/balancer"
    click bridge "https://github.com/vnoi-admin/oj/tree/master/judge/bridge"
    click contest "https://github.com/vnoi-admin/oj/tree/master/judge/contest_format"
    click cache "https://github.com/vnoi-admin/oj/blob/master/judge/caching.py"
    click discord "https://github.com/vnoi-admin/oj/blob/master/dmoj/throttle_discord_webhook.py"
    click email "https://github.com/vnoi-admin/oj/blob/master/dmoj/throttle_mail.py"
    click websocket "https://github.com/vnoi-admin/oj/tree/master/websocket"

    %% Styles
    classDef user fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef frontend fill:#a8d5e2,stroke:#333,stroke-width:2px;
    classDef backend fill:#f7a072,stroke:#333,stroke-width:2px;
    classDef taskqueue fill:#fce38a,stroke:#333,stroke-width:2px;
    classDef judgeengine fill:#f38181,stroke:#333,stroke-width:2px;
    classDef caching fill:#95e1d3,stroke:#333,stroke-width:2px;
    classDef external fill:#c9c5ba,stroke:#333,stroke-width:2px;
    classDef realtime fill:#b5e3b5,stroke:#333,stroke-width:2px;
```
