# omegaup/omegaup architecture

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

- Interactive diagram: https://gitdiagram.com/omegaup/omegaup
- Repository: https://github.com/omegaup/omegaup

## Overview

omegaUp is a web-based educational programming platform for learners and educators. A typical learner uses the browser to find a problem or enter a contest/course arena, submit code, and view grading results and scoreboards. The frontend communicates with the PHP API; controllers implement domain operations and use DAOs for persistent records. Contest, course, group, certificate, and editorial features are distinct product branches. The README identifies Quark as the external grader. Some subsystem links are based on documented responsibilities and the file tree; unsampled implementation details and uncertain wiring are omitted.

Main entry points: [`frontend/server/src/Controllers`](https://github.com/omegaup/omegaup/tree/main/frontend/server/src/Controllers) (API controllers), [`stuff/ai_editorial_worker/worker.py`](https://github.com/omegaup/omegaup/blob/main/stuff/ai_editorial_worker/worker.py) (Editorial worker), [`frontend/www/js/omegaup/arena`](https://github.com/omegaup/omegaup/tree/main/frontend/www/js/omegaup/arena) (Problem arena UI), [`frontend/www/js/omegaup/api.ts`](https://github.com/omegaup/omegaup/blob/main/frontend/www/js/omegaup/api.ts) (Frontend API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["omegaUp website"]
  node_arena_ui["Problem arena UI"]
  node_api_client["Frontend API client<br/>[api.ts]"]
end

subgraph group_domain["API domain"]
  node_api_entry["API entry point<br/>[ApiEntryPoint.php]"]
  node_controllers["API controllers"]
  node_identity["Identity and sessions<br/>[Identity.php]"]
  node_editorial_controller["AI editorial API<br/>[AiEditorial.php]"]
end

subgraph group_learning["Learning workflows"]
  node_problems["Problem catalog<br/>[Problem.php]"]
  node_contests["Contests<br/>[Contest.php]"]
  node_courses["Courses and assignments<br/>[Course.php]"]
  node_groups["Groups and scoreboards<br/>[Group.php]"]
  node_certificates["Certificates<br/>[Certificate.php]"]
end

subgraph group_execution["Code execution"]
  node_submissions["Submissions and runs<br/>[Submission.php]"]
  node_grader["Grader integration<br/>[Grader.php]"]
  node_quark{{"Quark grader"}}
end

subgraph group_persistence["State and integrations"]
  node_dao["Data access objects"]
  node_mysql[("MySQL database")]
  node_editorial_worker["Editorial worker<br/>[worker.py]"]
  node_redis["Redis queue"]
  node_openai{{"OpenAI service"}}
end

node_learner(("Learner / educator"))

node_learner -->|"uses"| node_web
node_web -->|"opens arena"| node_arena_ui
node_arena_ui -->|"requests data"| node_api_client
node_api_client -->|"calls API"| node_api_entry
node_api_entry -->|"dispatches"| node_controllers
node_controllers -->|"authenticates"| node_identity
node_controllers -->|"serves problems"| node_problems
node_controllers -->|"serves contests"| node_contests
node_controllers -->|"serves courses"| node_courses
node_controllers -->|"serves groups"| node_groups
node_controllers -->|"serves certificates"| node_certificates
node_arena_ui -->|"submits code"| node_submissions
node_submissions -->|"requests grading"| node_grader
node_grader -.->|"dispatches runs"| node_quark
node_controllers -->|"reads and writes"| node_dao
node_dao -->|"queries"| node_mysql
node_editorial_controller -.->|"queues jobs"| node_redis
node_editorial_worker -.->|"consumes jobs"| node_redis
node_editorial_worker -.->|"generates editorials"| node_openai
node_editorial_worker -.->|"publishes editorial"| node_api_client

click node_web "https://github.com/omegaup/omegaup/tree/main/frontend/www"
click node_arena_ui "https://github.com/omegaup/omegaup/tree/main/frontend/www/js/omegaup/arena"
click node_api_client "https://github.com/omegaup/omegaup/blob/main/frontend/www/js/omegaup/api.ts"
click node_api_entry "https://github.com/omegaup/omegaup/blob/main/frontend/www/api/ApiEntryPoint.php"
click node_controllers "https://github.com/omegaup/omegaup/tree/main/frontend/server/src/Controllers"
click node_identity "https://github.com/omegaup/omegaup/blob/main/frontend/server/src/Controllers/Identity.php"
click node_problems "https://github.com/omegaup/omegaup/blob/main/frontend/server/src/Controllers/Problem.php"
click node_contests "https://github.com/omegaup/omegaup/blob/main/frontend/server/src/Controllers/Contest.php"
click node_courses "https://github.com/omegaup/omegaup/blob/main/frontend/server/src/Controllers/Course.php"
click node_groups "https://github.com/omegaup/omegaup/blob/main/frontend/server/src/Controllers/Group.php"
click node_certificates "https://github.com/omegaup/omegaup/blob/main/frontend/server/src/Controllers/Certificate.php"
click node_submissions "https://github.com/omegaup/omegaup/blob/main/frontend/server/src/Controllers/Submission.php"
click node_grader "https://github.com/omegaup/omegaup/blob/main/frontend/server/src/Grader.php"
click node_dao "https://github.com/omegaup/omegaup/tree/main/frontend/server/src/DAO"
click node_mysql "https://github.com/omegaup/omegaup/blob/main/frontend/server/src/MySQLConnection.php"
click node_editorial_controller "https://github.com/omegaup/omegaup/blob/main/frontend/server/src/Controllers/AiEditorial.php"
click node_editorial_worker "https://github.com/omegaup/omegaup/blob/main/stuff/ai_editorial_worker/worker.py"

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_web,node_arena_ui,node_api_client toneBlue
class node_api_entry,node_controllers,node_identity,node_editorial_controller toneAmber
class node_problems,node_contests,node_courses,node_groups,node_certificates toneMint
class node_submissions,node_grader,node_quark toneRose
class node_dao,node_mysql,node_editorial_worker,node_redis,node_openai,node_learner toneIndigo
```

## Components

### Web client

- [omegaUp website](https://github.com/omegaup/omegaup/tree/main/frontend/www): `frontend/www`
- [Problem arena UI](https://github.com/omegaup/omegaup/tree/main/frontend/www/js/omegaup/arena): `frontend/www/js/omegaup/arena`
- [Frontend API client](https://github.com/omegaup/omegaup/blob/main/frontend/www/js/omegaup/api.ts): `frontend/www/js/omegaup/api.ts`

### API domain

- [API entry point](https://github.com/omegaup/omegaup/blob/main/frontend/www/api/ApiEntryPoint.php): `frontend/www/api/ApiEntryPoint.php`
- [API controllers](https://github.com/omegaup/omegaup/tree/main/frontend/server/src/Controllers): `frontend/server/src/Controllers`
- [Identity and sessions](https://github.com/omegaup/omegaup/blob/main/frontend/server/src/Controllers/Identity.php): `frontend/server/src/Controllers/Identity.php`
- [AI editorial API](https://github.com/omegaup/omegaup/blob/main/frontend/server/src/Controllers/AiEditorial.php): `frontend/server/src/Controllers/AiEditorial.php`

### Learning workflows

- [Problem catalog](https://github.com/omegaup/omegaup/blob/main/frontend/server/src/Controllers/Problem.php): `frontend/server/src/Controllers/Problem.php`
- [Contests](https://github.com/omegaup/omegaup/blob/main/frontend/server/src/Controllers/Contest.php): `frontend/server/src/Controllers/Contest.php`
- [Courses and assignments](https://github.com/omegaup/omegaup/blob/main/frontend/server/src/Controllers/Course.php): `frontend/server/src/Controllers/Course.php`
- [Groups and scoreboards](https://github.com/omegaup/omegaup/blob/main/frontend/server/src/Controllers/Group.php): `frontend/server/src/Controllers/Group.php`
- [Certificates](https://github.com/omegaup/omegaup/blob/main/frontend/server/src/Controllers/Certificate.php): `frontend/server/src/Controllers/Certificate.php`

### Code execution

- [Submissions and runs](https://github.com/omegaup/omegaup/blob/main/frontend/server/src/Controllers/Submission.php): `frontend/server/src/Controllers/Submission.php`
- [Grader integration](https://github.com/omegaup/omegaup/blob/main/frontend/server/src/Grader.php): `frontend/server/src/Grader.php`
- **Quark grader**

### State and integrations

- [Data access objects](https://github.com/omegaup/omegaup/tree/main/frontend/server/src/DAO): `frontend/server/src/DAO`
- [MySQL database](https://github.com/omegaup/omegaup/blob/main/frontend/server/src/MySQLConnection.php): `frontend/server/src/MySQLConnection.php`
- [Editorial worker](https://github.com/omegaup/omegaup/blob/main/stuff/ai_editorial_worker/worker.py): `stuff/ai_editorial_worker/worker.py`
- **Redis queue**
- **OpenAI service**

### Other components

- **Learner / educator**

## Connections

- Learner / educator → omegaUp website: uses
- omegaUp website → Problem arena UI: opens arena
- Problem arena UI → Frontend API client: requests data
- Frontend API client → API entry point: calls API
- API entry point → API controllers: dispatches
- API controllers → Identity and sessions: authenticates
- API controllers → Problem catalog: serves problems
- API controllers → Contests: serves contests
- API controllers → Courses and assignments: serves courses
- API controllers → Groups and scoreboards: serves groups
- API controllers → Certificates: serves certificates
- Problem arena UI → Submissions and runs: submits code
- Submissions and runs → Grader integration: requests grading
- Grader integration → Quark grader: dispatches runs
- API controllers → Data access objects: reads and writes
- Data access objects → MySQL database: queries
- AI editorial API → Redis queue: queues jobs
- Editorial worker → Redis queue: consumes jobs
- Editorial worker → OpenAI service: generates editorials
- Editorial worker → Frontend API client: publishes editorial