# demotione/osu-coach architecture

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

- Interactive diagram: https://gitdiagram.com/demotione/osu-coach
- Repository: https://github.com/demotione/osu-coach

## Overview

osu! coach is a local osu!standard replay-analysis and training app, with a web UI and optional desktop shell. The main workflow is to scan or upload replays, select and analyse them, aggregate results into a player profile, then explore statistics, tips, progress, and practice or play-goal recommendations. The graph includes documented capability branches and sampled call relationships; several feature implementations were not sampled, so their internal links are omitted rather than inferred.

Main entry points: [`backend/src/osu_coach/domain/player/records.py`](https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/domain/player/records.py) (Profile records), [`backend/src/osu_coach/domain/player/build.py`](https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/domain/player/build.py) (Profile aggregation), [`backend/src/osu_coach/features/library/session.py`](https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/features/library/session.py) (Replay session), [`backend/src/osu_coach/features/library/routes.py`](https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/features/library/routes.py) (Replay API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App entry"]
  node_webapp["Web app<br/>[server.py]"]
  node_workspace[("Workspace state<br/>[workspace.py]")]
end

subgraph group_replay["Replay analysis"]
  node_replay_api["Replay API<br/>[routes.py]"]
  node_replay_session["Replay session<br/>[session.py]"]
  node_replay_services["Replay services<br/>[service.py]"]
  node_replay_models["Replay models<br/>[models.py]"]
end

subgraph group_profile["Player model"]
  node_player_profile["Profile aggregation<br/>[build.py]"]
  node_summary["Play summaries<br/>[summary.py]"]
  node_records["Profile records<br/>[records.py]"]
  node_comfort_engine["Comfort ratings<br/>[engine.py]"]
  node_irt_engine["Star-scale ratings<br/>[engine.py]"]
end

subgraph group_features["Coaching features"]
  node_dashboard["Statistics dashboard<br/>[service.py]"]
  node_tips["Tips and setup<br/>[engine.py]"]
  node_maps["Skill playlists<br/>[service.py]"]
  node_play_goals["Play goals<br/>[service.py]"]
  node_progress["Progress tracking<br/>[service.py]"]
end

subgraph group_client["User interface"]
  node_frontend["Web interface<br/>[App.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
end

node_player(("Player"))
node_beatmaps["Beatmap downloads"]
node_osu_game["osu! game"]

node_player -.->|"uses"| node_frontend
node_frontend -.->|"requests"| node_api_client
node_api_client -.->|"calls API"| node_webapp
node_webapp -.->|"provides state"| node_workspace
node_player -->|"adds replays"| node_replay_api
node_replay_api -->|"delegates to"| node_replay_services
node_replay_api -->|"starts jobs"| node_replay_session
node_replay_session -.->|"updates"| node_workspace
node_replay_session -.->|"analyses"| node_replay_models
node_replay_session -.->|"builds profile"| node_player_profile
node_player_profile -->|"summarizes plays"| node_summary
node_player_profile -.->|"produces"| node_records
node_comfort_engine -->|"rates skills"| node_records
node_irt_engine -->|"rates skills"| node_records
node_player_profile -.->|"selects engine"| node_comfort_engine
node_player_profile -.->|"selects engine"| node_irt_engine
node_dashboard -.->|"reads profile"| node_workspace
node_tips -->|"uses profile data"| node_records
node_maps -.->|"uses skill ratings"| node_records
node_play_goals -.->|"uses play evidence"| node_records
node_progress -.->|"reads progress"| node_workspace
node_maps -.->|"downloads maps"| node_beatmaps
node_play_goals -.->|"exports training"| node_osu_game
node_frontend -.->|"scans and analyses"| node_replay_api

click node_webapp "https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/app/server.py"
click node_workspace "https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/app/workspace.py"
click node_replay_api "https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/features/library/routes.py"
click node_replay_session "https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/features/library/session.py"
click node_replay_services "https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/features/library/service.py"
click node_replay_models "https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/domain/analysis/models.py"
click node_player_profile "https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/domain/player/build.py"
click node_summary "https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/domain/player/summary.py"
click node_records "https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/domain/player/records.py"
click node_comfort_engine "https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/domain/player/engines/comfort/engine.py"
click node_irt_engine "https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/domain/player/engines/irt/engine.py"
click node_dashboard "https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/features/dashboard/service.py"
click node_tips "https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/features/tips/rules/engine.py"
click node_maps "https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/features/maps/service.py"
click node_play_goals "https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/features/play_goals/service.py"
click node_progress "https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/features/progress/service.py"
click node_frontend "https://github.com/demotione/osu-coach/blob/main/frontend/src/app/App.tsx"
click node_api_client "https://github.com/demotione/osu-coach/blob/main/frontend/src/api/client.ts"

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_webapp,node_workspace toneBlue
class node_replay_api,node_replay_session,node_replay_services,node_replay_models toneAmber
class node_player_profile,node_summary,node_records,node_comfort_engine,node_irt_engine toneMint
class node_dashboard,node_tips,node_maps,node_play_goals,node_progress toneRose
class node_frontend,node_api_client,node_player,node_beatmaps,node_osu_game toneIndigo
```

## Components

### App entry

- [Web app](https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/app/server.py): `backend/src/osu_coach/app/server.py`
- [Workspace state](https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/app/workspace.py): `backend/src/osu_coach/app/workspace.py`

### Replay analysis

- [Replay API](https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/features/library/routes.py): `backend/src/osu_coach/features/library/routes.py`
- [Replay session](https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/features/library/session.py): `backend/src/osu_coach/features/library/session.py`
- [Replay services](https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/features/library/service.py): `backend/src/osu_coach/features/library/service.py`
- [Replay models](https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/domain/analysis/models.py): `backend/src/osu_coach/domain/analysis/models.py`

### Player model

- [Profile aggregation](https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/domain/player/build.py): `backend/src/osu_coach/domain/player/build.py`
- [Play summaries](https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/domain/player/summary.py): `backend/src/osu_coach/domain/player/summary.py`
- [Profile records](https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/domain/player/records.py): `backend/src/osu_coach/domain/player/records.py`
- [Comfort ratings](https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/domain/player/engines/comfort/engine.py): `backend/src/osu_coach/domain/player/engines/comfort/engine.py`
- [Star-scale ratings](https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/domain/player/engines/irt/engine.py): `backend/src/osu_coach/domain/player/engines/irt/engine.py`

### Coaching features

- [Statistics dashboard](https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/features/dashboard/service.py): `backend/src/osu_coach/features/dashboard/service.py`
- [Tips and setup](https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/features/tips/rules/engine.py): `backend/src/osu_coach/features/tips/rules/engine.py`
- [Skill playlists](https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/features/maps/service.py): `backend/src/osu_coach/features/maps/service.py`
- [Play goals](https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/features/play_goals/service.py): `backend/src/osu_coach/features/play_goals/service.py`
- [Progress tracking](https://github.com/demotione/osu-coach/blob/main/backend/src/osu_coach/features/progress/service.py): `backend/src/osu_coach/features/progress/service.py`

### User interface

- [Web interface](https://github.com/demotione/osu-coach/blob/main/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [API client](https://github.com/demotione/osu-coach/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Other components

- **Player**
- **Beatmap downloads**
- **osu! game**

## Connections

- Player → Web interface: uses
- Web interface → API client: requests
- API client → Web app: calls API
- Web app → Workspace state: provides state
- Player → Replay API: adds replays (evidence: `backend/src/osu_coach/features/library/routes.py`)
- Replay API → Replay services: delegates to (evidence: `backend/src/osu_coach/features/library/routes.py`)
- Replay API → Replay session: starts jobs (evidence: `backend/src/osu_coach/features/library/routes.py`)
- Replay session → Workspace state: updates
- Replay session → Replay models: analyses
- Replay session → Profile aggregation: builds profile
- Profile aggregation → Play summaries: summarizes plays (evidence: `backend/src/osu_coach/domain/player/__init__.py`)
- Profile aggregation → Profile records: produces
- Comfort ratings → Profile records: rates skills (evidence: `backend/src/osu_coach/domain/player/engines/comfort/engine.py`)
- Star-scale ratings → Profile records: rates skills (evidence: `backend/src/osu_coach/domain/player/engines/irt/engine.py`)
- Profile aggregation → Comfort ratings: selects engine
- Profile aggregation → Star-scale ratings: selects engine
- Statistics dashboard → Workspace state: reads profile (evidence: `backend/src/osu_coach/features/dashboard/service.py`)
- Tips and setup → Profile records: uses profile data (evidence: `backend/src/osu_coach/features/tips/rules/engine.py`)
- Skill playlists → Profile records: uses skill ratings
- Play goals → Profile records: uses play evidence
- Progress tracking → Workspace state: reads progress
- Skill playlists → Beatmap downloads: downloads maps
- Play goals → osu! game: exports training
- Web interface → Replay API: scans and analyses
