# chawinkn/judge-ma-di architecture

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

- Interactive diagram: https://gitdiagram.com/chawinkn/judge-ma-di
- Repository: https://github.com/chawinkn/judge-ma-di

## Overview

##### Project type and purpose
- This is a backend-focused “Programming Judge System” (Judge Ma Di), written in Rust, exposing a REST API for submitting code, dispatching it to a sandbox (IOI Isolate), and returning judge results.
- It relies on Axum (HTTP), RabbitMQ (job queue), PostgreSQL (persistence), and the IOI Isolate tool for safe execution.

##### High-level file-structure analysis
- Top-level files and config:
- Dockerfile, docker-compose.yml, .env.example – define containerized environments (Axum server, RabbitMQ, Postgres, Isolate).
- config.json, setup.sh, checker.sh – sandbox and system setup scripts.
- test.py – a simple client to exercise API endpoints.
- src/: Application code organized into modules:
- main.rs – server bootstrap.
- rbmq.rs – RabbitMQ producer/consumer logic.
- isolate.rs & runner.rs – encapsulate sandbox invocation and job-processing loop.
- helper.rs – shared utilities.
- routes/ – HTTP route handlers (desc, healthchecker, manifest, submission, task).

##### Key README insights
- Core services: HTTP API, job queue, sandbox, database.
- Env var MAX_WORKER throttles concurrent runners.
- Docker Compose spawns Axum server, RabbitMQ, Postgres, optionally the isolate service.

##### Main components
a. HTTP API Layer (Axum server)
– Handles incoming requests on endpoints: /health, /desc, /submission, /manifest, /task.
– Reads/Writes to PostgreSQL and enqueues submission jobs to RabbitMQ.
b. Job Queue (RabbitMQ)
– Holds incoming code-judge tasks, decouples request handling from execution.
c. Runner & Sandbox (runner.rs + IOI Isolate)
– Worker process that consumes messages from RabbitMQ, runs submissions inside the Isolate sandbox via checker.sh, and pushes results back.
d. Persistence Layer (PostgreSQL)
– Stores submission metadata, statuses, results.
e. Configuration & Orchestration
– Docker Compose spins up all services; .env and config.json provide runtime parameters.
f. Optional Frontend / Client
– test.py or any UI consuming the JSON API to display results.

##### Relationships and data flow
1. Client → HTTP API (/submission)
2. API writes submission metadata to Postgres
3. API publishes a “new submission” message to RabbitMQ
4. Runner service subscribes to queue, receives job
5. Runner invokes IOI Isolate with code & test data (via isolate.rs + checker.sh)
6. Sandbox executes code, returns verdict and logs
7. Runner updates submission status and results in Postgres
8. Client polls API (/task or /manifest) to retrieve final status and details

##### Architectural patterns & design principles
- Separation of concerns: HTTP layer, queueing, execution, and persistence are distinct modules/services.
- Asynchronous, event-driven processing via RabbitMQ for scalability and reliability.
- Sandboxed execution isolating untrusted code.
- Configuration-driven deployment (Docker + .env + config.json).

## Diagram (Mermaid)

```mermaid
graph TD
    Client["Test Client\ntest.py"]:::client
    API["HTTP API Server\nAxum + Rust"]:::compute
    subgraph "API Code"
        Main["main.rs"]:::compute
        Helper["helper.rs"]:::compute
        Routes["routes/"]:::compute
    end
    RabbitMQ["RabbitMQ Queue"]:::queue
    DB["PostgreSQL"]:::db
    subgraph "Runner & Sandbox"
        Runner["Runner Service\nrunner.rs"]:::compute
        Isolate["IOI Isolate\nisolate.rs + checker.sh"]:::sandbox
    end
    Config["Config & Orchestration"]:::config

    Client -->|"Submit code"| API
    API -->|"Write metadata"| DB
    API -->|"Publish job"| RabbitMQ
    RabbitMQ -->|"Consume job"| Runner
    Runner -->|"Invoke sandbox"| Isolate
    Isolate -->|"Return verdict"| Runner
    Runner -->|"Update result"| DB
    Client -->|"Fetch status"| API

    Config -.-> API
    Config -.-> RabbitMQ
    Config -.-> DB
    Config -.-> Runner

    click Main "https://github.com/chawinkn/judge-ma-di/blob/master/src/main.rs"
    click Helper "https://github.com/chawinkn/judge-ma-di/blob/master/src/helper.rs"
    click Routes "https://github.com/chawinkn/judge-ma-di/tree/master/src/routes/"
    click RabbitMQ "https://github.com/chawinkn/judge-ma-di/blob/master/src/rbmq.rs"
    click Runner "https://github.com/chawinkn/judge-ma-di/blob/master/src/runner.rs"
    click Isolate "https://github.com/chawinkn/judge-ma-di/blob/master/src/isolate.rs"
    click Isolate "https://github.com/chawinkn/judge-ma-di/blob/master/checker.sh"
    click DB "https://github.com/chawinkn/judge-ma-di/blob/master/docker-compose.yml"
    click Config "https://github.com/chawinkn/judge-ma-di/tree/master/Dockerfile"
    click Config "https://github.com/chawinkn/judge-ma-di/blob/master/docker-compose.yml"
    click Config "https://github.com/chawinkn/judge-ma-di/blob/master/.env.example"
    click Config "https://github.com/chawinkn/judge-ma-di/blob/master/config.json"
    click Config "https://github.com/chawinkn/judge-ma-di/blob/master/setup.sh"
    click Client "https://github.com/chawinkn/judge-ma-di/blob/master/test.py"

    classDef compute fill:#AED6F1,stroke:#2980B9,color:#000
    classDef queue fill:#F5B041,stroke:#D35400,color:#000
    classDef db fill:#ABEBC6,stroke:#27AE60,color:#000
    classDef sandbox fill:#D2B4DE,stroke:#8E44AD,color:#000
    classDef config fill:#F8C471,stroke:#B9770E,color:#000
    classDef client fill:#D6DBDF,stroke:#566573,color:#000
```
