# turing-complete1509/algoarena architecture

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

- Interactive diagram: https://gitdiagram.com/turing-complete1509/algoarena
- Repository: https://github.com/turing-complete1509/algoarena

## Overview

AlgoArena is an online judge: users browse problems, authenticate, submit code or custom input, and receive execution results. The API persists submissions and queues evaluation; a worker runs code in Docker and records outcomes. The graph also preserves admin problem management and AI hints. Source excerpts show key API, controller, and worker behavior; some UI and infrastructure connections are documented in the README rather than verified from unsampled source.

Main entry points: [`frontend/src/services/api.js`](https://github.com/turing-complete1509/algoarena/blob/main/frontend/src/services/api.js) (API client), [`frontend/src/App.jsx`](https://github.com/turing-complete1509/algoarena/blob/main/frontend/src/App.jsx) (App routes), [`backend/src/server.js`](https://github.com/turing-complete1509/algoarena/blob/main/backend/src/server.js) (Express API), [`backend/src/controllers/submissionController.js`](https://github.com/turing-complete1509/algoarena/blob/main/backend/src/controllers/submissionController.js) (Submission handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["App routes<br/>[App.jsx]"]
  node_authui["Auth state<br/>[AuthContext.jsx]"]
  node_login["Login and register<br/>[Login.jsx]"]
  node_dashboard["Problem dashboard<br/>[Dashboard.jsx]"]
  node_workspace["Coding workspace<br/>[Workspace.jsx]"]
  node_adminui["Admin dashboard<br/>[AdminDashboard.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["API and domain"]
  node_server["Express API<br/>[server.js]"]
  node_auth["Authentication<br/>[authController.js]"]
  node_auth_guard["Token guard<br/>[authMiddleware.js]"]
  node_problems["Problem management"]
  node_submissions["Submission handling"]
  node_ai["AI hint endpoint<br/>[aiRoutes.js]"]
  node_user_model[("User records<br/>[User.js]")]
  node_problem_model[("Problem records<br/>[Problem.js]")]
  node_testcases[("Test case records<br/>[TestCase.js]")]
  node_submission_model[("Judge submissions<br/>[Submission.js]")]
  node_custom_model[("Custom submissions")]
end

subgraph group_execution["Code execution"]
  node_queue_config["Execution queue<br/>[queue.js]"]
  node_worker["Judge worker<br/>[worker.js]"]
end

subgraph group_integrations["External services"]
  node_redis[("Redis and BullMQ")]
  node_docker["Docker runtime"]
  node_gemini["Gemini AI"]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_workspace
node_app -->|"routes to"| node_login
node_app -->|"routes to"| node_adminui
node_app -->|"provides"| node_authui
node_login -->|"updates"| node_authui
node_login -->|"calls"| node_api_client
node_dashboard -->|"fetches problems"| node_api_client
node_workspace -->|"submits code"| node_api_client
node_adminui -->|"manages problems"| node_api_client
node_api_client -->|"sends API requests"| node_server
node_server -->|"mounts routes"| node_auth
node_server -->|"mounts routes"| node_problems
node_server -->|"mounts routes"| node_submissions
node_server -->|"mounts routes"| node_ai
node_auth -->|"reads and creates"| node_user_model
node_auth_guard -->|"loads user"| node_user_model
node_problems -->|"reads and writes"| node_problem_model
node_problems -->|"reads and writes"| node_testcases
node_submissions -->|"creates and reads"| node_submission_model
node_submissions -->|"creates and reads"| node_custom_model
node_submissions -->|"fetches cases"| node_testcases
node_submissions -->|"adds jobs"| node_queue_config
node_queue_config -.->|"uses broker"| node_redis
node_worker -->|"consumes jobs"| node_redis
node_worker -->|"updates status"| node_submission_model
node_worker -->|"updates status"| node_custom_model
node_worker -->|"runs code in"| node_docker
node_workspace -->|"requests hints"| node_api_client
node_api_client -->|"posts hint request"| node_ai
node_ai -->|"generates hints"| node_gemini

click node_app "https://github.com/turing-complete1509/algoarena/blob/main/frontend/src/App.jsx"
click node_authui "https://github.com/turing-complete1509/algoarena/blob/main/frontend/src/context/AuthContext.jsx"
click node_login "https://github.com/turing-complete1509/algoarena/blob/main/frontend/src/pages/Login.jsx"
click node_dashboard "https://github.com/turing-complete1509/algoarena/blob/main/frontend/src/pages/Dashboard.jsx"
click node_workspace "https://github.com/turing-complete1509/algoarena/blob/main/frontend/src/pages/Workspace.jsx"
click node_adminui "https://github.com/turing-complete1509/algoarena/blob/main/frontend/src/pages/AdminDashboard.jsx"
click node_api_client "https://github.com/turing-complete1509/algoarena/blob/main/frontend/src/services/api.js"
click node_server "https://github.com/turing-complete1509/algoarena/blob/main/backend/src/server.js"
click node_auth "https://github.com/turing-complete1509/algoarena/blob/main/backend/src/controllers/authController.js"
click node_auth_guard "https://github.com/turing-complete1509/algoarena/blob/main/backend/src/middleware/authMiddleware.js"
click node_problems "https://github.com/turing-complete1509/algoarena/blob/main/backend/src/controllers/problemController.js"
click node_submissions "https://github.com/turing-complete1509/algoarena/blob/main/backend/src/controllers/submissionController.js"
click node_ai "https://github.com/turing-complete1509/algoarena/blob/main/backend/src/routes/aiRoutes.js"
click node_user_model "https://github.com/turing-complete1509/algoarena/blob/main/backend/src/models/User.js"
click node_problem_model "https://github.com/turing-complete1509/algoarena/blob/main/backend/src/models/Problem.js"
click node_testcases "https://github.com/turing-complete1509/algoarena/blob/main/backend/src/models/TestCase.js"
click node_submission_model "https://github.com/turing-complete1509/algoarena/blob/main/backend/src/models/Submission.js"
click node_custom_model "https://github.com/turing-complete1509/algoarena/blob/main/backend/src/models/CustomSubmission.js"
click node_queue_config "https://github.com/turing-complete1509/algoarena/blob/main/backend/src/config/queue.js"
click node_worker "https://github.com/turing-complete1509/algoarena/blob/main/backend/worker.js"

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_app,node_authui,node_login,node_dashboard,node_workspace,node_adminui,node_api_client,node_user toneBlue
class node_server,node_auth,node_auth_guard,node_problems,node_submissions,node_ai,node_user_model,node_problem_model,node_testcases,node_submission_model,node_custom_model toneAmber
class node_queue_config,node_worker toneMint
class node_redis,node_docker,node_gemini toneRose
```

## Components

### Web client

- [App routes](https://github.com/turing-complete1509/algoarena/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Auth state](https://github.com/turing-complete1509/algoarena/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Login and register](https://github.com/turing-complete1509/algoarena/blob/main/frontend/src/pages/Login.jsx): `frontend/src/pages/Login.jsx`
- [Problem dashboard](https://github.com/turing-complete1509/algoarena/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Coding workspace](https://github.com/turing-complete1509/algoarena/blob/main/frontend/src/pages/Workspace.jsx): `frontend/src/pages/Workspace.jsx`
- [Admin dashboard](https://github.com/turing-complete1509/algoarena/blob/main/frontend/src/pages/AdminDashboard.jsx): `frontend/src/pages/AdminDashboard.jsx`
- [API client](https://github.com/turing-complete1509/algoarena/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### API and domain

- [Express API](https://github.com/turing-complete1509/algoarena/blob/main/backend/src/server.js): `backend/src/server.js`
- [Authentication](https://github.com/turing-complete1509/algoarena/blob/main/backend/src/controllers/authController.js): `backend/src/controllers/authController.js`
- [Token guard](https://github.com/turing-complete1509/algoarena/blob/main/backend/src/middleware/authMiddleware.js): `backend/src/middleware/authMiddleware.js`
- [Problem management](https://github.com/turing-complete1509/algoarena/blob/main/backend/src/controllers/problemController.js): `backend/src/controllers/problemController.js`
- [Submission handling](https://github.com/turing-complete1509/algoarena/blob/main/backend/src/controllers/submissionController.js): `backend/src/controllers/submissionController.js`
- [AI hint endpoint](https://github.com/turing-complete1509/algoarena/blob/main/backend/src/routes/aiRoutes.js): `backend/src/routes/aiRoutes.js`
- [User records](https://github.com/turing-complete1509/algoarena/blob/main/backend/src/models/User.js): `backend/src/models/User.js`
- [Problem records](https://github.com/turing-complete1509/algoarena/blob/main/backend/src/models/Problem.js): `backend/src/models/Problem.js`
- [Test case records](https://github.com/turing-complete1509/algoarena/blob/main/backend/src/models/TestCase.js): `backend/src/models/TestCase.js`
- [Judge submissions](https://github.com/turing-complete1509/algoarena/blob/main/backend/src/models/Submission.js): `backend/src/models/Submission.js`
- [Custom submissions](https://github.com/turing-complete1509/algoarena/blob/main/backend/src/models/CustomSubmission.js): `backend/src/models/CustomSubmission.js`

### Code execution

- [Execution queue](https://github.com/turing-complete1509/algoarena/blob/main/backend/src/config/queue.js): `backend/src/config/queue.js`
- [Judge worker](https://github.com/turing-complete1509/algoarena/blob/main/backend/worker.js): `backend/worker.js`

### External services

- **Redis and BullMQ**
- **Docker runtime**
- **Gemini AI**

### Other components

- **User**

## Connections

- User → App routes: uses (evidence: `README.md`)
- App routes → Problem dashboard: routes to (evidence: `frontend/src/App.jsx`)
- App routes → Coding workspace: routes to (evidence: `frontend/src/App.jsx`)
- App routes → Login and register: routes to (evidence: `frontend/src/App.jsx`)
- App routes → Admin dashboard: routes to (evidence: `frontend/src/App.jsx`)
- App routes → Auth state: provides (evidence: `frontend/src/App.jsx`)
- Login and register → Auth state: updates (evidence: `frontend/src/pages/Login.jsx`)
- Login and register → API client: calls (evidence: `frontend/src/pages/Login.jsx`)
- Problem dashboard → API client: fetches problems (evidence: `frontend/src/pages/Dashboard.jsx`)
- Coding workspace → API client: submits code (evidence: `frontend/src/pages/Workspace.jsx`)
- Admin dashboard → API client: manages problems (evidence: `frontend/src/pages/AdminDashboard.jsx`)
- API client → Express API: sends API requests (evidence: `README.md`)
- Express API → Authentication: mounts routes (evidence: `backend/src/server.js`)
- Express API → Problem management: mounts routes (evidence: `backend/src/server.js`)
- Express API → Submission handling: mounts routes (evidence: `backend/src/server.js`)
- Express API → AI hint endpoint: mounts routes (evidence: `backend/src/server.js`)
- Authentication → User records: reads and creates (evidence: `backend/src/controllers/authController.js`)
- Token guard → User records: loads user (evidence: `backend/src/middleware/authMiddleware.js`)
- Problem management → Problem records: reads and writes (evidence: `backend/src/controllers/problemController.js`)
- Problem management → Test case records: reads and writes (evidence: `backend/src/controllers/problemController.js`)
- Submission handling → Judge submissions: creates and reads (evidence: `backend/src/controllers/submissionController.js`)
- Submission handling → Custom submissions: creates and reads (evidence: `backend/src/controllers/submissionController.js`)
- Submission handling → Test case records: fetches cases (evidence: `backend/src/controllers/submissionController.js`)
- Submission handling → Execution queue: adds jobs (evidence: `backend/src/controllers/submissionController.js`)
- Execution queue → Redis and BullMQ: uses broker (evidence: `README.md`)
- Judge worker → Redis and BullMQ: consumes jobs (evidence: `README.md`)
- Judge worker → Judge submissions: updates status (evidence: `backend/worker.js`)
- Judge worker → Custom submissions: updates status (evidence: `backend/worker.js`)
- Judge worker → Docker runtime: runs code in (evidence: `backend/worker.js`)
- Coding workspace → API client: requests hints (evidence: `frontend/src/pages/Workspace.jsx`)
- API client → AI hint endpoint: posts hint request (evidence: `frontend/src/services/api.js`)
- AI hint endpoint → Gemini AI: generates hints (evidence: `backend/src/routes/aiRoutes.js`)