# dmoj/online-judge architecture

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

- Interactive diagram: https://gitdiagram.com/dmoj/online-judge
- Repository: https://github.com/dmoj/online-judge

## Overview

##### Project Type and Purpose
- This is a full-stack, monolithic Django web application augmented by asynchronous and real-time microservices to form the DMOJ online judge and contest platform.
- The core handles user and contest management, problem rendering, submissions, and administration. Background workers execute judging tasks; a separate judge bridge interfaces with an external judge-server cluster; real-time updates flow over WebSockets.

##### Main Components
a. Clients and Entry Points
- Web Browser (users) – HTTP(S) and WebSocket clients for site UI, live submission updates, and admin interfaces.
- Load Balancer / Reverse Proxy – distributes incoming HTTP and WS connections to Django app servers or WebSocket servers; can also serve static assets or forward to a CDN.
b. Web Application Layer
- Django Application Servers – handle HTTP requests (views, forms, REST/API), render Jinja2 templates, process authentication (OAuth, two-factor), manage sessions, and serve static/media.
- WSGI / ASGI Interfaces – synchronous WSGI (dmoj/wsgi.py) for HTTP; ASGI or custom WebSocket daemon scripts (websocket/*.js) for real-time channels.
c. Data and Persistence
- Relational Database (PostgreSQL/MySQL) – stores models: users, problems, contests, submissions, scores, etc.
- Caching Layer (Redis/Memcached) – optional; used by Django and Celery for caching querysets, throttles, and session data.
- File Storage – for user uploads, generated PDFs, static resources (could be local or S3).
d. Asynchronous Task Processing
- Celery Workers – process background jobs: submission dispatch, system testing, PDF generation, notifications, event posting.
- Message Broker (RabbitMQ/Redis/AMQP) – queues jobs between Django and Celery; also used by event_poster_amqp.
e. Judge Integration
- Judge Bridge Daemon (judge/bridge/daemon.py) – a long-running process that consumes judging requests from the broker and forwards them to one or more external judge-server instances.
- Judge-Server Cluster (external microservices) – sandboxed execution environments that compile and run submitted code, enforce resource limits, and return results.
f. Real-Time Event Delivery
- Event Poster (judge/event_poster_ws.py or AMQP variant) – publishes status changes (submission progress, contest scoreboard updates) onto WebSocket channels or message broker topics.
- WebSocket Servers / Consumers – maintain persistent connections to browsers and push live updates.
g. External Services
- OAuth Providers (Google, GitHub, Facebook) for social login
- Stanford MOSS for plagiarism detection
- Email / Mailgun for notifications
- MathJax CDN for rendering LaTeX

##### Relationships and Interactions
1. User → HTTP(S) → Load Balancer → Django App → Database / Cache
2. Django → Celery via Message Broker → Celery Worker → Database / Judge Bridge
3. Judge Bridge ↔ AMQP → Judge-Server Cluster → Judge Bridge → Database
4. Submission status changes → Celery or Django event_poster → Message Broker / WS → WebSocket Server → Web Browser
5. Django → External OAuth / MOSS / Email APIs

##### Architectural Patterns and Principles
- MVC (Django models-views-templates) for the core web app.
- Asynchronous, event-driven architecture for long-running judge tasks (Celery + message broker).
- Microservices for isolated, scalable code execution (judge-server cluster).
- Pub/Sub pattern for real-time updates (AMQP or Redis channels feeding WebSockets).
- Clear separation of concerns: presentation (HTTP + WS), application logic (Django), background processing (Celery), execution (judge-server), persistent storage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: Clients & Entry Points
    subgraph "Layer 1: Clients & Entry Points"
        direction TB
        Client["Web Browser (HTTP/WS)"]:::blue
        LB["Load Balancer / Reverse Proxy"]:::blue
    end

    %% Layer 2: Django Web App & WebSocket Servers
    subgraph "Layer 2: Django Web App & WebSocket Servers"
        direction TB
        Settings["Django Settings & Configuration"]:::green
        URLs["URL Routing (HTTP endpoints)"]:::green
        WSGI["WSGI HTTP Interface"]:::green
        ASGI["ASGI / WebSocket Interface"]:::green
        DjangoApp["Django App (Python, WSGI, Jinja2)"]:::green
        WebSocketSrv["WebSocket Server / Consumers"]:::green
        Templates["Jinja2 Templates"]:::green
        Static["Static Assets & Frontend Resources"]:::green
    end

    %% Layer 3: Celery Workers & Judge Bridge
    subgraph "Layer 3: Asynchronous & Judge Integration"
        direction TB
        Broker["Message Broker (AMQP/Redis)"]:::orange
        CeleryCfg1["Celery Configuration"]:::orange
        CeleryCfg2["Django Celery Setup"]:::orange
        Tasks["Background Jobs (Celery Workers)"]:::orange
        EventAMQP["AMQP-based Event Poster"]:::orange
        EventWS["WebSocket-based Event Poster"]:::orange
        Bridge["Judge Bridge Daemon"]:::orange
    end

    %% Layer 4: Data & Persistence
    subgraph "Layer 4: Data & Persistence"
        direction TB
        DB["Relational Database (PostgreSQL/MySQL)"]:::yellow
        Cache["Caching Layer (Redis/Memcached)"]:::yellow
        FileStore["File Storage (uploads, static)"]:::yellow
    end

    %% Layer 5: External Judge & Third-Party Services
    subgraph "Layer 5: External Judge & Third-Party Services"
        direction TB
        JudgeCluster["Judge-Server Cluster"]:::red
        OAuth["OAuth Providers (Google, GitHub, Facebook)"]:::external
        MOSS["Stanford MOSS"]:::external
        EmailSvc["Email / Mailgun"]:::external
        MathJax["MathJax CDN"]:::external
    end

    %% Connections
    Client -->|"HTTP(S)/WebSocket"| LB
    LB -->|"HTTP"| WSGI
    LB -->|"WebSocket"| ASGI
    WSGI -->|loads| Settings
    WSGI -->|routes| URLs
    URLs -->|calls| DjangoApp
    DjangoApp -->|renders| Templates
    DjangoApp -->|serves| Static
    DjangoApp -->|SQL| DB
    DjangoApp -->|cache| Cache
    DjangoApp -->|stores| FileStore
    DjangoApp -->|"invoke tasks via AMQP"| Broker
    ASGI -->|persistent WS| WebSocketSrv
    WebSocketSrv -->|pub/sub via AMQP| Broker
    Broker -->|tasks| Tasks
    Tasks -->|SQL| DB
    Tasks -->|emit events AMQP| EventAMQP
    Tasks -->|emit events WS| EventWS
    EventAMQP -->|AMQP pub/sub| Broker
    EventWS -->|WS push| WebSocketSrv
    Bridge -->|consume jobs| Broker
    Bridge -->|dispatch judge requests| JudgeCluster
    JudgeCluster -->|results| Bridge
    Bridge -->|store results| DB
    DjangoApp -->|OAuth API calls| OAuth
    DjangoApp -->|MOSS API calls| MOSS
    DjangoApp -->|Email API calls| EmailSvc
    DjangoApp -->|load MathJax| MathJax

    %% Click Events
    click Settings "https://github.com/dmoj/online-judge/blob/master/dmoj/settings.py"
    click WSGI "https://github.com/dmoj/online-judge/blob/master/dmoj/wsgi.py"
    click ASGI "https://github.com/dmoj/online-judge/blob/master/dmoj/wsgi_async.py"
    click ASGI "https://github.com/dmoj/online-judge/blob/master/websocket/daemon.js"
    click URLs "https://github.com/dmoj/online-judge/blob/master/dmoj/urls.py"
    click CeleryCfg1 "https://github.com/dmoj/online-judge/blob/master/dmoj/celery.py"
    click CeleryCfg2 "https://github.com/dmoj/online-judge/blob/master/dmoj_celery.py"
    click Tasks "https://github.com/dmoj/online-judge/tree/master/judge/tasks/"
    click EventAMQP "https://github.com/dmoj/online-judge/blob/master/judge/event_poster_amqp.py"
    click EventWS "https://github.com/dmoj/online-judge/blob/master/judge/event_poster_ws.py"
    click Bridge "https://github.com/dmoj/online-judge/blob/master/judge/bridge/daemon.py"
    click Models "https://github.com/dmoj/online-judge/tree/master/judge/models/"
    click Views "https://github.com/dmoj/online-judge/tree/master/judge/views/"
    click Templates "https://github.com/dmoj/online-judge/tree/master/templates/"
    click Static "https://github.com/dmoj/online-judge/tree/master/resources/"
    click SocialAuth "https://github.com/dmoj/online-judge/blob/master/judge/social_auth.py"
    click MOSS "https://github.com/dmoj/online-judge/blob/master/judge/management/commands/runmoss.py"
    click EmailSvc "https://github.com/dmoj/online-judge/blob/master/judge/views/mailgun.py"
    click Caching "https://github.com/dmoj/online-judge/blob/master/judge/caching.py"
    click Caching "https://github.com/dmoj/online-judge/blob/master/judge/utils/celery.py"

    %% Styles
    classDef blue fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef green fill:#DFFFE0,stroke:#28a745,color:#28a745
    classDef orange fill:#FFF0D0,stroke:#d9822b,color:#d9822b
    classDef yellow fill:#FFFAE0,stroke:#e36209,color:#e36209
    classDef red fill:#FFE0E0,stroke:#d73a49,color:#d73a49
    classDef external stroke-dasharray: 5 5,fill:none,stroke:#6a737d,color:#6a737d
    class Settings,URLs,WSGI,ASGI,DjangoApp,WebSocketSrv,Templates,Static green
    class Client,LB blue
    class Broker,CeleryCfg1,CeleryCfg2,Tasks,EventAMQP,EventWS,Bridge orange
    class DB,Cache,FileStore yellow
    class JudgeCluster red
    class OAuth,MOSS,EmailSvc,MathJax external
```
