# qianqiuzy/harei-backend architecture

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

- Interactive diagram: https://gitdiagram.com/qianqiuzy/harei-backend
- Repository: https://github.com/qianqiuzy/harei-backend

## Overview

harei-backend is a FastAPI service for authentication, a message box, music catalog management, rankings and tags, downloads, and captain/gift features. Users call its API routes; those routes provide domain operations backed by MySQL, with Redis supporting token sessions. A separate optional Bilibili listener tracks live-room and captain activity and produces reports. The README documents these capabilities, but several route implementations were not sampled; their presence and startup registration are shown, while uncertain internal flows are omitted.

Main entry points: [`app/main.py`](https://github.com/qianqiuzy/harei-backend/blob/main/app/main.py) (FastAPI application), [`app/db/session.py`](https://github.com/qianqiuzy/harei-backend/blob/main/app/db/session.py) (MySQL sessions), [`app/deps/auth.py`](https://github.com/qianqiuzy/harei-backend/blob/main/app/deps/auth.py) (Auth dependencies), [`app/api/music_manage.py`](https://github.com/qianqiuzy/harei-backend/blob/main/app/api/music_manage.py) (Music management API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime infrastructure"]
  node_app["FastAPI application<br/>[main.py]"]
  node_settings["Settings<br/>[config.py]"]
  node_mysql[("MySQL sessions<br/>[session.py]")]
  node_redis[("Redis client<br/>[redis.py]")]
  node_authservice["Authentication service<br/>[auth_service.py]"]
  node_authdep["Auth dependencies<br/>[auth.py]"]
end

subgraph group_api["API domains"]
  node_authapi["Authentication API<br/>[auth.py]"]
  node_boxapi["Message box API<br/>[box.py]"]
  node_downloadapi["Download API<br/>[download.py]"]
  node_emojiapi["Emoji API<br/>[emoji.py]"]
  node_huangdouapi["Huangdou rankings API<br/>[huangdou.py]"]
  node_tagapi["Tag API<br/>[tag.py]"]
end

subgraph group_music["Music catalog"]
  node_musicapi["Music catalog API<br/>[music.py]"]
  node_musicmanage["Music management API<br/>[music_manage.py]"]
  node_musicextra["Music management extras"]
  node_musicimport["Music import API<br/>[music_import.py]"]
  node_musicdata[("Music models<br/>[music.py]")]
end

subgraph group_captain["Captain and live"]
  node_captainsapi["Captains API<br/>[captains.py]"]
  node_giftapi["Captain gifts API<br/>[captaingift.py]"]
  node_liveapi["Live status API<br/>[live.py]"]
  node_listener["Captain live listener"]
  node_giftarchive["Gift archive service"]
  node_captainreports["Captain reports<br/>[captain_reports.py]"]
end

subgraph group_blivedm["Bilibili client"]
  node_ws["WebSocket client<br/>[ws_base.py]"]
  node_handlers["Message handlers<br/>[handlers.py]"]
  node_webmodels["Web message models<br/>[web.py]"]
  node_openmodels["Open live models<br/>[open_live.py]"]
  node_giftv2["Gift V2 model<br/>[send_gift_v2.py]"]
end

node_users(("API clients"))

node_users -->|"send requests"| node_app
node_app -->|"registers route"| node_authapi
node_app -->|"registers route"| node_boxapi
node_app -->|"registers route"| node_downloadapi
node_app -->|"registers route"| node_emojiapi
node_app -->|"registers route"| node_huangdouapi
node_app -->|"registers route"| node_tagapi
node_app -->|"registers route"| node_musicapi
node_app -->|"registers route"| node_musicmanage
node_app -->|"registers route"| node_musicextra
node_app -->|"registers route"| node_musicimport
node_app -->|"registers route"| node_captainsapi
node_app -->|"registers route"| node_giftapi
node_app -->|"registers route"| node_liveapi
node_app -->|"starts listener"| node_listener
node_app -->|"runs migration"| node_giftarchive
node_authapi -->|"uses"| node_authservice
node_authapi -->|"uses"| node_authdep
node_authdep -->|"checks token"| node_authservice
node_authdep -->|"gets client"| node_redis
node_authservice -->|"stores tokens"| node_redis
node_authservice -->|"reads credentials"| node_settings
node_boxapi -->|"uses sessions"| node_mysql
node_boxapi -->|"uses auth"| node_authdep
node_downloadapi -->|"uses sessions"| node_mysql
node_downloadapi -->|"uses auth"| node_authdep
node_huangdouapi -->|"uses sessions"| node_mysql
node_musicapi -->|"uses sessions"| node_mysql
node_musicapi -->|"queries models"| node_musicdata
node_musicmanage -->|"reuses routes"| node_musicapi
node_musicmanage -->|"uses sessions"| node_mysql
node_musicmanage -->|"uses auth"| node_authdep
node_musicmanage -->|"uses models"| node_musicdata
node_musicextra -->|"reuses management"| node_musicmanage
node_musicextra -->|"uses sessions"| node_mysql
node_musicextra -->|"uses auth"| node_authdep
node_captainsapi -->|"uses sessions"| node_mysql
node_captainsapi -->|"uses auth"| node_authdep
node_captainsapi -->|"uses reports"| node_captainreports
node_giftapi -->|"uses sessions"| node_mysql
node_giftapi -->|"uses auth"| node_authdep
node_giftapi -->|"uses archive"| node_giftarchive
node_liveapi -->|"reads status"| node_listener
node_listener -->|"writes records"| node_mysql
node_listener -->|"uses reports"| node_captainreports
node_giftarchive -->|"uses sessions"| node_mysql
node_ws -->|"dispatches messages"| node_handlers
node_handlers -->|"receives commands"| node_ws

click node_app "https://github.com/qianqiuzy/harei-backend/blob/main/app/main.py"
click node_settings "https://github.com/qianqiuzy/harei-backend/blob/main/app/core/config.py"
click node_mysql "https://github.com/qianqiuzy/harei-backend/blob/main/app/db/session.py"
click node_redis "https://github.com/qianqiuzy/harei-backend/blob/main/app/core/redis.py"
click node_authservice "https://github.com/qianqiuzy/harei-backend/blob/main/app/services/auth_service.py"
click node_authdep "https://github.com/qianqiuzy/harei-backend/blob/main/app/deps/auth.py"
click node_authapi "https://github.com/qianqiuzy/harei-backend/blob/main/app/api/auth.py"
click node_boxapi "https://github.com/qianqiuzy/harei-backend/blob/main/app/api/box.py"
click node_downloadapi "https://github.com/qianqiuzy/harei-backend/blob/main/app/api/download.py"
click node_emojiapi "https://github.com/qianqiuzy/harei-backend/blob/main/app/api/emoji.py"
click node_huangdouapi "https://github.com/qianqiuzy/harei-backend/blob/main/app/api/huangdou.py"
click node_tagapi "https://github.com/qianqiuzy/harei-backend/blob/main/app/api/tag.py"
click node_musicapi "https://github.com/qianqiuzy/harei-backend/blob/main/app/api/music.py"
click node_musicmanage "https://github.com/qianqiuzy/harei-backend/blob/main/app/api/music_manage.py"
click node_musicextra "https://github.com/qianqiuzy/harei-backend/blob/main/app/api/music_manage_extra.py"
click node_musicimport "https://github.com/qianqiuzy/harei-backend/blob/main/app/api/music_import.py"
click node_musicdata "https://github.com/qianqiuzy/harei-backend/blob/main/app/models/music.py"
click node_captainsapi "https://github.com/qianqiuzy/harei-backend/blob/main/app/api/captains.py"
click node_giftapi "https://github.com/qianqiuzy/harei-backend/blob/main/app/api/captaingift.py"
click node_liveapi "https://github.com/qianqiuzy/harei-backend/blob/main/app/api/live.py"
click node_listener "https://github.com/qianqiuzy/harei-backend/blob/main/app/services/bili_captain_listener.py"
click node_giftarchive "https://github.com/qianqiuzy/harei-backend/blob/main/app/services/captain_gift_archive.py"
click node_captainreports "https://github.com/qianqiuzy/harei-backend/blob/main/app/services/captain_reports.py"
click node_ws "https://github.com/qianqiuzy/harei-backend/blob/main/blivedm/clients/ws_base.py"
click node_handlers "https://github.com/qianqiuzy/harei-backend/blob/main/blivedm/handlers.py"
click node_webmodels "https://github.com/qianqiuzy/harei-backend/blob/main/blivedm/models/web.py"
click node_openmodels "https://github.com/qianqiuzy/harei-backend/blob/main/blivedm/models/open_live.py"
click node_giftv2 "https://github.com/qianqiuzy/harei-backend/blob/main/blivedm/models/send_gift_v2.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_app,node_settings,node_mysql,node_redis,node_authservice,node_authdep,node_users toneBlue
class node_authapi,node_boxapi,node_downloadapi,node_emojiapi,node_huangdouapi,node_tagapi toneAmber
class node_musicapi,node_musicmanage,node_musicextra,node_musicimport,node_musicdata toneMint
class node_captainsapi,node_giftapi,node_liveapi,node_listener,node_giftarchive,node_captainreports toneRose
class node_ws,node_handlers,node_webmodels,node_openmodels,node_giftv2 toneIndigo
```

## Components

### Runtime infrastructure

- [FastAPI application](https://github.com/qianqiuzy/harei-backend/blob/main/app/main.py): `app/main.py`
- [Settings](https://github.com/qianqiuzy/harei-backend/blob/main/app/core/config.py): `app/core/config.py`
- [MySQL sessions](https://github.com/qianqiuzy/harei-backend/blob/main/app/db/session.py): `app/db/session.py`
- [Redis client](https://github.com/qianqiuzy/harei-backend/blob/main/app/core/redis.py): `app/core/redis.py`
- [Authentication service](https://github.com/qianqiuzy/harei-backend/blob/main/app/services/auth_service.py): `app/services/auth_service.py`
- [Auth dependencies](https://github.com/qianqiuzy/harei-backend/blob/main/app/deps/auth.py): `app/deps/auth.py`

### API domains

- [Authentication API](https://github.com/qianqiuzy/harei-backend/blob/main/app/api/auth.py): `app/api/auth.py`
- [Message box API](https://github.com/qianqiuzy/harei-backend/blob/main/app/api/box.py): `app/api/box.py`
- [Download API](https://github.com/qianqiuzy/harei-backend/blob/main/app/api/download.py): `app/api/download.py`
- [Emoji API](https://github.com/qianqiuzy/harei-backend/blob/main/app/api/emoji.py): `app/api/emoji.py`
- [Huangdou rankings API](https://github.com/qianqiuzy/harei-backend/blob/main/app/api/huangdou.py): `app/api/huangdou.py`
- [Tag API](https://github.com/qianqiuzy/harei-backend/blob/main/app/api/tag.py): `app/api/tag.py`

### Music catalog

- [Music catalog API](https://github.com/qianqiuzy/harei-backend/blob/main/app/api/music.py): `app/api/music.py`
- [Music management API](https://github.com/qianqiuzy/harei-backend/blob/main/app/api/music_manage.py): `app/api/music_manage.py`
- [Music management extras](https://github.com/qianqiuzy/harei-backend/blob/main/app/api/music_manage_extra.py): `app/api/music_manage_extra.py`
- [Music import API](https://github.com/qianqiuzy/harei-backend/blob/main/app/api/music_import.py): `app/api/music_import.py`
- [Music models](https://github.com/qianqiuzy/harei-backend/blob/main/app/models/music.py): `app/models/music.py`

### Captain and live

- [Captains API](https://github.com/qianqiuzy/harei-backend/blob/main/app/api/captains.py): `app/api/captains.py`
- [Captain gifts API](https://github.com/qianqiuzy/harei-backend/blob/main/app/api/captaingift.py): `app/api/captaingift.py`
- [Live status API](https://github.com/qianqiuzy/harei-backend/blob/main/app/api/live.py): `app/api/live.py`
- [Captain live listener](https://github.com/qianqiuzy/harei-backend/blob/main/app/services/bili_captain_listener.py): `app/services/bili_captain_listener.py`
- [Gift archive service](https://github.com/qianqiuzy/harei-backend/blob/main/app/services/captain_gift_archive.py): `app/services/captain_gift_archive.py`
- [Captain reports](https://github.com/qianqiuzy/harei-backend/blob/main/app/services/captain_reports.py): `app/services/captain_reports.py`

### Bilibili client

- [WebSocket client](https://github.com/qianqiuzy/harei-backend/blob/main/blivedm/clients/ws_base.py): `blivedm/clients/ws_base.py`
- [Message handlers](https://github.com/qianqiuzy/harei-backend/blob/main/blivedm/handlers.py): `blivedm/handlers.py`
- [Web message models](https://github.com/qianqiuzy/harei-backend/blob/main/blivedm/models/web.py): `blivedm/models/web.py`
- [Open live models](https://github.com/qianqiuzy/harei-backend/blob/main/blivedm/models/open_live.py): `blivedm/models/open_live.py`
- [Gift V2 model](https://github.com/qianqiuzy/harei-backend/blob/main/blivedm/models/send_gift_v2.py): `blivedm/models/send_gift_v2.py`

### Other components

- **API clients**

## Connections

- API clients → FastAPI application: send requests (evidence: `app/main.py`)
- FastAPI application → Authentication API: registers route (evidence: `app/main.py`)
- FastAPI application → Message box API: registers route (evidence: `app/main.py`)
- FastAPI application → Download API: registers route (evidence: `app/main.py`)
- FastAPI application → Emoji API: registers route (evidence: `app/main.py`)
- FastAPI application → Huangdou rankings API: registers route (evidence: `app/main.py`)
- FastAPI application → Tag API: registers route (evidence: `app/main.py`)
- FastAPI application → Music catalog API: registers route (evidence: `app/main.py`)
- FastAPI application → Music management API: registers route (evidence: `app/main.py`)
- FastAPI application → Music management extras: registers route (evidence: `app/main.py`)
- FastAPI application → Music import API: registers route (evidence: `app/main.py`)
- FastAPI application → Captains API: registers route (evidence: `app/main.py`)
- FastAPI application → Captain gifts API: registers route (evidence: `app/main.py`)
- FastAPI application → Live status API: registers route (evidence: `app/main.py`)
- FastAPI application → Captain live listener: starts listener (evidence: `app/main.py`)
- FastAPI application → Gift archive service: runs migration (evidence: `app/main.py`)
- Authentication API → Authentication service: uses (evidence: `app/api/auth.py`)
- Authentication API → Auth dependencies: uses (evidence: `app/api/auth.py`)
- Auth dependencies → Authentication service: checks token (evidence: `app/deps/auth.py`)
- Auth dependencies → Redis client: gets client (evidence: `app/deps/auth.py`)
- Authentication service → Redis client: stores tokens (evidence: `app/services/auth_service.py`)
- Authentication service → Settings: reads credentials (evidence: `app/services/auth_service.py`)
- Message box API → MySQL sessions: uses sessions (evidence: `app/api/box.py`)
- Message box API → Auth dependencies: uses auth (evidence: `app/api/box.py`)
- Download API → MySQL sessions: uses sessions (evidence: `app/api/download.py`)
- Download API → Auth dependencies: uses auth (evidence: `app/api/download.py`)
- Huangdou rankings API → MySQL sessions: uses sessions (evidence: `app/api/huangdou.py`)
- Music catalog API → MySQL sessions: uses sessions (evidence: `app/api/music.py`)
- Music catalog API → Music models: queries models (evidence: `app/api/music.py`)
- Music management API → Music catalog API: reuses routes (evidence: `app/api/music_manage.py`)
- Music management API → MySQL sessions: uses sessions (evidence: `app/api/music_manage.py`)
- Music management API → Auth dependencies: uses auth (evidence: `app/api/music_manage.py`)
- Music management API → Music models: uses models (evidence: `app/api/music_manage.py`)
- Music management extras → Music management API: reuses management (evidence: `app/api/music_manage_extra.py`)
- Music management extras → MySQL sessions: uses sessions (evidence: `app/api/music_manage_extra.py`)
- Music management extras → Auth dependencies: uses auth (evidence: `app/api/music_manage_extra.py`)
- Captains API → MySQL sessions: uses sessions (evidence: `app/api/captains.py`)
- Captains API → Auth dependencies: uses auth (evidence: `app/api/captains.py`)
- Captains API → Captain reports: uses reports (evidence: `app/api/captains.py`)
- Captain gifts API → MySQL sessions: uses sessions (evidence: `app/api/captaingift.py`)
- Captain gifts API → Auth dependencies: uses auth (evidence: `app/api/captaingift.py`)
- Captain gifts API → Gift archive service: uses archive (evidence: `app/api/captaingift.py`)
- Live status API → Captain live listener: reads status (evidence: `app/api/live.py`)
- Captain live listener → MySQL sessions: writes records (evidence: `app/services/bili_captain_listener.py`)
- Captain live listener → Captain reports: uses reports (evidence: `app/services/bili_captain_listener.py`)
- Gift archive service → MySQL sessions: uses sessions (evidence: `app/services/captain_gift_archive.py`)
- WebSocket client → Message handlers: dispatches messages (evidence: `blivedm/clients/ws_base.py`)
- Message handlers → WebSocket client: receives commands (evidence: `blivedm/handlers.py`)
