# ptrchain/osu-echo architecture

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

- Interactive diagram: https://gitdiagram.com/ptrchain/osu-echo
- Repository: https://github.com/ptrchain/osu-echo

## Overview

osu-echo is a local osu! server: the game client connects to its Bancho-compatible server, submits scores and replays, and receives local profile, leaderboard, and bot responses. Score submission decodes replay data, stores plays, updates medals, and can notify Discord; PP and rank features also use online services. Separate web routes provide profiles and osu!direct-style beatmap access. The graph follows documented capabilities and indexed module references; several route and runtime details are unsampled, so uncertain dispatch links are omitted.

Main entry points: [`src/handlers/score_submit.rs`](https://github.com/ptrchain/osu-echo/blob/main/src/handlers/score_submit.rs) (Score submission), [`src/handlers/cho.rs`](https://github.com/ptrchain/osu-echo/blob/main/src/handlers/cho.rs) (Bancho protocol), [`src/handlers/banchobot.rs`](https://github.com/ptrchain/osu-echo/blob/main/src/handlers/banchobot.rs) (BanchoBot), [`src/db.rs`](https://github.com/ptrchain/osu-echo/blob/main/src/db.rs) (SQLite data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server runtime"]
  node_entry["Application startup<br/>[main.rs]"]
  node_server["HTTP server<br/>[mod.rs]"]
  node_router["Request routing<br/>[router.rs]"]
  node_cho["Bancho protocol<br/>[cho.rs]"]
  node_packets["Packet encoding<br/>[packets.rs]"]
end

subgraph group_scores["Scores and maps"]
  node_score_submit["Score submission<br/>[score_submit.rs]"]
  node_score_decode["Replay decoding<br/>[score_decode.rs]"]
  node_score_types["Score models<br/>[score.rs]"]
  node_beatmap["Beatmap models<br/>[beatmap.rs]"]
  node_pp_utils["PP and map utilities<br/>[utils.rs]"]
end

subgraph group_community["Profiles and bots"]
  node_chat_commands["Chat command dispatch<br/>[chat_commands.rs]"]
  node_banchobot["BanchoBot<br/>[banchobot.rs]"]
  node_tillerino["Tillerino<br/>[tillerino.rs]"]
  node_medals["Medal awards<br/>[medals.rs]"]
end

subgraph group_web["Web features"]
  node_api["API endpoints<br/>[api.rs]"]
  node_website["Profiles and leaderboards<br/>[website.rs]"]
  node_web_routes["Web endpoints<br/>[web.rs]"]
  node_avatar["Avatar handling<br/>[avatar.rs]"]
  node_webhook["Discord notifications<br/>[webhook.rs]"]
end

subgraph group_shared["Shared services"]
  node_database[("SQLite data<br/>[db.rs]")]
  node_state["Shared application state<br/>[state.rs]"]
  node_config["Configuration wizard<br/>[config.rs]"]
end

node_osu_client(("osu! client"))
node_discord(("Discord"))
node_osu_api(("osu! APIs"))
node_beatmap_mirror(("Catboy map mirror"))

node_osu_client -->|"connects to"| node_server
node_entry -->|"starts"| node_server
node_server -->|"configures"| node_router
node_router -.->|"routes requests"| node_cho
node_cho -->|"dispatches chat"| node_chat_commands
node_cho -->|"encodes responses"| node_packets
node_score_submit -->|"decodes replay"| node_score_decode
node_score_submit -->|"stores scores"| node_database
node_score_submit -->|"checks awards"| node_medals
node_score_submit -->|"notifies"| node_webhook
node_score_submit -->|"calculates PP"| node_pp_utils
node_score_decode -->|"builds score"| node_score_types
node_score_submit -->|"uses score"| node_score_types
node_score_submit -->|"uses map data"| node_beatmap
node_chat_commands -->|"dispatches commands"| node_banchobot
node_chat_commands -->|"dispatches commands"| node_tillerino
node_banchobot -->|"reads and writes"| node_database
node_banchobot -->|"delegates to"| node_tillerino
node_banchobot -->|"syncs medals"| node_medals
node_api -->|"reads and writes"| node_database
node_website -->|"reads and writes"| node_database
node_web_routes -->|"uses submission"| node_score_submit
node_web_routes -->|"uses decoder"| node_score_decode
node_webhook -.->|"posts plays"| node_discord
node_pp_utils -->|"fetches data"| node_osu_api
node_web_routes -.->|"downloads maps"| node_beatmap_mirror
node_score_submit -->|"uses shared state"| node_state
node_cho -->|"uses shared state"| node_state

click node_entry "https://github.com/ptrchain/osu-echo/blob/main/src/main.rs"
click node_server "https://github.com/ptrchain/osu-echo/blob/main/src/server/mod.rs"
click node_router "https://github.com/ptrchain/osu-echo/blob/main/src/server/router.rs"
click node_cho "https://github.com/ptrchain/osu-echo/blob/main/src/handlers/cho.rs"
click node_packets "https://github.com/ptrchain/osu-echo/blob/main/src/packets.rs"
click node_score_submit "https://github.com/ptrchain/osu-echo/blob/main/src/handlers/score_submit.rs"
click node_score_decode "https://github.com/ptrchain/osu-echo/blob/main/src/handlers/score_decode.rs"
click node_score_types "https://github.com/ptrchain/osu-echo/blob/main/src/types/score.rs"
click node_beatmap "https://github.com/ptrchain/osu-echo/blob/main/src/types/beatmap.rs"
click node_pp_utils "https://github.com/ptrchain/osu-echo/blob/main/src/utils.rs"
click node_database "https://github.com/ptrchain/osu-echo/blob/main/src/db.rs"
click node_state "https://github.com/ptrchain/osu-echo/blob/main/src/state.rs"
click node_config "https://github.com/ptrchain/osu-echo/blob/main/src/types/config.rs"
click node_chat_commands "https://github.com/ptrchain/osu-echo/blob/main/src/handlers/chat_commands.rs"
click node_banchobot "https://github.com/ptrchain/osu-echo/blob/main/src/handlers/banchobot.rs"
click node_tillerino "https://github.com/ptrchain/osu-echo/blob/main/src/handlers/tillerino.rs"
click node_medals "https://github.com/ptrchain/osu-echo/blob/main/src/handlers/medals.rs"
click node_api "https://github.com/ptrchain/osu-echo/blob/main/src/handlers/api.rs"
click node_website "https://github.com/ptrchain/osu-echo/blob/main/src/handlers/website.rs"
click node_web_routes "https://github.com/ptrchain/osu-echo/blob/main/src/handlers/web.rs"
click node_avatar "https://github.com/ptrchain/osu-echo/blob/main/src/handlers/avatar.rs"
click node_webhook "https://github.com/ptrchain/osu-echo/blob/main/src/handlers/webhook.rs"

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_entry,node_server,node_router,node_cho,node_packets,node_osu_client toneBlue
class node_score_submit,node_score_decode,node_score_types,node_beatmap,node_pp_utils toneAmber
class node_chat_commands,node_banchobot,node_tillerino,node_medals,node_osu_api toneMint
class node_api,node_website,node_web_routes,node_avatar,node_webhook toneRose
class node_database,node_state,node_config,node_discord,node_beatmap_mirror toneIndigo
```

## Components

### Server runtime

- [Application startup](https://github.com/ptrchain/osu-echo/blob/main/src/main.rs): `src/main.rs`
- [HTTP server](https://github.com/ptrchain/osu-echo/blob/main/src/server/mod.rs): `src/server/mod.rs`
- [Request routing](https://github.com/ptrchain/osu-echo/blob/main/src/server/router.rs): `src/server/router.rs`
- [Bancho protocol](https://github.com/ptrchain/osu-echo/blob/main/src/handlers/cho.rs): `src/handlers/cho.rs`
- [Packet encoding](https://github.com/ptrchain/osu-echo/blob/main/src/packets.rs): `src/packets.rs`

### Scores and maps

- [Score submission](https://github.com/ptrchain/osu-echo/blob/main/src/handlers/score_submit.rs): `src/handlers/score_submit.rs`
- [Replay decoding](https://github.com/ptrchain/osu-echo/blob/main/src/handlers/score_decode.rs): `src/handlers/score_decode.rs`
- [Score models](https://github.com/ptrchain/osu-echo/blob/main/src/types/score.rs): `src/types/score.rs`
- [Beatmap models](https://github.com/ptrchain/osu-echo/blob/main/src/types/beatmap.rs): `src/types/beatmap.rs`
- [PP and map utilities](https://github.com/ptrchain/osu-echo/blob/main/src/utils.rs): `src/utils.rs`

### Profiles and bots

- [Chat command dispatch](https://github.com/ptrchain/osu-echo/blob/main/src/handlers/chat_commands.rs): `src/handlers/chat_commands.rs`
- [BanchoBot](https://github.com/ptrchain/osu-echo/blob/main/src/handlers/banchobot.rs): `src/handlers/banchobot.rs`
- [Tillerino](https://github.com/ptrchain/osu-echo/blob/main/src/handlers/tillerino.rs): `src/handlers/tillerino.rs`
- [Medal awards](https://github.com/ptrchain/osu-echo/blob/main/src/handlers/medals.rs): `src/handlers/medals.rs`

### Web features

- [API endpoints](https://github.com/ptrchain/osu-echo/blob/main/src/handlers/api.rs): `src/handlers/api.rs`
- [Profiles and leaderboards](https://github.com/ptrchain/osu-echo/blob/main/src/handlers/website.rs): `src/handlers/website.rs`
- [Web endpoints](https://github.com/ptrchain/osu-echo/blob/main/src/handlers/web.rs): `src/handlers/web.rs`
- [Avatar handling](https://github.com/ptrchain/osu-echo/blob/main/src/handlers/avatar.rs): `src/handlers/avatar.rs`
- [Discord notifications](https://github.com/ptrchain/osu-echo/blob/main/src/handlers/webhook.rs): `src/handlers/webhook.rs`

### Shared services

- [SQLite data](https://github.com/ptrchain/osu-echo/blob/main/src/db.rs): `src/db.rs`
- [Shared application state](https://github.com/ptrchain/osu-echo/blob/main/src/state.rs): `src/state.rs`
- [Configuration wizard](https://github.com/ptrchain/osu-echo/blob/main/src/types/config.rs): `src/types/config.rs`

### Other components

- **osu! client**
- **Discord**
- **osu! APIs**
- **Catboy map mirror**

## Connections

- osu! client → HTTP server: connects to (evidence: `README.md`)
- Application startup → HTTP server: starts (evidence: `src/main.rs`)
- HTTP server → Request routing: configures (evidence: `src/server/mod.rs`)
- Request routing → Bancho protocol: routes requests
- Bancho protocol → Chat command dispatch: dispatches chat (evidence: `src/handlers/cho.rs`)
- Bancho protocol → Packet encoding: encodes responses (evidence: `src/handlers/cho.rs`)
- Score submission → Replay decoding: decodes replay (evidence: `src/handlers/score_submit.rs`)
- Score submission → SQLite data: stores scores (evidence: `src/handlers/score_submit.rs`)
- Score submission → Medal awards: checks awards (evidence: `src/handlers/score_submit.rs`)
- Score submission → Discord notifications: notifies (evidence: `src/handlers/score_submit.rs`)
- Score submission → PP and map utilities: calculates PP (evidence: `src/handlers/score_submit.rs`)
- Replay decoding → Score models: builds score (evidence: `src/handlers/score_decode.rs`)
- Score submission → Score models: uses score (evidence: `src/handlers/score_submit.rs`)
- Score submission → Beatmap models: uses map data (evidence: `src/handlers/score_submit.rs`)
- Chat command dispatch → BanchoBot: dispatches commands (evidence: `src/handlers/chat_commands.rs`)
- Chat command dispatch → Tillerino: dispatches commands (evidence: `src/handlers/chat_commands.rs`)
- BanchoBot → SQLite data: reads and writes (evidence: `src/handlers/banchobot.rs`)
- BanchoBot → Tillerino: delegates to (evidence: `src/handlers/banchobot.rs`)
- BanchoBot → Medal awards: syncs medals (evidence: `src/handlers/banchobot.rs`)
- API endpoints → SQLite data: reads and writes (evidence: `src/handlers/api.rs`)
- Profiles and leaderboards → SQLite data: reads and writes (evidence: `src/handlers/website.rs`)
- Web endpoints → Score submission: uses submission (evidence: `src/handlers/web.rs`)
- Web endpoints → Replay decoding: uses decoder (evidence: `src/handlers/web.rs`)
- Discord notifications → Discord: posts plays (evidence: `README.md`)
- PP and map utilities → osu! APIs: fetches data (evidence: `src/utils.rs`)
- Web endpoints → Catboy map mirror: downloads maps (evidence: `README.md`)
- Score submission → Shared application state: uses shared state (evidence: `src/handlers/score_submit.rs`)
- Bancho protocol → Shared application state: uses shared state (evidence: `src/handlers/cho.rs`)
