# xssandreissx/code-runner architecture

> Architecture diagram of the GitHub repository xssandreissx/code-runner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xssandreissx/code-runner
- Repository: https://github.com/xssandreissx/code-runner

## Overview

code-runner accepts test suites and authenticated code submissions from external services, queues judging work, runs tests in a sandboxed worker, persists verdicts, and exposes status/results. The main path is API submission handling → task dispatch → worker execution → result tracking → API retrieval. Test-suite management and service/JWT administration are additional capabilities. Source excerpts show application startup, persistence helpers, task-result synchronization, and shared runner schemas; some router and worker details are supported only by the SOURCE INDEX or README, so uncertain implementation links are omitted.

Main entry points: [`app/database.py`](https://github.com/xssandreissx/code-runner/blob/main/app/database.py) (Database access), [`app/routers/submission.py`](https://github.com/xssandreissx/code-runner/blob/main/app/routers/submission.py) (Submission API), [`app/services/result_awaiter.py`](https://github.com/xssandreissx/code-runner/blob/main/app/services/result_awaiter.py) (Result awaiter), [`app/core/database.py`](https://github.com/xssandreissx/code-runner/blob/main/app/core/database.py) (PostgreSQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_submission_api["Submission API<br/>[submission.py]"]
  node_suite_api["Test suite API"]
  node_access_control["JWT access<br/>[deps.py]"]
  node_response_schema["Client responses<br/>[client_response.py]"]
end

subgraph group_data["Submission data"]
  node_submission_services["Submission services<br/>[submission.py]"]
  node_submission_processing["Submission processing"]
  node_submission_model["Submission model<br/>[submission.py]"]
  node_service_model["Service model<br/>[service.py]"]
  node_database_access["Database access<br/>[database.py]"]
  node_database[("PostgreSQL<br/>[database.py]")]
  node_result_awaiter["Result awaiter<br/>[result_awaiter.py]"]
end

subgraph group_execution["Judging execution"]
  node_runner_contract["Runner schemas<br/>[runner.py]"]
  node_celery_config["Celery configuration<br/>[celery_app.py]"]
  node_rabbitmq["RabbitMQ broker"]
  node_worker_task["Worker task<br/>[main.py]"]
  node_test_processing["Test processing<br/>[process_tests.py]"]
  node_sandbox_runner["Sandbox runner<br/>[runner.py]"]
  node_sandbox["nsjail sandbox"]
  node_redis[("Redis result backend")]
end

subgraph group_operations["Service administration"]
  node_cli["Management CLI<br/>[cli.py]"]
  node_service_commands["Service commands<br/>[service.py]"]
  node_problem_commands["Problem commands<br/>[problem.py]"]
  node_seed_problems["Demo problem data"]
end

node_external_service(("External service"))

node_external_service -->|"calls API"| node_fastapi
node_fastapi -->|"registers route"| node_submission_api
node_fastapi -->|"registers route"| node_suite_api
node_external_service -->|"manages suites"| node_suite_api
node_external_service -->|"submits code"| node_submission_api
node_submission_api -->|"uses authorization"| node_access_control
node_submission_api -->|"uses services"| node_submission_services
node_submission_api -->|"dispatches processing"| node_submission_processing
node_submission_api -->|"returns response"| node_response_schema
node_submission_services -->|"reads and writes"| node_database_access
node_submission_processing -->|"reads suite data"| node_database_access
node_submission_processing -->|"submits task"| node_celery_config
node_submission_processing -->|"builds task input"| node_runner_contract
node_database_access -->|"queries"| node_database
node_database_access -->|"operates on"| node_submission_model
node_database_access -->|"operates on"| node_service_model
node_database -->|"stores records"| node_database
node_celery_config -->|"uses broker"| node_rabbitmq
node_celery_config -->|"uses backend"| node_redis
node_worker_task -->|"dispatches task"| node_test_processing
node_test_processing -->|"uses input and output"| node_runner_contract
node_test_processing -->|"runs tests"| node_sandbox_runner
node_sandbox_runner -->|"executes isolated"| node_sandbox
node_fastapi -->|"starts listener"| node_result_awaiter
node_result_awaiter -->|"checks task results"| node_celery_config
node_result_awaiter -->|"loads submissions"| node_database_access
node_result_awaiter -->|"persists verdicts"| node_database
node_result_awaiter -->|"reads task status"| node_redis
node_external_service -->|"retrieves verdict"| node_submission_api
node_cli -->|"invokes commands"| node_service_commands
node_cli -->|"invokes commands"| node_problem_commands
node_problem_commands -->|"loads suite data"| node_database_access
node_problem_commands -.->|"loads demo data"| node_seed_problems
node_service_commands -->|"manages services"| node_database_access
node_service_commands -->|"opens session"| node_database

click node_fastapi "https://github.com/xssandreissx/code-runner/blob/main/app/main.py"
click node_submission_api "https://github.com/xssandreissx/code-runner/blob/main/app/routers/submission.py"
click node_suite_api "https://github.com/xssandreissx/code-runner/tree/main/app/routers"
click node_access_control "https://github.com/xssandreissx/code-runner/blob/main/app/core/deps.py"
click node_response_schema "https://github.com/xssandreissx/code-runner/blob/main/app/schemas/client_response.py"
click node_submission_services "https://github.com/xssandreissx/code-runner/blob/main/app/services/submission.py"
click node_submission_processing "https://github.com/xssandreissx/code-runner/blob/main/app/services/process_submission.py"
click node_submission_model "https://github.com/xssandreissx/code-runner/blob/main/app/models/submission.py"
click node_service_model "https://github.com/xssandreissx/code-runner/blob/main/app/models/service.py"
click node_database_access "https://github.com/xssandreissx/code-runner/blob/main/app/database.py"
click node_database "https://github.com/xssandreissx/code-runner/blob/main/app/core/database.py"
click node_runner_contract "https://github.com/xssandreissx/code-runner/blob/main/shared/schemas/runner.py"
click node_celery_config "https://github.com/xssandreissx/code-runner/blob/main/shared/celery_app.py"
click node_worker_task "https://github.com/xssandreissx/code-runner/blob/main/worker/main.py"
click node_test_processing "https://github.com/xssandreissx/code-runner/blob/main/worker/core/process_tests.py"
click node_sandbox_runner "https://github.com/xssandreissx/code-runner/blob/main/worker/core/runner.py"
click node_result_awaiter "https://github.com/xssandreissx/code-runner/blob/main/app/services/result_awaiter.py"
click node_cli "https://github.com/xssandreissx/code-runner/blob/main/app/cli.py"
click node_service_commands "https://github.com/xssandreissx/code-runner/blob/main/app/cli_commands/service.py"
click node_problem_commands "https://github.com/xssandreissx/code-runner/blob/main/app/cli_commands/problem.py"
click node_seed_problems "https://github.com/xssandreissx/code-runner/tree/main/seed_problems"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_fastapi,node_submission_api,node_suite_api,node_access_control,node_response_schema toneBlue
class node_submission_services,node_submission_processing,node_submission_model,node_service_model,node_database_access,node_database,node_result_awaiter toneAmber
class node_runner_contract,node_celery_config,node_rabbitmq,node_worker_task,node_test_processing,node_sandbox_runner,node_sandbox,node_redis toneMint
class node_cli,node_service_commands,node_problem_commands,node_seed_problems toneRose
class node_external_service toneIndigo
```

## Components

### API and access

- [FastAPI app](https://github.com/xssandreissx/code-runner/blob/main/app/main.py): `app/main.py`
- [Submission API](https://github.com/xssandreissx/code-runner/blob/main/app/routers/submission.py): `app/routers/submission.py`
- [Test suite API](https://github.com/xssandreissx/code-runner/tree/main/app/routers): `app/routers`
- [JWT access](https://github.com/xssandreissx/code-runner/blob/main/app/core/deps.py): `app/core/deps.py`
- [Client responses](https://github.com/xssandreissx/code-runner/blob/main/app/schemas/client_response.py): `app/schemas/client_response.py`

### Submission data

- [Submission services](https://github.com/xssandreissx/code-runner/blob/main/app/services/submission.py): `app/services/submission.py`
- [Submission processing](https://github.com/xssandreissx/code-runner/blob/main/app/services/process_submission.py): `app/services/process_submission.py`
- [Submission model](https://github.com/xssandreissx/code-runner/blob/main/app/models/submission.py): `app/models/submission.py`
- [Service model](https://github.com/xssandreissx/code-runner/blob/main/app/models/service.py): `app/models/service.py`
- [Database access](https://github.com/xssandreissx/code-runner/blob/main/app/database.py): `app/database.py`
- [PostgreSQL](https://github.com/xssandreissx/code-runner/blob/main/app/core/database.py): `app/core/database.py`
- [Result awaiter](https://github.com/xssandreissx/code-runner/blob/main/app/services/result_awaiter.py): `app/services/result_awaiter.py`

### Judging execution

- [Runner schemas](https://github.com/xssandreissx/code-runner/blob/main/shared/schemas/runner.py): `shared/schemas/runner.py`
- [Celery configuration](https://github.com/xssandreissx/code-runner/blob/main/shared/celery_app.py): `shared/celery_app.py`
- **RabbitMQ broker**
- [Worker task](https://github.com/xssandreissx/code-runner/blob/main/worker/main.py): `worker/main.py`
- [Test processing](https://github.com/xssandreissx/code-runner/blob/main/worker/core/process_tests.py): `worker/core/process_tests.py`
- [Sandbox runner](https://github.com/xssandreissx/code-runner/blob/main/worker/core/runner.py): `worker/core/runner.py`
- **nsjail sandbox**
- **Redis result backend**

### Service administration

- [Management CLI](https://github.com/xssandreissx/code-runner/blob/main/app/cli.py): `app/cli.py`
- [Service commands](https://github.com/xssandreissx/code-runner/blob/main/app/cli_commands/service.py): `app/cli_commands/service.py`
- [Problem commands](https://github.com/xssandreissx/code-runner/blob/main/app/cli_commands/problem.py): `app/cli_commands/problem.py`
- [Demo problem data](https://github.com/xssandreissx/code-runner/tree/main/seed_problems): `seed_problems`

### Other components

- **External service**

## Connections

- External service → FastAPI app: calls API (evidence: `README.md`)
- FastAPI app → Submission API: registers route (evidence: `app/main.py`)
- FastAPI app → Test suite API: registers route (evidence: `app/main.py`)
- External service → Test suite API: manages suites (evidence: `README.md`)
- External service → Submission API: submits code (evidence: `README.md`)
- Submission API → JWT access: uses authorization (evidence: `app/routers/submission.py`)
- Submission API → Submission services: uses services (evidence: `app/routers/submission.py`)
- Submission API → Submission processing: dispatches processing (evidence: `app/routers/submission.py`)
- Submission API → Client responses: returns response (evidence: `app/routers/submission.py`)
- Submission services → Database access: reads and writes (evidence: `app/services/submission.py`)
- Submission processing → Database access: reads suite data (evidence: `app/services/process_submission.py`)
- Submission processing → Celery configuration: submits task (evidence: `app/services/process_submission.py`)
- Submission processing → Runner schemas: builds task input (evidence: `app/services/process_submission.py`)
- Database access → PostgreSQL: queries (evidence: `app/database.py`)
- Database access → Submission model: operates on (evidence: `app/database.py`)
- Database access → Service model: operates on (evidence: `app/database.py`)
- PostgreSQL → PostgreSQL: stores records (evidence: `app/core/database.py`)
- Celery configuration → RabbitMQ broker: uses broker (evidence: `shared/celery_app.py`)
- Celery configuration → Redis result backend: uses backend (evidence: `shared/celery_app.py`)
- Worker task → Test processing: dispatches task (evidence: `worker/main.py`)
- Test processing → Runner schemas: uses input and output (evidence: `worker/core/process_tests.py`)
- Test processing → Sandbox runner: runs tests (evidence: `worker/core/process_tests.py`)
- Sandbox runner → nsjail sandbox: executes isolated (evidence: `README.md`)
- FastAPI app → Result awaiter: starts listener (evidence: `app/main.py`)
- Result awaiter → Celery configuration: checks task results (evidence: `app/services/result_awaiter.py`)
- Result awaiter → Database access: loads submissions (evidence: `app/services/result_awaiter.py`)
- Result awaiter → PostgreSQL: persists verdicts (evidence: `app/services/result_awaiter.py`)
- Result awaiter → Redis result backend: reads task status (evidence: `app/services/result_awaiter.py`)
- External service → Submission API: retrieves verdict (evidence: `README.md`)
- Management CLI → Service commands: invokes commands (evidence: `app/cli.py`)
- Management CLI → Problem commands: invokes commands (evidence: `app/cli.py`)
- Problem commands → Database access: loads suite data (evidence: `app/cli_commands/problem.py`)
- Problem commands → Demo problem data: loads demo data
- Service commands → Database access: manages services (evidence: `app/cli_commands/service.py`)
- Service commands → PostgreSQL: opens session (evidence: `app/cli_commands/service.py`)
