# megazordpobeda/datarush architecture

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

- Interactive diagram: https://gitdiagram.com/megazordpobeda/datarush
- Repository: https://github.com/megazordpobeda/datarush

## Overview

#### Purpose and entry points
DataRush is a containerized platform for data-analysis competitions: users authenticate, join competitions, submit task solutions, receive asynchronous checking results, and view reviews, achievements, and standings. Docker Compose is the deployment entry point: `compose.yaml`. Public routes are served through `infrastructure/nginx/nginx.conf`; primary interfaces are the React UI, Django API/admin, Grafana, and learning documentation.

#### Edge and client application
Nginx fronts the stack and routes the browser to the frontend and backend-facing services. The React/Vite/TypeScript SPA owns user-facing competition flows, including session task answering and submission state:
- `services/frontend/src/main.tsx`
- `services/frontend/src/App.tsx`
- `services/frontend/src/pages/CompetitionSession/index.tsx`

Its API boundary is centralized under `services/frontend/src/shared/api/`, with authentication/session data managed separately from page widgets.

#### Backend API and domain core
The backend is Django with Django Ninja REST endpoints. Django bootstraps ASGI/WSGI, settings, URL routing, and Celery:
- `services/backend/config/settings.py`
- `services/backend/config/urls.py`
- `services/backend/api/v1/router.py`

API resources map to domain apps rather than placing persistence logic in the frontend: competition, task, team, user, review, and achievement endpoints are under `services/backend/api/v1/`; corresponding models and lifecycle signals live under `services/backend/apps/`.

#### Competition lifecycle and persistence
PostgreSQL is the system of record for users, teams, competitions, tasks, submissions, reviews, and achievement state. Competition state changes and review/user signals express cross-domain lifecycle effects:
- `services/backend/apps/competition/models.py`
- `services/backend/apps/task/models.py`
- `services/backend/apps/review/models.py`

Django admin provides operational management and a competition leaderboard template. Database initialization/data generation is performed through backend scripts and management commands, rather than by the client.

#### Submission and asynchronous checking
A solution submitted from the competition-session UI reaches backend task APIs, is queued through Celery, then sent to the checker integration. Task worker orchestration and checker health boundary are located at:
- `services/backend/apps/task/tasks.py`
- `services/backend/config/celery.py`
- `services/backend/integrations/checker/healthcheck.py`

Redis is the Celery broker/result-supporting runtime, configured as infrastructure alongside PostgreSQL. This separates request handling from potentially slow or unsafe user-code execution.

#### Checker isolation boundary
The checker is an independent FastAPI service with an `/execute` endpoint. It runs user submissions in disposable Docker containers with fixed CPU, memory, dependency, and execution-time limits; it is the security boundary for arbitrary code:
- `services/checker/main.py`
- `services/checker/config.py`
- `services/checker/Dockerfile.checker`

The backend/checker contract is service-to-service and should remain independent of frontend types or UI workflow.

#### Operations, observability, and supporting services
Compose assembles backend, frontend, checker, PostgreSQL, Redis, and supporting services. MinIO provides object-storage infrastructure; documentation is a separate Docusaurus service. Prometheus gathers metrics, exporters expose Postgres/Redis/Celery metrics, and Grafana provisions dashboards:
- `compose.yaml`
- `infrastructure/prometheus/prometheus.yaml`
- `infrastructure/grafana/provisioning/dashboards/providers.yaml`

Operational ingress, monitoring, and admin tools are infrastructure concerns, not backend domain dependencies.

Main entry points: [`infrastructure/nginx/nginx.conf`](https://github.com/megazordpobeda/datarush/blob/master/infrastructure/nginx/nginx.conf) (Nginx ingress), [`services/backend/api/v1/router.py`](https://github.com/megazordpobeda/datarush/blob/master/services/backend/api/v1/router.py) (Django Ninja API), [`compose.yaml`](https://github.com/megazordpobeda/datarush/blob/master/compose.yaml) (Docker Compose), [`services/backend/config/celery.py`](https://github.com/megazordpobeda/datarush/blob/master/services/backend/config/celery.py) (Celery runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Edge & clients"]
  node_nginx{{"Nginx ingress<br/>reverse proxy<br/>[nginx.conf]"}}
  node_spa["React competition UI<br/>Vite SPA<br/>[index.tsx]"]
  node_frontend_api["Frontend API client<br/>API boundary"]
  node_docs["Learning documentation<br/>Docusaurus service"]
end

subgraph group_application["Application services"]
  node_django_api["Django Ninja API<br/>REST API<br/>[router.py]"]
  node_django_core["Django domain core<br/>domain apps<br/>[models.py]"]
  node_django_admin["Django admin<br/>operations UI<br/>[urls.py]"]
  node_task_orchestration["Task orchestration<br/>Celery tasks<br/>[tasks.py]"]
  node_checker{{"Isolated checker<br/>FastAPI executor<br/>[main.py]"}}
  node_checker_container["Checker sandbox image<br/>Docker image<br/>[Dockerfile.checker]"]
end

subgraph group_runtime["Async &amp; data runtime"]
  node_celery["Celery runtime<br/>worker runtime<br/>[celery.py]"]
  node_redis[("Redis<br/>broker/results")]
  node_postgres[("PostgreSQL<br/>system of record")]
  node_minio[("MinIO<br/>object storage")]
end

subgraph group_operations["Operations"]
  node_compose["Docker Compose<br/>deployment<br/>[compose.yaml]"]
  node_prometheus["Prometheus<br/>metrics collector<br/>[prometheus.yaml]"]
  node_exporters["Runtime exporters<br/>metrics exporters"]
  node_grafana["Grafana dashboards<br/>observability UI<br/>[providers.yaml]"]
end

node_compose -.->|"deploys"| node_nginx
node_compose -.->|"deploys"| node_django_api
node_compose -.->|"deploys"| node_spa
node_compose -.->|"deploys"| node_checker
node_nginx -->|"serves"| node_spa
node_nginx -->|"routes API/admin"| node_django_api
node_nginx -->|"routes"| node_grafana
node_nginx -->|"routes"| node_docs
node_spa -->|"uses"| node_frontend_api
node_frontend_api -->|"REST requests"| node_django_api
node_django_api -->|"invokes domain logic"| node_django_core
node_django_api -->|"queues submissions"| node_task_orchestration
node_django_core -->|"persists lifecycle state"| node_postgres
node_django_admin -->|"manages"| node_django_core
node_task_orchestration -->|"dispatches"| node_celery
node_celery -->|"uses broker/results"| node_redis
node_celery -->|"execute contract"| node_checker
node_checker -->|"launches sandbox"| node_checker_container
node_exporters -.->|"collects metrics"| node_postgres
node_exporters -.->|"collects metrics"| node_redis
node_exporters -.->|"collects metrics"| node_celery
node_prometheus -->|"scrapes"| node_exporters
node_grafana -->|"queries metrics"| node_prometheus

click node_compose "https://github.com/megazordpobeda/datarush/blob/master/compose.yaml"
click node_nginx "https://github.com/megazordpobeda/datarush/blob/master/infrastructure/nginx/nginx.conf"
click node_spa "https://github.com/megazordpobeda/datarush/blob/master/services/frontend/src/pages/CompetitionSession/index.tsx"
click node_django_api "https://github.com/megazordpobeda/datarush/blob/master/services/backend/api/v1/router.py"
click node_django_core "https://github.com/megazordpobeda/datarush/blob/master/services/backend/apps/competition/models.py"
click node_django_admin "https://github.com/megazordpobeda/datarush/blob/master/services/backend/config/urls.py"
click node_task_orchestration "https://github.com/megazordpobeda/datarush/blob/master/services/backend/apps/task/tasks.py"
click node_celery "https://github.com/megazordpobeda/datarush/blob/master/services/backend/config/celery.py"
click node_checker "https://github.com/megazordpobeda/datarush/blob/master/services/checker/main.py"
click node_checker_container "https://github.com/megazordpobeda/datarush/blob/master/services/checker/Dockerfile.checker"
click node_prometheus "https://github.com/megazordpobeda/datarush/blob/master/infrastructure/prometheus/prometheus.yaml"
click node_grafana "https://github.com/megazordpobeda/datarush/blob/master/infrastructure/grafana/provisioning/dashboards/providers.yaml"

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_nginx,node_spa,node_frontend_api,node_docs toneBlue
class node_django_api,node_django_core,node_django_admin,node_task_orchestration,node_checker,node_checker_container toneAmber
class node_celery,node_redis,node_postgres,node_minio toneMint
class node_compose,node_prometheus,node_exporters,node_grafana toneRose
```

## Components

### Edge & clients

- [Nginx ingress](https://github.com/megazordpobeda/datarush/blob/master/infrastructure/nginx/nginx.conf): reverse proxy · `infrastructure/nginx/nginx.conf`
- [React competition UI](https://github.com/megazordpobeda/datarush/blob/master/services/frontend/src/pages/CompetitionSession/index.tsx): Vite SPA · Owns session answering and submission state. · `services/frontend/src/pages/CompetitionSession/index.tsx`
- **Frontend API client**: API boundary
- **Learning documentation**: Docusaurus service

### Application services

- [Django Ninja API](https://github.com/megazordpobeda/datarush/blob/master/services/backend/api/v1/router.py): REST API · Routes domain resources for competitions, tasks, teams, users, reviews, and achievements. · `services/backend/api/v1/router.py`
- [Django domain core](https://github.com/megazordpobeda/datarush/blob/master/services/backend/apps/competition/models.py): domain apps · Models and signals implement competition lifecycle effects. · `services/backend/apps/competition/models.py`
- [Django admin](https://github.com/megazordpobeda/datarush/blob/master/services/backend/config/urls.py): operations UI · Provides operational management and leaderboard views. · `services/backend/config/urls.py`
- [Task orchestration](https://github.com/megazordpobeda/datarush/blob/master/services/backend/apps/task/tasks.py): Celery tasks · Dispatches submitted solutions for asynchronous checking. · `services/backend/apps/task/tasks.py`
- [Isolated checker](https://github.com/megazordpobeda/datarush/blob/master/services/checker/main.py): FastAPI executor · Executes untrusted submissions in disposable constrained containers. · `services/checker/main.py`
- [Checker sandbox image](https://github.com/megazordpobeda/datarush/blob/master/services/checker/Dockerfile.checker): Docker image · Defines execution dependencies and resource limits. · `services/checker/Dockerfile.checker`

### Async & data runtime

- [Celery runtime](https://github.com/megazordpobeda/datarush/blob/master/services/backend/config/celery.py): worker runtime · `services/backend/config/celery.py`
- **Redis**: broker/results · Celery broker and result-supporting runtime.
- **PostgreSQL**: system of record · Stores users, teams, competitions, tasks, submissions, reviews, and achievements.
- **MinIO**: object storage

### Operations

- [Docker Compose](https://github.com/megazordpobeda/datarush/blob/master/compose.yaml): deployment · Assembles the platform services. · `compose.yaml`
- [Prometheus](https://github.com/megazordpobeda/datarush/blob/master/infrastructure/prometheus/prometheus.yaml): metrics collector · `infrastructure/prometheus/prometheus.yaml`
- **Runtime exporters**: metrics exporters · Expose PostgreSQL, Redis, and Celery metrics.
- [Grafana dashboards](https://github.com/megazordpobeda/datarush/blob/master/infrastructure/grafana/provisioning/dashboards/providers.yaml): observability UI · `infrastructure/grafana/provisioning/dashboards/providers.yaml`

## Connections

- Docker Compose → Nginx ingress: deploys
- Docker Compose → Django Ninja API: deploys
- Docker Compose → React competition UI: deploys
- Docker Compose → Isolated checker: deploys
- Nginx ingress → React competition UI: serves
- Nginx ingress → Django Ninja API: routes API/admin
- Nginx ingress → Grafana dashboards: routes
- Nginx ingress → Learning documentation: routes
- React competition UI → Frontend API client: uses
- Frontend API client → Django Ninja API: REST requests
- Django Ninja API → Django domain core: invokes domain logic
- Django Ninja API → Task orchestration: queues submissions
- Django domain core → PostgreSQL: persists lifecycle state
- Django admin → Django domain core: manages
- Task orchestration → Celery runtime: dispatches
- Celery runtime → Redis: uses broker/results
- Celery runtime → Isolated checker: execute contract
- Isolated checker → Checker sandbox image: launches sandbox
- Runtime exporters → PostgreSQL: collects metrics
- Runtime exporters → Redis: collects metrics
- Runtime exporters → Celery runtime: collects metrics
- Prometheus → Runtime exporters: scrapes
- Grafana dashboards → Prometheus: queries metrics