How danielgregorio/cazalberto works
High-Level Components
a. Entry Point & Configuration
• bot.py (Discord client initialization & startup)
• config.py / .env (token loading, basic config)
b. Discord Gateway & API Layer
• Discord.py library handling WebSocket connection, event loop, REST API calls
c. Command Dispatcher & Cog Modules
• cogs/ (audio_commands.py, misc_commands.py, playlist_commands.py, wow_commands.py)
• clean-commands-json.py & force_sync.py (scripts for JSON → Discord slash-command sync)
d. Data Storage
• JSON files under data/ (commands.json)
• playlists.json
• commands.json (root, backup)
e. Audio Processing Pipeline
• FFmpeg subprocess calls (via utils.py or directly in audio_commands.py)
• Local audio files (managed via add/remove commands)
f. Utility & Logging
• utils.py (common helpers, logging configuration)
g. External Dependencies
• Discord API (gateway + REST)
• FFmpeg executable (system-installed)
Relationships & Data Flows
1. Startup
– bot.py reads config.py (.env) → instantiates Discord client
2. Event Reception
– Discord API Gateway → Discord.py event handlers
3. Command Invocation
– Incoming slash command → Dispatcher → appropriate Cog
4. Data Access
– Cog reads/writes JSON storage → data persistence on disk
5. Audio Playback
– Cog invokes FFmpeg (via subprocess) → decodes/transcodes clip → streams to voice channel via Discord.py
6. Command Sync Scripts
– force_sync.py / clean-commands-json.py read commands.json → REST-call to Discord to register slash commands
Architectural Patterns & Design Principles
• Modular “Cog” pattern (Discord.py extension mechanism) separates command domains (audio, misc, playlist, wow)
• Single-process, event-driven architecture
• File-based persistence (JSON) rather than a DB—model this as a “flat-file store”
• External process integration (FFmpeg) for media handling
• Scripts folderless approach—scripts at root for one-off tasks
Final Checklist
– [ ] Clear labels on every component (module name, file name)