# humanshuise/coderiot architecture

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

- Interactive diagram: https://gitdiagram.com/humanshuise/coderiot
- Repository: https://github.com/humanshuise/coderiot

## Overview

#### 1. Purpose and deployable entry points
CodeRiot is a competitive-programming platform for authenticated, head-to-head coding matches. It is split into three runtimes:
- Main FastAPI application: `backend/main.py`
- Isolated FastAPI judge service: `backend/judge_server.py`
- React/Vite SPA bootstrap: `frontend/vite-project/src/main.jsx`, `frontend/vite-project/src/App.jsx`

The SPA calls the backend REST API and matchmaking WebSocket; the backend persists platform data, coordinates matches, invokes the judge, and requests AI hints.

#### 2. Frontend application and session boundary
The React SPA owns routing, interactive pages, and browser-side match continuity. Match state is centralized in `frontend/vite-project/src/context/MatchContext.jsx`, allowing reconnect after refresh. Key user surfaces include matchmaking, editor/submission, leaderboard, profile, and admin review:
- `frontend/vite-project/src/pages/Matchmaking.jsx`
- `frontend/vite-project/src/components/CodeEditor.jsx`
- `frontend/vite-project/src/components/AdminDashboard.jsx`

Authentication flows are rendered client-side but rely on backend JWT/OAuth endpoints, including callback and password-reset pages.

#### 3. FastAPI API composition
`backend/main.py` is the API composition root. Route modules separate major product domains:
- Auth and identity: `backend/app/api/auth.py`, `backend/app/api/user.py`
- Live match lifecycle: `backend/app/api/match.py`
- Submission and judging orchestration: `backend/app/api/submission.py`
- Problem intake/review and discovery: `backend/app/api/new_problems.py`, `backend/app/api/stats.py`
- AI assistance: `backend/app/api/hint.py`

API schemas create the request/response boundary between clients and domain persistence: `backend/app/schemas/user.py`, `backend/app/schemas/problems.py`, `backend/app/schemas/submission.py`.

#### 4. Identity, persistence, and content governance
SQLAlchemy-backed PostgreSQL is the durable system of record, initialized/configured through `backend/app/db/database.py`. Core persisted entities cover users, coding problems, judged submissions, and rankings:
- `backend/app/models/user.py`
- `backend/app/models/problem.py`
- `backend/app/models/submission.py`
- `backend/app/models/leaderboard.py`

JWT security, password handling, and authorization are centralized in `backend/app/core/security.py`. User-contributed problems enter a review workflow rather than immediately becoming platform content; the admin dashboard is the UI boundary for that governance process.

#### 5. Real-time matchmaking and match control
The backend uses Redis as the ephemeral matchmaking queue and active-match state store. WebSocket connection management is isolated in `backend/app/core/websockets.py`, while protocol and match lifecycle behavior sit in `backend/app/api/match.py`.

Primary flow: an authenticated frontend opens the matchmaking WebSocket → backend queues or reconnects the player via Redis → paired users receive live match events → quit/solve outcomes update match state and notify the opponent. This is intentionally distinct from PostgreSQL’s durable user/problem/submission records.

#### 6. Submission-to-judge execution pipeline
The coding UI sends source code and problem context through the submission API, `backend/app/api/submission.py`. The main backend is the trust and orchestration boundary: it associates work with authenticated users and persisted problems, then delegates execution to the separately run judge service, `backend/judge_server.py`.

The judge executes Python and C++ submissions in Docker containers against test cases and returns outputs, errors, or timeouts. The backend records submission outcomes using `backend/app/models/submission.py` and can feed match completion/leaderboard behavior.

#### 7. External services and integrations
Material infrastructure: PostgreSQL for durable state, Redis for matchmaking state/queue, Docker for sandbox execution, and separate backend/judge FastAPI processes. External integrations include Google OAuth2, SMTP email for password resets, and Ollama for HintAI. Hint requests flow through `backend/app/api/hint.py`; email delivery and generated-code-related utilities are isolated under `backend/app/core/email_utils.py` and `backend/app/core/code_generators.py`.

Main entry points: [`frontend/vite-project/src/App.jsx`](https://github.com/humanshuise/coderiot/blob/main/frontend/vite-project/src/App.jsx) (App routes), [`backend/main.py`](https://github.com/humanshuise/coderiot/blob/main/backend/main.py) (Main FastAPI app), [`backend/app/api/auth.py`](https://github.com/humanshuise/coderiot/blob/main/backend/app/api/auth.py) (Product APIs), [`backend/app/api/match.py`](https://github.com/humanshuise/coderiot/blob/main/backend/app/api/match.py) (Match lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser SPA"]
  node_spa_bootstrap["React/Vite SPA<br/>SPA entry<br/>[main.jsx]"]
  node_app_shell["App routes<br/>React shell<br/>[App.jsx]"]
  node_match_context["Match continuity<br/>React context<br/>[MatchContext.jsx]"]
  node_matchmaking_ui["Matchmaking UI<br/>React page<br/>[Matchmaking.jsx]"]
  node_code_editor["Code editor<br/>React component<br/>[CodeEditor.jsx]"]
  node_admin_ui["Admin review UI<br/>React component<br/>[AdminDashboard.jsx]"]
end

subgraph group_backend["Main backend"]
  node_api_app["Main FastAPI app<br/>API entry<br/>[main.py]"]
  node_api_routes["Product APIs<br/>route modules<br/>[auth.py]"]
  node_match_protocol["Match lifecycle<br/>WebSocket API<br/>[match.py]"]
  node_submission_api["Submission orchestration<br/>REST API<br/>[submission.py]"]
  node_security["JWT authorization<br/>security layer<br/>[security.py]"]
  node_websocket_manager["WebSocket manager<br/>connection layer<br/>[websockets.py]"]
  node_database_layer[("SQLAlchemy persistence<br/>database layer<br/>[database.py]")]
  node_hint_api["HintAI API<br/>AI route<br/>[hint.py]"]
end

subgraph group_execution["Judge runtime"]
  node_judge_service["Judge FastAPI service<br/>judge entry<br/>[judge_server.py]"]
  node_docker{{"Docker sandbox<br/>execution runtime"}}
end

node_postgres[("PostgreSQL<br/>durable store")]
node_redis[("Redis<br/>ephemeral store")]
node_ollama{{"Ollama<br/>AI service"}}

node_spa_bootstrap -->|"boots"| node_app_shell
node_app_shell -->|"uses"| node_match_context
node_app_shell -->|"renders"| node_matchmaking_ui
node_app_shell -->|"renders"| node_code_editor
node_app_shell -->|"renders"| node_admin_ui
node_spa_bootstrap -->|"REST API"| node_api_app
node_matchmaking_ui -->|"authenticated WebSocket"| node_match_protocol
node_code_editor -->|"source submission"| node_submission_api
node_admin_ui -->|"problem review"| node_api_routes
node_api_app -->|"mounts"| node_api_routes
node_api_app -->|"mounts"| node_match_protocol
node_api_app -->|"mounts"| node_submission_api
node_api_routes -->|"authenticates"| node_security
node_api_routes -->|"reads and writes"| node_database_layer
node_match_protocol -->|"manages connections"| node_websocket_manager
node_match_protocol -->|"queue and live state"| node_redis
node_submission_api -->|"loads context and records outcomes"| node_database_layer
node_submission_api -->|"execution request"| node_judge_service
node_database_layer -->|"persists"| node_postgres
node_hint_api -->|"hint request"| node_ollama
node_api_app -->|"mounts"| node_hint_api
node_judge_service -->|"sandbox execution"| node_docker

click node_spa_bootstrap "https://github.com/humanshuise/coderiot/blob/main/frontend/vite-project/src/main.jsx"
click node_app_shell "https://github.com/humanshuise/coderiot/blob/main/frontend/vite-project/src/App.jsx"
click node_match_context "https://github.com/humanshuise/coderiot/blob/main/frontend/vite-project/src/context/MatchContext.jsx"
click node_matchmaking_ui "https://github.com/humanshuise/coderiot/blob/main/frontend/vite-project/src/pages/Matchmaking.jsx"
click node_code_editor "https://github.com/humanshuise/coderiot/blob/main/frontend/vite-project/src/components/CodeEditor.jsx"
click node_admin_ui "https://github.com/humanshuise/coderiot/blob/main/frontend/vite-project/src/components/AdminDashboard.jsx"
click node_api_app "https://github.com/humanshuise/coderiot/blob/main/backend/main.py"
click node_api_routes "https://github.com/humanshuise/coderiot/blob/main/backend/app/api/auth.py"
click node_match_protocol "https://github.com/humanshuise/coderiot/blob/main/backend/app/api/match.py"
click node_submission_api "https://github.com/humanshuise/coderiot/blob/main/backend/app/api/submission.py"
click node_security "https://github.com/humanshuise/coderiot/blob/main/backend/app/core/security.py"
click node_websocket_manager "https://github.com/humanshuise/coderiot/blob/main/backend/app/core/websockets.py"
click node_database_layer "https://github.com/humanshuise/coderiot/blob/main/backend/app/db/database.py"
click node_hint_api "https://github.com/humanshuise/coderiot/blob/main/backend/app/api/hint.py"
click node_judge_service "https://github.com/humanshuise/coderiot/blob/main/backend/judge_server.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_spa_bootstrap,node_app_shell,node_match_context,node_matchmaking_ui,node_code_editor,node_admin_ui toneBlue
class node_api_app,node_api_routes,node_match_protocol,node_submission_api,node_security,node_websocket_manager,node_database_layer,node_hint_api toneAmber
class node_judge_service,node_docker toneMint
class node_postgres,node_redis,node_ollama toneNeutral
```

## Components

### Browser SPA

- [React/Vite SPA](https://github.com/humanshuise/coderiot/blob/main/frontend/vite-project/src/main.jsx): SPA entry · `frontend/vite-project/src/main.jsx`
- [App routes](https://github.com/humanshuise/coderiot/blob/main/frontend/vite-project/src/App.jsx): React shell · `frontend/vite-project/src/App.jsx`
- [Match continuity](https://github.com/humanshuise/coderiot/blob/main/frontend/vite-project/src/context/MatchContext.jsx): React context · Preserves match state across browser reconnects. · `frontend/vite-project/src/context/MatchContext.jsx`
- [Matchmaking UI](https://github.com/humanshuise/coderiot/blob/main/frontend/vite-project/src/pages/Matchmaking.jsx): React page · `frontend/vite-project/src/pages/Matchmaking.jsx`
- [Code editor](https://github.com/humanshuise/coderiot/blob/main/frontend/vite-project/src/components/CodeEditor.jsx): React component · `frontend/vite-project/src/components/CodeEditor.jsx`
- [Admin review UI](https://github.com/humanshuise/coderiot/blob/main/frontend/vite-project/src/components/AdminDashboard.jsx): React component · `frontend/vite-project/src/components/AdminDashboard.jsx`

### Main backend

- [Main FastAPI app](https://github.com/humanshuise/coderiot/blob/main/backend/main.py): API entry · Composes authenticated REST and WebSocket endpoints. · `backend/main.py`
- [Product APIs](https://github.com/humanshuise/coderiot/blob/main/backend/app/api/auth.py): route modules · Auth, users, problems, stats, submissions, matches, and hints. · `backend/app/api/auth.py`
- [Match lifecycle](https://github.com/humanshuise/coderiot/blob/main/backend/app/api/match.py): WebSocket API · Queues, reconnects, pairs, and notifies players. · `backend/app/api/match.py`
- [Submission orchestration](https://github.com/humanshuise/coderiot/blob/main/backend/app/api/submission.py): REST API · Validates submissions and delegates execution. · `backend/app/api/submission.py`
- [JWT authorization](https://github.com/humanshuise/coderiot/blob/main/backend/app/core/security.py): security layer · `backend/app/core/security.py`
- [WebSocket manager](https://github.com/humanshuise/coderiot/blob/main/backend/app/core/websockets.py): connection layer · `backend/app/core/websockets.py`
- [SQLAlchemy persistence](https://github.com/humanshuise/coderiot/blob/main/backend/app/db/database.py): database layer · Maps users, problems, submissions, and rankings. · `backend/app/db/database.py`
- [HintAI API](https://github.com/humanshuise/coderiot/blob/main/backend/app/api/hint.py): AI route · `backend/app/api/hint.py`

### Judge runtime

- [Judge FastAPI service](https://github.com/humanshuise/coderiot/blob/main/backend/judge_server.py): judge entry · Separately deployed execution service. · `backend/judge_server.py`
- **Docker sandbox**: execution runtime · Runs Python and C++ against test cases.

### Other components

- **PostgreSQL**: durable store · System of record for platform data.
- **Redis**: ephemeral store · Matchmaking queue and active-match state.
- **Ollama**: AI service

## Connections

- React/Vite SPA → App routes: boots
- App routes → Match continuity: uses
- App routes → Matchmaking UI: renders
- App routes → Code editor: renders
- App routes → Admin review UI: renders
- React/Vite SPA → Main FastAPI app: REST API
- Matchmaking UI → Match lifecycle: authenticated WebSocket
- Code editor → Submission orchestration: source submission
- Admin review UI → Product APIs: problem review
- Main FastAPI app → Product APIs: mounts
- Main FastAPI app → Match lifecycle: mounts
- Main FastAPI app → Submission orchestration: mounts
- Product APIs → JWT authorization: authenticates
- Product APIs → SQLAlchemy persistence: reads and writes
- Match lifecycle → WebSocket manager: manages connections
- Match lifecycle → Redis: queue and live state
- Submission orchestration → SQLAlchemy persistence: loads context and records outcomes
- Submission orchestration → Judge FastAPI service: execution request
- SQLAlchemy persistence → PostgreSQL: persists
- HintAI API → Ollama: hint request
- Main FastAPI app → HintAI API: mounts
- Judge FastAPI service → Docker sandbox: sandbox execution