# 31zeta/zeta-discordbot architecture

> Architecture diagram of the GitHub repository 31zeta/zeta-discordbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/31zeta/zeta-discordbot
- Repository: https://github.com/31zeta/zeta-discordbot

## Overview

Zeta Discord Bot is a Pycord music bot. The main workflow starts with a Discord user requesting a search or media link; the bot obtains media information from go-music-api, Bilibili, or YouTube, downloads or reuses audio, adds it to a guild playlist, and plays it in a voice channel. Interactive playlist controls, guild-specific state, configurable settings, and QR-based platform login are additional product capabilities. The supplied excerpts show parts of core orchestration, caching, and provider behavior; several feature links are documented in the README but their exact call wiring is not visible.

Main entry points: [`zeta_bot/core.py`](https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/core.py) (Bot commands), [`zeta_bot/file_management.py`](https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/file_management.py) (Audio cache), [`zeta_bot/go_music.py`](https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/go_music.py) (Cookie login), [`zeta_bot/ytdlp.py`](https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/ytdlp.py) (YouTube extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Discord interaction"]
  node_main["Application entry<br/>[main.py]"]
  node_core["Bot commands<br/>[core.py]"]
  node_playlist_ui["Playlist controls<br/>[core.py]"]
end

subgraph group_media["Media discovery"]
  node_go_music["Music API client<br/>[go_music.py]"]
  node_bilibili["Bilibili search<br/>[bilibili.py]"]
  node_youtube["YouTube extraction<br/>[ytdlp.py]"]
end

subgraph group_playback["Playback and state"]
  node_audio["Audio model<br/>[audio.py]"]
  node_file_library[("Audio cache<br/>[file_management.py]")]
  node_guild[("Guild state<br/>[guild.py]")]
  node_playlist["Playlist model<br/>[playlist.py]"]
  node_ffmpeg["FFmpeg playback<br/>[audio.py]"]
end

subgraph group_operations["Configuration and login"]
  node_settings[("Bot settings<br/>[setting.py]")]
  node_cookies["Cookie login<br/>[go_music.py]"]
  node_qr_entry["QR login command"]
  node_console["Console and logs<br/>[output_console.py]"]
end

node_user(("Discord user"))
node_discord{{"Discord platform"}}
node_music_api{{"go-music-api"}}
node_bili_service{{"Bilibili"}}
node_youtube_service{{"YouTube"}}
node_config_files[("Local configuration")]

node_user -->|"issues request"| node_discord
node_discord -->|"dispatches command"| node_core
node_main -->|"starts bot"| node_core
node_core -->|"sends responses"| node_discord
node_core -->|"requests media"| node_go_music
node_core -->|"searches media"| node_bilibili
node_core -->|"extracts media"| node_youtube
node_go_music -->|"requests metadata/audio"| node_music_api
node_bilibili -->|"searches/downloads"| node_bili_service
node_youtube -->|"extracts audio"| node_youtube_service
node_core -->|"gets audio files"| node_file_library
node_file_library -->|"downloads via API"| node_go_music
node_file_library -->|"downloads via yt-dlp"| node_youtube
node_core -->|"manages tracks"| node_playlist
node_guild -->|"provides playlists"| node_playlist
node_playlist_ui -->|"edits playlist"| node_playlist
node_core -->|"gets guild state"| node_guild
node_core -->|"plays audio"| node_audio
node_audio -->|"decodes audio"| node_ffmpeg
node_core -->|"loads settings"| node_settings
node_settings -->|"reads/writes"| node_config_files
node_qr_entry -->|"starts QR login"| node_cookies
node_cookies -->|"saves cookies"| node_config_files
node_cookies -->|"syncs cookies"| node_music_api
node_core -->|"records activity"| node_console

click node_main "https://github.com/31zeta/zeta-discordbot/blob/main/main.py"
click node_core "https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/core.py"
click node_playlist_ui "https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/core.py"
click node_go_music "https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/go_music.py"
click node_bilibili "https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/bilibili.py"
click node_youtube "https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/ytdlp.py"
click node_audio "https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/audio.py"
click node_file_library "https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/file_management.py"
click node_guild "https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/guild.py"
click node_playlist "https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/playlist.py"
click node_ffmpeg "https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/audio.py"
click node_settings "https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/setting.py"
click node_cookies "https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/go_music.py"
click node_qr_entry "https://github.com/31zeta/zeta-discordbot/blob/main/go_music_qr_login.py"
click node_console "https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/output_console.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_main,node_core,node_playlist_ui,node_user toneBlue
class node_go_music,node_bilibili,node_youtube,node_config_files toneAmber
class node_audio,node_file_library,node_guild,node_playlist,node_ffmpeg,node_music_api toneMint
class node_settings,node_cookies,node_qr_entry,node_console toneRose
class node_discord,node_bili_service,node_youtube_service toneIndigo
```

## Components

### Discord interaction

- [Application entry](https://github.com/31zeta/zeta-discordbot/blob/main/main.py): `main.py`
- [Bot commands](https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/core.py): `zeta_bot/core.py`
- [Playlist controls](https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/core.py): `zeta_bot/core.py`

### Media discovery

- [Music API client](https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/go_music.py): `zeta_bot/go_music.py`
- [Bilibili search](https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/bilibili.py): `zeta_bot/bilibili.py`
- [YouTube extraction](https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/ytdlp.py): `zeta_bot/ytdlp.py`

### Playback and state

- [Audio model](https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/audio.py): `zeta_bot/audio.py`
- [Audio cache](https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/file_management.py): `zeta_bot/file_management.py`
- [Guild state](https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/guild.py): `zeta_bot/guild.py`
- [Playlist model](https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/playlist.py): `zeta_bot/playlist.py`
- [FFmpeg playback](https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/audio.py): `zeta_bot/audio.py`

### Configuration and login

- [Bot settings](https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/setting.py): `zeta_bot/setting.py`
- [Cookie login](https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/go_music.py): `zeta_bot/go_music.py`
- [QR login command](https://github.com/31zeta/zeta-discordbot/blob/main/go_music_qr_login.py): `go_music_qr_login.py`
- [Console and logs](https://github.com/31zeta/zeta-discordbot/blob/main/zeta_bot/output_console.py): `zeta_bot/output_console.py`

### Other components

- **Discord user**
- **Discord platform**
- **go-music-api**
- **Bilibili**
- **YouTube**
- **Local configuration**

## Connections

- Discord user → Discord platform: issues request
- Discord platform → Bot commands: dispatches command
- Application entry → Bot commands: starts bot
- Bot commands → Discord platform: sends responses
- Bot commands → Music API client: requests media
- Bot commands → Bilibili search: searches media
- Bot commands → YouTube extraction: extracts media
- Music API client → go-music-api: requests metadata/audio
- Bilibili search → Bilibili: searches/downloads
- YouTube extraction → YouTube: extracts audio
- Bot commands → Audio cache: gets audio files
- Audio cache → Music API client: downloads via API
- Audio cache → YouTube extraction: downloads via yt-dlp
- Bot commands → Playlist model: manages tracks
- Guild state → Playlist model: provides playlists
- Playlist controls → Playlist model: edits playlist
- Bot commands → Guild state: gets guild state
- Bot commands → Audio model: plays audio
- Audio model → FFmpeg playback: decodes audio
- Bot commands → Bot settings: loads settings
- Bot settings → Local configuration: reads/writes
- QR login command → Cookie login: starts QR login
- Cookie login → Local configuration: saves cookies
- Cookie login → go-music-api: syncs cookies
- Bot commands → Console and logs: records activity