# azaken1248/osurenderapi architecture

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

- Interactive diagram: https://gitdiagram.com/azaken1248/osurenderapi
- Repository: https://github.com/azaken1248/osurenderapi

## Overview

OsuRender accepts osu! replay submissions, validates and stores them, records a render job plus an outbox event, then dispatches work for rendering and exposes status, artifacts, and replay analytics. The worker prepares replay metadata and delegates video generation to the render pipeline, which uses cloud or local GPU execution and object storage. The README also identifies skins, legacy endpoints, and Modal as product capabilities. Dispatcher and several route/worker details are represented from the SOURCE INDEX; their internal behavior was not fully excerpted.

Main entry points: [`src/api/app.py`](https://github.com/azaken1248/osurenderapi/blob/main/src/api/app.py) (FastAPI gateway), [`src/workers/render_worker.py`](https://github.com/azaken1248/osurenderapi/blob/main/src/workers/render_worker.py) (Render worker), [`src/db/models.py`](https://github.com/azaken1248/osurenderapi/blob/main/src/db/models.py) (Jobs and outbox), [`src/api/routes/render.py`](https://github.com/azaken1248/osurenderapi/blob/main/src/api/routes/render.py) (Render submission)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_gateway["FastAPI gateway<br/>[app.py]"]
  node_submit["Render submission<br/>[render.py]"]
  node_job_api["Job status and analytics<br/>[jobs.py]"]
  node_legacy["Legacy endpoints<br/>[legacy.py]"]
  node_skins["Skin management<br/>[skins.py]"]
  node_artifacts["Artifact access<br/>[artifacts.py]"]
  node_player["Web replay player<br/>[view.py]"]
end

subgraph group_jobs["Job orchestration"]
  node_dispatcher["Outbox dispatcher<br/>[dispatcher.py]"]
  node_celery["Celery queue"]
end

subgraph group_rendering["Render execution"]
  node_worker["Render worker<br/>[render_worker.py]"]
  node_pipeline["Replay render pipeline<br/>[render_pipeline.py]"]
  node_modal["Modal GPU execution<br/>[modal_deploy.py]"]
end

subgraph group_platform["Data and operations"]
  node_jobs_db[("Jobs and outbox<br/>[models.py]")]
  node_storage_client["Storage client<br/>[storage.py]"]
  node_metrics["Prometheus metrics<br/>[metrics.py]"]
  node_config["Service configuration<br/>[config.py]"]
end

node_client(("API client"))
node_object_store[("Object storage")]
node_danser["Danser-Go"]
node_osu_api["osu! API"]

node_client -->|"sends requests"| node_gateway
node_gateway -->|"routes requests"| node_submit
node_gateway -->|"routes requests"| node_job_api
node_gateway -->|"routes requests"| node_legacy
node_gateway -->|"routes requests"| node_skins
node_gateway -->|"routes requests"| node_artifacts
node_gateway -->|"routes requests"| node_player
node_submit -->|"uploads replay"| node_storage_client
node_submit -->|"stores job and event"| node_jobs_db
node_job_api -->|"reads job state"| node_jobs_db
node_legacy -->|"reads job data"| node_jobs_db
node_player -->|"reads job data"| node_jobs_db
node_skins -->|"manages skin objects"| node_storage_client
node_artifacts -->|"reads stored artifacts"| node_storage_client
node_storage_client -->|"stores objects"| node_object_store
node_dispatcher -->|"dispatches render task"| node_worker
node_dispatcher -.->|"queues tasks"| node_celery
node_worker -->|"updates job state"| node_jobs_db
node_worker -->|"fetches score data"| node_osu_api
node_worker -->|"executes render pipeline"| node_pipeline
node_pipeline -->|"downloads and uploads"| node_object_store
node_pipeline -->|"runs renderer"| node_danser
node_worker -.->|"uses GPU execution"| node_modal
node_gateway -->|"publishes metrics"| node_metrics
node_submit -->|"counts submissions"| node_metrics
node_job_api -->|"counts analytics requests"| node_metrics
node_gateway -->|"loads settings"| node_config

click node_gateway "https://github.com/azaken1248/osurenderapi/blob/main/src/api/app.py"
click node_submit "https://github.com/azaken1248/osurenderapi/blob/main/src/api/routes/render.py"
click node_job_api "https://github.com/azaken1248/osurenderapi/blob/main/src/api/routes/jobs.py"
click node_legacy "https://github.com/azaken1248/osurenderapi/blob/main/src/api/routes/legacy.py"
click node_skins "https://github.com/azaken1248/osurenderapi/blob/main/src/api/routes/skins.py"
click node_artifacts "https://github.com/azaken1248/osurenderapi/blob/main/src/api/routes/artifacts.py"
click node_player "https://github.com/azaken1248/osurenderapi/blob/main/src/api/routes/view.py"
click node_jobs_db "https://github.com/azaken1248/osurenderapi/blob/main/src/db/models.py"
click node_storage_client "https://github.com/azaken1248/osurenderapi/blob/main/src/core/storage.py"
click node_dispatcher "https://github.com/azaken1248/osurenderapi/blob/main/src/workers/dispatcher.py"
click node_worker "https://github.com/azaken1248/osurenderapi/blob/main/src/workers/render_worker.py"
click node_pipeline "https://github.com/azaken1248/osurenderapi/blob/main/src/core/render_pipeline.py"
click node_modal "https://github.com/azaken1248/osurenderapi/blob/main/src/modal_deploy.py"
click node_metrics "https://github.com/azaken1248/osurenderapi/blob/main/src/core/metrics.py"
click node_config "https://github.com/azaken1248/osurenderapi/blob/main/src/core/config.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_gateway,node_submit,node_job_api,node_legacy,node_skins,node_artifacts,node_player,node_client toneBlue
class node_dispatcher,node_celery,node_object_store toneAmber
class node_worker,node_pipeline,node_modal,node_osu_api toneMint
class node_jobs_db,node_storage_client,node_metrics,node_config toneRose
class node_danser toneIndigo
```

## Components

### API and access

- [FastAPI gateway](https://github.com/azaken1248/osurenderapi/blob/main/src/api/app.py): `src/api/app.py`
- [Render submission](https://github.com/azaken1248/osurenderapi/blob/main/src/api/routes/render.py): `src/api/routes/render.py`
- [Job status and analytics](https://github.com/azaken1248/osurenderapi/blob/main/src/api/routes/jobs.py): `src/api/routes/jobs.py`
- [Legacy endpoints](https://github.com/azaken1248/osurenderapi/blob/main/src/api/routes/legacy.py): `src/api/routes/legacy.py`
- [Skin management](https://github.com/azaken1248/osurenderapi/blob/main/src/api/routes/skins.py): `src/api/routes/skins.py`
- [Artifact access](https://github.com/azaken1248/osurenderapi/blob/main/src/api/routes/artifacts.py): `src/api/routes/artifacts.py`
- [Web replay player](https://github.com/azaken1248/osurenderapi/blob/main/src/api/routes/view.py): `src/api/routes/view.py`

### Job orchestration

- [Outbox dispatcher](https://github.com/azaken1248/osurenderapi/blob/main/src/workers/dispatcher.py): `src/workers/dispatcher.py`
- **Celery queue**

### Render execution

- [Render worker](https://github.com/azaken1248/osurenderapi/blob/main/src/workers/render_worker.py): `src/workers/render_worker.py`
- [Replay render pipeline](https://github.com/azaken1248/osurenderapi/blob/main/src/core/render_pipeline.py): `src/core/render_pipeline.py`
- [Modal GPU execution](https://github.com/azaken1248/osurenderapi/blob/main/src/modal_deploy.py): `src/modal_deploy.py`

### Data and operations

- [Jobs and outbox](https://github.com/azaken1248/osurenderapi/blob/main/src/db/models.py): `src/db/models.py`
- [Storage client](https://github.com/azaken1248/osurenderapi/blob/main/src/core/storage.py): `src/core/storage.py`
- [Prometheus metrics](https://github.com/azaken1248/osurenderapi/blob/main/src/core/metrics.py): `src/core/metrics.py`
- [Service configuration](https://github.com/azaken1248/osurenderapi/blob/main/src/core/config.py): `src/core/config.py`

### Other components

- **API client**
- **Object storage**
- **Danser-Go**
- **osu! API**

## Connections

- API client → FastAPI gateway: sends requests (evidence: `src/api/app.py`)
- FastAPI gateway → Render submission: routes requests (evidence: `src/api/app.py`)
- FastAPI gateway → Job status and analytics: routes requests (evidence: `src/api/app.py`)
- FastAPI gateway → Legacy endpoints: routes requests (evidence: `src/api/app.py`)
- FastAPI gateway → Skin management: routes requests (evidence: `src/api/app.py`)
- FastAPI gateway → Artifact access: routes requests (evidence: `src/api/app.py`)
- FastAPI gateway → Web replay player: routes requests (evidence: `src/api/app.py`)
- Render submission → Storage client: uploads replay (evidence: `src/api/routes/render.py`)
- Render submission → Jobs and outbox: stores job and event (evidence: `src/api/routes/render.py`)
- Job status and analytics → Jobs and outbox: reads job state (evidence: `src/api/routes/jobs.py`)
- Legacy endpoints → Jobs and outbox: reads job data (evidence: `src/api/routes/legacy.py`)
- Web replay player → Jobs and outbox: reads job data (evidence: `src/api/routes/view.py`)
- Skin management → Storage client: manages skin objects (evidence: `src/api/routes/skins.py`)
- Artifact access → Storage client: reads stored artifacts (evidence: `src/api/routes/artifacts.py`)
- Storage client → Object storage: stores objects (evidence: `src/core/storage.py`)
- Outbox dispatcher → Render worker: dispatches render task (evidence: `src/workers/dispatcher.py`)
- Outbox dispatcher → Celery queue: queues tasks
- Render worker → Jobs and outbox: updates job state (evidence: `src/workers/render_worker.py`)
- Render worker → osu! API: fetches score data (evidence: `src/workers/render_worker.py`)
- Render worker → Replay render pipeline: executes render pipeline (evidence: `src/workers/render_worker.py`)
- Replay render pipeline → Object storage: downloads and uploads (evidence: `src/core/render_pipeline.py`)
- Replay render pipeline → Danser-Go: runs renderer (evidence: `src/core/render_pipeline.py`)
- Render worker → Modal GPU execution: uses GPU execution
- FastAPI gateway → Prometheus metrics: publishes metrics (evidence: `src/api/app.py`)
- Render submission → Prometheus metrics: counts submissions (evidence: `src/api/routes/render.py`)
- Job status and analytics → Prometheus metrics: counts analytics requests (evidence: `src/api/routes/jobs.py`)
- FastAPI gateway → Service configuration: loads settings (evidence: `src/api/app.py`)
