# chuanyuannotboat/malody_data_studio architecture

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

## Overview

Malody Data Studio is a local Malody data platform: users query and analyze player/chart data, manage collection and database quality, and use a desktop interface or API; a plugin-based CLI is an additional access path. The central API flow is HTTP request → router → domain service or crawler controller → SQLite or external Malody source → response. README capabilities include page parsing, analytics, advanced queries, task management, plugins, and maintenance. Some subsystem links are documented rather than source-verified; those are marked dashed where appropriate.

Main entry points: [`app/main.py`](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/app/main.py) (FastAPI App), [`core/database.py`](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/core/database.py) (SQLite Database), [`crawlers/controller.py`](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/crawlers/controller.py) (Crawler Control), [`crawlers/rankings.py`](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/crawlers/rankings.py) (Rankings Crawler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User Interfaces"]
  node_desktop["Desktop App<br/>[App.tsx]"]
  node_cli["Stats CLI<br/>[app.py]"]
  node_cli_plugins["CLI Plugins<br/>[registry.py]"]
end

subgraph group_api["API and Domain"]
  node_app["FastAPI App<br/>[main.py]"]
  node_player["Player Queries<br/>[player_service.py]"]
  node_chart["Chart Queries<br/>[chart_service.py]"]
  node_analytics["Analytics"]
  node_parser["Page Parser<br/>[page_parser.py]"]
  node_query["Advanced Query<br/>[query_builder.py]"]
end

subgraph group_collection["Data Collection"]
  node_crawlers["Crawler Control<br/>[controller.py]"]
  node_rankings["Rankings Crawler<br/>[rankings.py]"]
  node_profiles["Profile Crawler<br/>[player_profile.py]"]
  node_stb["STB Crawler<br/>[stb.py]"]
end

subgraph group_storage["Persistence"]
  node_sqlite[("SQLite Database<br/>[database.py]")]
end

subgraph group_ops["Operations and Extensions"]
  node_quality["Quality Checks<br/>[quality_service.py]"]
  node_tasks["Task Center"]
  node_maintenance["DB Maintenance"]
  node_plugins["Plugin Services<br/>[plugin_service.py]"]
  node_official["Official API"]
end

node_user(("Operator"))
node_http(("HTTP Client"))
node_malody(("Malody Services"))

node_user -->|"uses"| node_desktop
node_desktop -.->|"requests data"| node_http
node_http -->|"sends requests"| node_app
node_app -.->|"routes player requests"| node_player
node_app -.->|"routes chart requests"| node_chart
node_app -.->|"routes analysis"| node_analytics
node_app -.->|"routes parsing"| node_parser
node_app -->|"routes query"| node_query
node_player -->|"reads"| node_sqlite
node_chart -.->|"reads"| node_sqlite
node_analytics -.->|"reads"| node_sqlite
node_query -.->|"queries"| node_sqlite
node_parser -.->|"looks up songs"| node_sqlite
node_user -->|"uses"| node_cli
node_cli -->|"dispatches commands"| node_cli_plugins
node_cli_plugins -.->|"queries data"| node_sqlite
node_user -.->|"starts crawler tasks"| node_app
node_app -.->|"controls collection"| node_crawlers
node_crawlers -.->|"dispatches"| node_rankings
node_crawlers -.->|"dispatches"| node_profiles
node_crawlers -.->|"dispatches"| node_stb
node_rankings -.->|"fetches data"| node_malody
node_profiles -.->|"fetches profiles"| node_malody
node_stb -.->|"fetches charts"| node_malody
node_rankings -.->|"stores results"| node_sqlite
node_profiles -.->|"stores results"| node_sqlite
node_stb -.->|"stores results"| node_sqlite
node_app -.->|"offers quality checks"| node_quality
node_app -.->|"manages tasks"| node_tasks
node_app -.->|"offers maintenance"| node_maintenance
node_app -.->|"runs plugins"| node_plugins
node_app -.->|"exposes integration"| node_official
node_quality -.->|"checks data"| node_sqlite
node_maintenance -.->|"maintains"| node_sqlite

click node_desktop "https://github.com/chuanyuannotboat/malody_data_studio/blob/main/desktop/src/App.tsx"
click node_cli "https://github.com/chuanyuannotboat/malody_data_studio/blob/main/stats_cli/app.py"
click node_app "https://github.com/chuanyuannotboat/malody_data_studio/blob/main/app/main.py"
click node_player "https://github.com/chuanyuannotboat/malody_data_studio/blob/main/core/services/player_service.py"
click node_chart "https://github.com/chuanyuannotboat/malody_data_studio/blob/main/core/services/chart_service.py"
click node_analytics "https://github.com/chuanyuannotboat/malody_data_studio/blob/main/core/services/analysis_service.py"
click node_parser "https://github.com/chuanyuannotboat/malody_data_studio/blob/main/routers/page_parser.py"
click node_query "https://github.com/chuanyuannotboat/malody_data_studio/blob/main/utils/query_builder.py"
click node_crawlers "https://github.com/chuanyuannotboat/malody_data_studio/blob/main/crawlers/controller.py"
click node_rankings "https://github.com/chuanyuannotboat/malody_data_studio/blob/main/crawlers/rankings.py"
click node_profiles "https://github.com/chuanyuannotboat/malody_data_studio/blob/main/crawlers/player_profile.py"
click node_stb "https://github.com/chuanyuannotboat/malody_data_studio/blob/main/crawlers/stb.py"
click node_sqlite "https://github.com/chuanyuannotboat/malody_data_studio/blob/main/core/database.py"
click node_quality "https://github.com/chuanyuannotboat/malody_data_studio/blob/main/core/services/quality_service.py"
click node_tasks "https://github.com/chuanyuannotboat/malody_data_studio/blob/main/core/services/task_center_service.py"
click node_maintenance "https://github.com/chuanyuannotboat/malody_data_studio/blob/main/core/services/db_maintenance_service.py"
click node_plugins "https://github.com/chuanyuannotboat/malody_data_studio/blob/main/core/services/plugin_service.py"
click node_official "https://github.com/chuanyuannotboat/malody_data_studio/blob/main/core/services/official_api_service.py"
click node_cli_plugins "https://github.com/chuanyuannotboat/malody_data_studio/blob/main/stats_cli/plugins/registry.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_desktop,node_cli,node_cli_plugins,node_http toneBlue
class node_app,node_player,node_chart,node_analytics,node_parser,node_query toneAmber
class node_crawlers,node_rankings,node_profiles,node_stb toneMint
class node_sqlite toneRose
class node_quality,node_tasks,node_maintenance,node_plugins,node_official,node_user,node_malody toneIndigo
```

## Components

### User Interfaces

- [Desktop App](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/desktop/src/App.tsx): `desktop/src/App.tsx`
- [Stats CLI](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/stats_cli/app.py): `stats_cli/app.py`
- [CLI Plugins](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/stats_cli/plugins/registry.py): `stats_cli/plugins/registry.py`

### API and Domain

- [FastAPI App](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/app/main.py): `app/main.py`
- [Player Queries](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/core/services/player_service.py): `core/services/player_service.py`
- [Chart Queries](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/core/services/chart_service.py): `core/services/chart_service.py`
- [Analytics](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/core/services/analysis_service.py): `core/services/analysis_service.py`
- [Page Parser](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/routers/page_parser.py): `routers/page_parser.py`
- [Advanced Query](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/utils/query_builder.py): `utils/query_builder.py`

### Data Collection

- [Crawler Control](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/crawlers/controller.py): `crawlers/controller.py`
- [Rankings Crawler](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/crawlers/rankings.py): `crawlers/rankings.py`
- [Profile Crawler](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/crawlers/player_profile.py): `crawlers/player_profile.py`
- [STB Crawler](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/crawlers/stb.py): `crawlers/stb.py`

### Persistence

- [SQLite Database](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/core/database.py): `core/database.py`

### Operations and Extensions

- [Quality Checks](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/core/services/quality_service.py): `core/services/quality_service.py`
- [Task Center](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/core/services/task_center_service.py): `core/services/task_center_service.py`
- [DB Maintenance](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/core/services/db_maintenance_service.py): `core/services/db_maintenance_service.py`
- [Plugin Services](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/core/services/plugin_service.py): `core/services/plugin_service.py`
- [Official API](https://github.com/chuanyuannotboat/malody_data_studio/blob/main/core/services/official_api_service.py): `core/services/official_api_service.py`

### Other components

- **Operator**
- **HTTP Client**
- **Malody Services**

## Connections

- Operator → Desktop App: uses (evidence: `desktop/src/App.tsx`)
- Desktop App → HTTP Client: requests data
- HTTP Client → FastAPI App: sends requests
- FastAPI App → Player Queries: routes player requests
- FastAPI App → Chart Queries: routes chart requests
- FastAPI App → Analytics: routes analysis
- FastAPI App → Page Parser: routes parsing (evidence: `app/main.py`)
- FastAPI App → Advanced Query: routes query
- Player Queries → SQLite Database: reads (evidence: `core/services/player_service.py`)
- Chart Queries → SQLite Database: reads (evidence: `core/services/chart_service.py`)
- Analytics → SQLite Database: reads (evidence: `core/services/analysis_service.py`)
- Advanced Query → SQLite Database: queries (evidence: `utils/query_builder.py`)
- Page Parser → SQLite Database: looks up songs
- Operator → Stats CLI: uses (evidence: `stats_cli/app.py`)
- Stats CLI → CLI Plugins: dispatches commands (evidence: `stats_cli/app.py`)
- CLI Plugins → SQLite Database: queries data
- Operator → FastAPI App: starts crawler tasks
- FastAPI App → Crawler Control: controls collection
- Crawler Control → Rankings Crawler: dispatches
- Crawler Control → Profile Crawler: dispatches
- Crawler Control → STB Crawler: dispatches
- Rankings Crawler → Malody Services: fetches data
- Profile Crawler → Malody Services: fetches profiles
- STB Crawler → Malody Services: fetches charts
- Rankings Crawler → SQLite Database: stores results
- Profile Crawler → SQLite Database: stores results
- STB Crawler → SQLite Database: stores results
- FastAPI App → Quality Checks: offers quality checks
- FastAPI App → Task Center: manages tasks
- FastAPI App → DB Maintenance: offers maintenance
- FastAPI App → Plugin Services: runs plugins
- FastAPI App → Official API: exposes integration
- Quality Checks → SQLite Database: checks data (evidence: `core/services/quality_service.py`)
- DB Maintenance → SQLite Database: maintains
