# matsuk1/jietng-maimai-dx-bot architecture

> Architecture diagram of the GitHub repository matsuk1/jietng-maimai-dx-bot, 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/matsuk1/jietng-maimai-dx-bot
- Repository: https://github.com/matsuk1/jietng-maimai-dx-bot

## Overview

JiETNG is a LINE bot and web service for tracking maimai DX scores, managing player accounts and presenting game data. The main workflow starts with a player request delivered through LINE, passes through the application’s request handling, fetches or reads game data, and returns localized text or generated score imagery. Separate branches cover the web administration and AI operations capabilities documented in the README. Source excerpts and the index support the core data, image, and integration components; some unsampled subsystem connections are therefore left out.

Main entry points: [`main.py`](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/main.py) (Bot and web app), [`modules/record_manager.py`](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/record_manager.py) (Score records), [`modules/images/records.py`](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/images/records.py) (Score images), [`modules/api/admin_api.py`](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/api/admin_api.py) (Web administration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Player interaction"]
  node_app["Bot and web app<br/>[main.py]"]
  node_messages["Message service<br/>[service.py]"]
  node_commands["Command routing<br/>[command_router.py]"]
  node_discord["Discord bot<br/>[bot.py]"]
  node_sdk["Python client SDK<br/>[client.py]"]
end

subgraph group_game_data["Game data"]
  node_game_fetch["SEGA game access<br/>[maimai_manager.py]"]
  node_records["Score records<br/>[record_manager.py]"]
  node_user_manager["User management<br/>[user_manager.py]"]
  node_dxdata["Song data<br/>[dxdata_manager.py]"]
  node_rating["Rating calculation"]
end

subgraph group_presentation["Results presentation"]
  node_score_image["Score images<br/>[records.py]"]
  node_song_image["Song images<br/>[songs.py]"]
  node_renderer["Image renderer<br/>[renderer.py]"]
  node_skins["Image skins<br/>[skins.py]"]
end

subgraph group_operations["Administration and operations"]
  node_admin["Web administration<br/>[admin_api.py]"]
  node_monitoring["AI operations<br/>[mcp_server.py]"]
  node_events["Business metrics<br/>[event_tracker.py]"]
end

subgraph group_platform["Runtime platform"]
  node_user_store[("User database<br/>[user_db.py]")]
  node_localization["Localization<br/>[i18n.py]"]
  node_config["Configuration<br/>[config_loader.py]"]
end

node_players(("Players"))
node_line["LINE platform"]
node_mysql[("MySQL")]

node_players -->|"send requests"| node_line
node_line -->|"deliver webhook events"| node_app
node_app -->|"route commands"| node_commands
node_app -->|"build replies"| node_messages
node_app -->|"fetch game data"| node_game_fetch
node_app -->|"read and update"| node_records
node_app -->|"manage accounts"| node_user_manager
node_game_fetch -->|"authenticate externally"| node_line
node_records -->|"read and write scores"| node_mysql
node_user_manager -->|"manage user data"| node_user_store
node_user_store -->|"read and write users"| node_mysql
node_records -->|"enrich records"| node_dxdata
node_app -->|"update song data"| node_dxdata
node_records -->|"calculate rating"| node_rating
node_app -->|"generate score charts"| node_score_image
node_app -->|"generate song images"| node_song_image
node_score_image -->|"render templates"| node_renderer
node_song_image -->|"render templates"| node_renderer
node_score_image -->|"apply skin"| node_skins
node_messages -->|"translate messages"| node_localization
node_app -->|"serve admin features"| node_admin
node_admin -->|"offer AI operations"| node_monitoring
node_admin -->|"report business metrics"| node_events
node_app -->|"load settings"| node_config
node_discord -.->|"use client API"| node_sdk

click node_app "https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/main.py"
click node_messages "https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/messages/service.py"
click node_commands "https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/commands/command_router.py"
click node_game_fetch "https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/maimai_manager.py"
click node_records "https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/record_manager.py"
click node_user_manager "https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/user_manager.py"
click node_user_store "https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/user_db.py"
click node_dxdata "https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/dxdata_manager.py"
click node_rating "https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/score_calculator.py"
click node_score_image "https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/images/records.py"
click node_song_image "https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/images/songs.py"
click node_renderer "https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/images/renderer.py"
click node_skins "https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/images/skins.py"
click node_localization "https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/i18n.py"
click node_admin "https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/api/admin_api.py"
click node_monitoring "https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/monitoring/mcp_server.py"
click node_events "https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/event_tracker.py"
click node_config "https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/config_loader.py"
click node_discord "https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/discord_bot/jietng_discord_bot/bot.py"
click node_sdk "https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/client/src/jietng/client.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_messages,node_commands,node_discord,node_sdk toneBlue
class node_game_fetch,node_records,node_user_manager,node_dxdata,node_rating,node_mysql toneAmber
class node_score_image,node_song_image,node_renderer,node_skins toneMint
class node_admin,node_monitoring,node_events toneRose
class node_user_store,node_localization,node_config,node_players,node_line toneIndigo
```

## Components

### Player interaction

- [Bot and web app](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/main.py): `main.py`
- [Message service](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/messages/service.py): `modules/messages/service.py`
- [Command routing](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/commands/command_router.py): `modules/commands/command_router.py`
- [Discord bot](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/discord_bot/jietng_discord_bot/bot.py): `discord_bot/jietng_discord_bot/bot.py`
- [Python client SDK](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/client/src/jietng/client.py): `client/src/jietng/client.py`

### Game data

- [SEGA game access](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/maimai_manager.py): `modules/maimai_manager.py`
- [Score records](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/record_manager.py): `modules/record_manager.py`
- [User management](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/user_manager.py): `modules/user_manager.py`
- [Song data](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/dxdata_manager.py): `modules/dxdata_manager.py`
- [Rating calculation](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/score_calculator.py): `modules/score_calculator.py`

### Results presentation

- [Score images](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/images/records.py): `modules/images/records.py`
- [Song images](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/images/songs.py): `modules/images/songs.py`
- [Image renderer](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/images/renderer.py): `modules/images/renderer.py`
- [Image skins](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/images/skins.py): `modules/images/skins.py`

### Administration and operations

- [Web administration](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/api/admin_api.py): `modules/api/admin_api.py`
- [AI operations](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/monitoring/mcp_server.py): `modules/monitoring/mcp_server.py`
- [Business metrics](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/event_tracker.py): `modules/event_tracker.py`

### Runtime platform

- [User database](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/user_db.py): `modules/user_db.py`
- [Localization](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/i18n.py): `modules/i18n.py`
- [Configuration](https://github.com/matsuk1/jietng-maimai-dx-bot/blob/main/modules/config_loader.py): `modules/config_loader.py`

### Other components

- **Players**
- **LINE platform**
- **MySQL**

## Connections

- Players → LINE platform: send requests
- LINE platform → Bot and web app: deliver webhook events
- Bot and web app → Command routing: route commands (evidence: `main.py`)
- Bot and web app → Message service: build replies (evidence: `main.py`)
- Bot and web app → SEGA game access: fetch game data (evidence: `main.py`)
- Bot and web app → Score records: read and update (evidence: `main.py`)
- Bot and web app → User management: manage accounts (evidence: `main.py`)
- SEGA game access → LINE platform: authenticate externally (evidence: `modules/maimai_manager.py`)
- Score records → MySQL: read and write scores (evidence: `modules/record_manager.py`)
- User management → User database: manage user data
- User database → MySQL: read and write users (evidence: `modules/user_db.py`)
- Score records → Song data: enrich records (evidence: `modules/record_manager.py`)
- Bot and web app → Song data: update song data (evidence: `main.py`)
- Score records → Rating calculation: calculate rating
- Bot and web app → Score images: generate score charts (evidence: `main.py`)
- Bot and web app → Song images: generate song images (evidence: `modules/images/songs.py`)
- Score images → Image renderer: render templates (evidence: `modules/images/records.py`)
- Song images → Image renderer: render templates (evidence: `modules/images/songs.py`)
- Score images → Image skins: apply skin (evidence: `modules/images/records.py`)
- Message service → Localization: translate messages (evidence: `modules/messages/service.py`)
- Bot and web app → Web administration: serve admin features
- Web administration → AI operations: offer AI operations
- Web administration → Business metrics: report business metrics
- Bot and web app → Configuration: load settings (evidence: `modules/config_loader.py`)
- Discord bot → Python client SDK: use client API
