# miguotw/miyako-dcb architecture

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

- Interactive diagram: https://gitdiagram.com/miguotw/miyako-dcb
- Repository: https://github.com/miguotw/miyako-dcb

## Overview

MiYako-DCB is a Traditional Chinese Discord bot. Its main workflow is a Discord interaction routed to an enabled feature and command, which may call domain services, persist state, and reply in Discord. The README also documents scheduled/background features and event loggers. Paths and relationships for unsampled capabilities are limited to the tree, SOURCE INDEX references, and README; they are represented at subsystem level rather than inferred call-by-call.

Main entry points: [`core/router.js`](https://github.com/miguotw/miyako-dcb/blob/main/core/router.js) (Interaction router), [`core/runtime.js`](https://github.com/miguotw/miyako-dcb/blob/main/core/runtime.js) (Runtime orchestration), [`core/jsonRepository.js`](https://github.com/miguotw/miyako-dcb/blob/main/core/jsonRepository.js) (JSON persistence), [`src/commands/music.js`](https://github.com/miguotw/miyako-dcb/blob/main/src/commands/music.js) (Music playback)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_entry["Runtime lifecycle<br/>[index.js]"]
  node_runtimecore["Runtime orchestration<br/>[runtime.js]"]
  node_config["Config validation<br/>[config.js]"]
  node_manifests["Feature manifests<br/>[index.js]"]
  node_router["Interaction router<br/>[router.js]"]
  node_scheduler["Job scheduler<br/>[scheduler.js]"]
  node_reply["Reply and logging<br/>[Reply.js]"]
end

subgraph group_commands["Interactions"]
  node_general["Public commands"]
  node_management["Admin commands"]
  node_provider["Global announcements"]
end

subgraph group_domains["Domain features"]
  node_music["Music playback<br/>[music.js]"]
  node_tracking["Package tracking<br/>[packageTracking.js]"]
  node_checkin["Game check-in<br/>[gameCheckIn.js]"]
  node_events["Events and logging"]
end

subgraph group_services["Services and state"]
  node_musicplayer["Player and queue<br/>[musicPlayer.js]"]
  node_musicmanager["Media processing<br/>[ytDlpManager.js]"]
  node_checkinservice["Check-in jobs<br/>[game_check_in.js]"]
  node_repositories[("JSON persistence<br/>[jsonRepository.js]")]
  node_http["HTTP client<br/>[http.js]"]
end

subgraph group_integrations["External systems"]
  node_discord{{"Discord API"}}
  node_providers{{"Game and media providers"}}
end

node_user(("Discord user"))

node_user -->|"submits interaction"| node_discord
node_discord -->|"delivers interaction"| node_router
node_entry -->|"starts runtime"| node_runtimecore
node_runtimecore -->|"loads settings"| node_config
node_runtimecore -->|"creates manifests"| node_manifests
node_runtimecore -->|"configures routes"| node_router
node_runtimecore -->|"provides scheduler"| node_scheduler
node_manifests -->|"registers commands"| node_general
node_manifests -->|"registers commands"| node_management
node_router -->|"dispatches"| node_general
node_router -->|"dispatches"| node_management
node_router -->|"checks provider access"| node_provider
node_router -->|"reports failures"| node_reply
node_general -->|"replies"| node_discord
node_management -.->|"reads and writes"| node_repositories
node_provider -->|"publishes guild messages"| node_discord
node_music -->|"controls playback"| node_musicplayer
node_music -->|"resolves media"| node_musicmanager
node_music -->|"stores snapshots"| node_repositories
node_musicplayer -->|"plays voice audio"| node_discord
node_musicmanager -->|"fetches media"| node_providers
node_musicmanager -->|"downloads binary"| node_http
node_tracking -->|"stores packages"| node_repositories
node_tracking -->|"queries tracking"| node_providers
node_checkin -->|"manages credentials"| node_repositories
node_checkinservice -->|"processes check-in state"| node_repositories
node_checkinservice -->|"runs daily sign-in"| node_providers
node_scheduler -->|"runs scheduled jobs"| node_checkinservice
node_events -->|"handles events"| node_discord
node_events -.->|"registers background work"| node_scheduler
node_reply -->|"sends log messages"| node_discord

click node_entry "https://github.com/miguotw/miyako-dcb/blob/main/index.js"
click node_runtimecore "https://github.com/miguotw/miyako-dcb/blob/main/core/runtime.js"
click node_config "https://github.com/miguotw/miyako-dcb/blob/main/core/config.js"
click node_manifests "https://github.com/miguotw/miyako-dcb/blob/main/src/features/index.js"
click node_router "https://github.com/miguotw/miyako-dcb/blob/main/core/router.js"
click node_scheduler "https://github.com/miguotw/miyako-dcb/blob/main/core/scheduler.js"
click node_general "https://github.com/miguotw/miyako-dcb/tree/main/src/commands"
click node_management "https://github.com/miguotw/miyako-dcb/tree/main/src/commands/admin"
click node_provider "https://github.com/miguotw/miyako-dcb/blob/main/src/commands/globalAnnouncement.js"
click node_music "https://github.com/miguotw/miyako-dcb/blob/main/src/commands/music.js"
click node_tracking "https://github.com/miguotw/miyako-dcb/blob/main/src/commands/packageTracking.js"
click node_checkin "https://github.com/miguotw/miyako-dcb/blob/main/src/commands/gameCheckIn.js"
click node_events "https://github.com/miguotw/miyako-dcb/tree/main/src/features"
click node_musicplayer "https://github.com/miguotw/miyako-dcb/blob/main/util/musicPlayer.js"
click node_musicmanager "https://github.com/miguotw/miyako-dcb/blob/main/util/ytDlpManager.js"
click node_checkinservice "https://github.com/miguotw/miyako-dcb/blob/main/src/modules/event/game_check_in.js"
click node_repositories "https://github.com/miguotw/miyako-dcb/blob/main/core/jsonRepository.js"
click node_http "https://github.com/miguotw/miyako-dcb/blob/main/core/http.js"
click node_reply "https://github.com/miguotw/miyako-dcb/blob/main/core/Reply.js"

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_runtimecore,node_config,node_manifests,node_router,node_scheduler,node_reply,node_user toneBlue
class node_general,node_management,node_provider toneAmber
class node_music,node_tracking,node_checkin,node_events toneMint
class node_musicplayer,node_musicmanager,node_checkinservice,node_repositories,node_http toneRose
class node_discord,node_providers toneIndigo
```

## Components

### Bot runtime

- [Runtime lifecycle](https://github.com/miguotw/miyako-dcb/blob/main/index.js): `index.js`
- [Runtime orchestration](https://github.com/miguotw/miyako-dcb/blob/main/core/runtime.js): `core/runtime.js`
- [Config validation](https://github.com/miguotw/miyako-dcb/blob/main/core/config.js): `core/config.js`
- [Feature manifests](https://github.com/miguotw/miyako-dcb/blob/main/src/features/index.js): `src/features/index.js`
- [Interaction router](https://github.com/miguotw/miyako-dcb/blob/main/core/router.js): `core/router.js`
- [Job scheduler](https://github.com/miguotw/miyako-dcb/blob/main/core/scheduler.js): `core/scheduler.js`
- [Reply and logging](https://github.com/miguotw/miyako-dcb/blob/main/core/Reply.js): `core/Reply.js`

### Interactions

- [Public commands](https://github.com/miguotw/miyako-dcb/tree/main/src/commands): `src/commands`
- [Admin commands](https://github.com/miguotw/miyako-dcb/tree/main/src/commands/admin): `src/commands/admin`
- [Global announcements](https://github.com/miguotw/miyako-dcb/blob/main/src/commands/globalAnnouncement.js): `src/commands/globalAnnouncement.js`

### Domain features

- [Music playback](https://github.com/miguotw/miyako-dcb/blob/main/src/commands/music.js): `src/commands/music.js`
- [Package tracking](https://github.com/miguotw/miyako-dcb/blob/main/src/commands/packageTracking.js): `src/commands/packageTracking.js`
- [Game check-in](https://github.com/miguotw/miyako-dcb/blob/main/src/commands/gameCheckIn.js): `src/commands/gameCheckIn.js`
- [Events and logging](https://github.com/miguotw/miyako-dcb/tree/main/src/features): `src/features`

### Services and state

- [Player and queue](https://github.com/miguotw/miyako-dcb/blob/main/util/musicPlayer.js): `util/musicPlayer.js`
- [Media processing](https://github.com/miguotw/miyako-dcb/blob/main/util/ytDlpManager.js): `util/ytDlpManager.js`
- [Check-in jobs](https://github.com/miguotw/miyako-dcb/blob/main/src/modules/event/game_check_in.js): `src/modules/event/game_check_in.js`
- [JSON persistence](https://github.com/miguotw/miyako-dcb/blob/main/core/jsonRepository.js): `core/jsonRepository.js`
- [HTTP client](https://github.com/miguotw/miyako-dcb/blob/main/core/http.js): `core/http.js`

### External systems

- **Discord API**
- **Game and media providers**

### Other components

- **Discord user**

## Connections

- Discord user → Discord API: submits interaction
- Discord API → Interaction router: delivers interaction
- Runtime lifecycle → Runtime orchestration: starts runtime (evidence: `index.js`)
- Runtime orchestration → Config validation: loads settings (evidence: `core/runtime.js`)
- Runtime orchestration → Feature manifests: creates manifests (evidence: `core/runtime.js`)
- Runtime orchestration → Interaction router: configures routes (evidence: `core/runtime.js`)
- Runtime orchestration → Job scheduler: provides scheduler (evidence: `core/runtime.js`)
- Feature manifests → Public commands: registers commands (evidence: `src/features/index.js`)
- Feature manifests → Admin commands: registers commands (evidence: `src/features/index.js`)
- Interaction router → Public commands: dispatches
- Interaction router → Admin commands: dispatches
- Interaction router → Global announcements: checks provider access
- Interaction router → Reply and logging: reports failures (evidence: `core/router.js`)
- Public commands → Discord API: replies (evidence: `src/commands/ipQuery.js`)
- Admin commands → JSON persistence: reads and writes
- Global announcements → Discord API: publishes guild messages
- Music playback → Player and queue: controls playback (evidence: `src/commands/music.js`)
- Music playback → Media processing: resolves media (evidence: `src/commands/music.js`)
- Music playback → JSON persistence: stores snapshots
- Player and queue → Discord API: plays voice audio
- Media processing → Game and media providers: fetches media
- Media processing → HTTP client: downloads binary (evidence: `util/ytDlpManager.js`)
- Package tracking → JSON persistence: stores packages (evidence: `src/commands/packageTracking.js`)
- Package tracking → Game and media providers: queries tracking
- Game check-in → JSON persistence: manages credentials
- Check-in jobs → JSON persistence: processes check-in state (evidence: `src/modules/event/game_check_in.js`)
- Check-in jobs → Game and media providers: runs daily sign-in
- Job scheduler → Check-in jobs: runs scheduled jobs
- Events and logging → Discord API: handles events
- Events and logging → Job scheduler: registers background work
- Reply and logging → Discord API: sends log messages (evidence: `core/Reply.js`)
