# qianqiuzy/vr_douchong architecture

> Architecture diagram of the GitHub repository qianqiuzy/vr_douchong, 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/vr_douchong
- Repository: https://github.com/qianqiuzy/vr_douchong

## Overview

VR斗虫 is a Bilibili live-room leaderboard and statistics service, with monthly archiving. The main paths are room configuration and API management, live-room monitoring and websocket event ingestion, metrics persistence, and report queries. The README documents dynamic room add/delete endpoints and monthly rankings; the source index identifies additional runtime and reporting modules whose internals were not excerpted, so their detailed interactions are not inferred here.

Main entry points: [`app/api_app.py`](https://github.com/qianqiuzy/vr_douchong/blob/main/app/api_app.py) (HTTP API), [`app/event_ingestion.py`](https://github.com/qianqiuzy/vr_douchong/blob/main/app/event_ingestion.py) (Event ingestion), [`app/bootstrap.py`](https://github.com/qianqiuzy/vr_douchong/blob/main/app/bootstrap.py) (Application bootstrap), [`app/database.py`](https://github.com/qianqiuzy/vr_douchong/blob/main/app/database.py) (MySQL database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and rooms"]
  node_api["HTTP API<br/>[api_app.py]"]
  node_roomcfg["Room configuration<br/>[room_config.py]"]
  node_lifecycle["Room lifecycle<br/>[room_lifecycle.py]"]
end

subgraph group_live["Live collection"]
  node_gateway["Bilibili gateway"]
  node_monitor["Live monitoring<br/>[monitoring_jobs.py]"]
  node_ws["Websocket client<br/>[ws_base.py]"]
  node_handlers["Message dispatch<br/>[handlers.py]"]
  node_ingestion["Event ingestion<br/>[event_ingestion.py]"]
end

subgraph group_metrics["Metrics and storage"]
  node_metrics_runtime["Metrics runtime<br/>[metrics_runtime.py]"]
  node_whale["Whale metrics<br/>[whale_metrics.py]"]
  node_redis["Redis metrics<br/>[redis_metrics.py]"]
  node_api_models["Report models<br/>[aggregates.py]"]
  node_sessions["Session models<br/>[sessions.py]"]
  node_repos["Persistence helpers<br/>[tables.py]"]
  node_database[("MySQL database<br/>[database.py]")]
  node_archive["Monthly archiving<br/>[archive_service.py]"]
end

subgraph group_runtime["Runtime operations"]
  node_state["Runtime state<br/>[runtime_state.py]"]
  node_bootstrap["Application bootstrap<br/>[bootstrap.py]"]
  node_gift["Runtime launcher<br/>[gift.py]"]
end

node_operator(("Operator"))
node_bilibili(("Bilibili Live"))

node_operator -->|"manages rooms"| node_api
node_api -->|"updates rooms"| node_roomcfg
node_api -->|"controls rooms"| node_lifecycle
node_api -->|"queries reports"| node_database
node_operator -->|"launches service"| node_gift
node_gift -->|"starts runtime"| node_bootstrap
node_bootstrap -->|"starts API"| node_api
node_bootstrap -->|"starts jobs"| node_monitor
node_bootstrap -->|"initializes gateway"| node_gateway
node_bootstrap -->|"runs archiving"| node_archive
node_monitor -->|"fetches room data"| node_gateway
node_monitor -->|"uses runtime state"| node_state
node_monitor -->|"starts ingestion"| node_ingestion
node_bilibili -->|"sends live events"| node_ws
node_ws -->|"dispatches messages"| node_handlers
node_handlers -.->|"routes events"| node_ingestion
node_ingestion -->|"reads session state"| node_state
node_ingestion -->|"updates sessions"| node_sessions
node_ingestion -->|"updates monthly totals"| node_api_models
node_ingestion -->|"records metrics"| node_whale
node_metrics_runtime -->|"uses metrics cache"| node_redis
node_sessions -->|"persists records"| node_database
node_api_models -->|"persists aggregates"| node_database
node_repos -->|"uses engine"| node_database
node_archive -->|"copies archive data"| node_database
node_archive -->|"uses table helpers"| node_repos
node_api -->|"reports metrics"| node_whale

click node_api "https://github.com/qianqiuzy/vr_douchong/blob/main/app/api_app.py"
click node_roomcfg "https://github.com/qianqiuzy/vr_douchong/blob/main/app/room_config.py"
click node_lifecycle "https://github.com/qianqiuzy/vr_douchong/blob/main/app/room_lifecycle.py"
click node_gateway "https://github.com/qianqiuzy/vr_douchong/blob/main/app/bilibili_gateway.py"
click node_monitor "https://github.com/qianqiuzy/vr_douchong/blob/main/app/monitoring_jobs.py"
click node_ws "https://github.com/qianqiuzy/vr_douchong/blob/main/app/blivedm/clients/ws_base.py"
click node_handlers "https://github.com/qianqiuzy/vr_douchong/blob/main/app/blivedm/handlers.py"
click node_ingestion "https://github.com/qianqiuzy/vr_douchong/blob/main/app/event_ingestion.py"
click node_state "https://github.com/qianqiuzy/vr_douchong/blob/main/app/runtime_state.py"
click node_metrics_runtime "https://github.com/qianqiuzy/vr_douchong/blob/main/app/metrics_runtime.py"
click node_whale "https://github.com/qianqiuzy/vr_douchong/blob/main/app/whale_metrics.py"
click node_redis "https://github.com/qianqiuzy/vr_douchong/blob/main/app/redis_metrics.py"
click node_api_models "https://github.com/qianqiuzy/vr_douchong/blob/main/app/models/aggregates.py"
click node_sessions "https://github.com/qianqiuzy/vr_douchong/blob/main/app/models/sessions.py"
click node_repos "https://github.com/qianqiuzy/vr_douchong/blob/main/app/repositories/tables.py"
click node_database "https://github.com/qianqiuzy/vr_douchong/blob/main/app/database.py"
click node_archive "https://github.com/qianqiuzy/vr_douchong/blob/main/app/archive_service.py"
click node_bootstrap "https://github.com/qianqiuzy/vr_douchong/blob/main/app/bootstrap.py"
click node_gift "https://github.com/qianqiuzy/vr_douchong/blob/main/app/gift.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_api,node_roomcfg,node_lifecycle toneBlue
class node_gateway,node_monitor,node_ws,node_handlers,node_ingestion toneAmber
class node_metrics_runtime,node_whale,node_redis,node_api_models,node_sessions,node_repos,node_database,node_archive toneMint
class node_state,node_bootstrap,node_gift toneRose
class node_operator,node_bilibili toneIndigo
```

## Components

### API and rooms

- [HTTP API](https://github.com/qianqiuzy/vr_douchong/blob/main/app/api_app.py): `app/api_app.py`
- [Room configuration](https://github.com/qianqiuzy/vr_douchong/blob/main/app/room_config.py): `app/room_config.py`
- [Room lifecycle](https://github.com/qianqiuzy/vr_douchong/blob/main/app/room_lifecycle.py): `app/room_lifecycle.py`

### Live collection

- [Bilibili gateway](https://github.com/qianqiuzy/vr_douchong/blob/main/app/bilibili_gateway.py): `app/bilibili_gateway.py`
- [Live monitoring](https://github.com/qianqiuzy/vr_douchong/blob/main/app/monitoring_jobs.py): `app/monitoring_jobs.py`
- [Websocket client](https://github.com/qianqiuzy/vr_douchong/blob/main/app/blivedm/clients/ws_base.py): `app/blivedm/clients/ws_base.py`
- [Message dispatch](https://github.com/qianqiuzy/vr_douchong/blob/main/app/blivedm/handlers.py): `app/blivedm/handlers.py`
- [Event ingestion](https://github.com/qianqiuzy/vr_douchong/blob/main/app/event_ingestion.py): `app/event_ingestion.py`

### Metrics and storage

- [Metrics runtime](https://github.com/qianqiuzy/vr_douchong/blob/main/app/metrics_runtime.py): `app/metrics_runtime.py`
- [Whale metrics](https://github.com/qianqiuzy/vr_douchong/blob/main/app/whale_metrics.py): `app/whale_metrics.py`
- [Redis metrics](https://github.com/qianqiuzy/vr_douchong/blob/main/app/redis_metrics.py): `app/redis_metrics.py`
- [Report models](https://github.com/qianqiuzy/vr_douchong/blob/main/app/models/aggregates.py): `app/models/aggregates.py`
- [Session models](https://github.com/qianqiuzy/vr_douchong/blob/main/app/models/sessions.py): `app/models/sessions.py`
- [Persistence helpers](https://github.com/qianqiuzy/vr_douchong/blob/main/app/repositories/tables.py): `app/repositories/tables.py`
- [MySQL database](https://github.com/qianqiuzy/vr_douchong/blob/main/app/database.py): `app/database.py`
- [Monthly archiving](https://github.com/qianqiuzy/vr_douchong/blob/main/app/archive_service.py): `app/archive_service.py`

### Runtime operations

- [Runtime state](https://github.com/qianqiuzy/vr_douchong/blob/main/app/runtime_state.py): `app/runtime_state.py`
- [Application bootstrap](https://github.com/qianqiuzy/vr_douchong/blob/main/app/bootstrap.py): `app/bootstrap.py`
- [Runtime launcher](https://github.com/qianqiuzy/vr_douchong/blob/main/app/gift.py): `app/gift.py`

### Other components

- **Operator**
- **Bilibili Live**

## Connections

- Operator → HTTP API: manages rooms
- HTTP API → Room configuration: updates rooms (evidence: `app/api_app.py`)
- HTTP API → Room lifecycle: controls rooms (evidence: `app/api_app.py`)
- HTTP API → MySQL database: queries reports (evidence: `app/api_app.py`)
- Operator → Runtime launcher: launches service
- Runtime launcher → Application bootstrap: starts runtime (evidence: `app/gift.py`)
- Application bootstrap → HTTP API: starts API (evidence: `app/bootstrap.py`)
- Application bootstrap → Live monitoring: starts jobs (evidence: `app/bootstrap.py`)
- Application bootstrap → Bilibili gateway: initializes gateway (evidence: `app/bootstrap.py`)
- Application bootstrap → Monthly archiving: runs archiving (evidence: `app/bootstrap.py`)
- Live monitoring → Bilibili gateway: fetches room data (evidence: `app/monitoring_jobs.py`)
- Live monitoring → Runtime state: uses runtime state (evidence: `app/monitoring_jobs.py`)
- Live monitoring → Event ingestion: starts ingestion (evidence: `app/monitoring_jobs.py`)
- Bilibili Live → Websocket client: sends live events (evidence: `app/blivedm/clients/ws_base.py`)
- Websocket client → Message dispatch: dispatches messages (evidence: `app/blivedm/clients/ws_base.py`)
- Message dispatch → Event ingestion: routes events
- Event ingestion → Runtime state: reads session state (evidence: `app/event_ingestion.py`)
- Event ingestion → Session models: updates sessions (evidence: `app/event_ingestion.py`)
- Event ingestion → Report models: updates monthly totals (evidence: `app/event_ingestion.py`)
- Event ingestion → Whale metrics: records metrics (evidence: `app/event_ingestion.py`)
- Metrics runtime → Redis metrics: uses metrics cache (evidence: `app/metrics_runtime.py`)
- Session models → MySQL database: persists records (evidence: `app/models/sessions.py`)
- Report models → MySQL database: persists aggregates (evidence: `app/models/aggregates.py`)
- Persistence helpers → MySQL database: uses engine (evidence: `app/repositories/tables.py`)
- Monthly archiving → MySQL database: copies archive data (evidence: `app/archive_service.py`)
- Monthly archiving → Persistence helpers: uses table helpers (evidence: `app/archive_service.py`)
- HTTP API → Whale metrics: reports metrics (evidence: `app/api_app.py`)
