# danielgregorio/cazalberto architecture

> Architecture diagram of the GitHub repository danielgregorio/cazalberto, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/danielgregorio/cazalberto
- Repository: https://github.com/danielgregorio/cazalberto

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Discord Layer
    subgraph "Discord Layer"
        DiscordAPI(("Discord API")):::external
    end

    %% Application Layer
    subgraph "Application Layer"
        config["config.py"]:::core
        bot["bot.py"]:::core
        utils["utils.py"]:::core
        subgraph "Command Modules"
            audio["audio_commands.py"]:::core
            misc["misc_commands.py"]:::core
            playlist["playlist_commands.py"]:::core
            wow["wow_commands.py"]:::core
        end
        clean["clean-commands-json.py"]:::script
        sync["force_sync.py"]:::script
        installer["instalar-servico.bat"]:::script
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        cmds_data["data/commands.json"]:::data
        playlists["playlists.json"]:::data
        cmds_root["commands.json"]:::data
        cmds_backup["commands_backup.json"]:::data
    end

    %% External Tools
    subgraph "External Tools"
        FFmpeg(("FFmpeg")):::external
    end

    %% Connections
    DiscordAPI -->|"WebSocket events"| bot
    bot -->|loads| config
    bot -->|uses| utils
    bot -->|dispatches to| audio
    bot -->|dispatches to| misc
    bot -->|dispatches to| playlist
    bot -->|dispatches to| wow

    audio -->|read/write JSON| cmds_data
    playlist -->|read/write JSON| playlists
    playlist -->|read/write JSON| cmds_root
    playlist -->|read/write JSON| cmds_backup

    audio -->|invokes subprocess| FFmpeg
    audio -->|uses| utils

    clean -->|reads| cmds_root
    clean -->|syncs via REST| DiscordAPI
    sync -->|reads| cmds_root
    sync -->|calls REST| DiscordAPI

    installer -->|installs service| bot

    %% Click Events
    click config "https://github.com/danielgregorio/cazalberto/blob/main/config.py"
    click bot "https://github.com/danielgregorio/cazalberto/blob/main/bot.py"
    click audio "https://github.com/danielgregorio/cazalberto/blob/main/cogs/audio_commands.py"
    click misc "https://github.com/danielgregorio/cazalberto/blob/main/cogs/misc_commands.py"
    click playlist "https://github.com/danielgregorio/cazalberto/blob/main/cogs/playlist_commands.py"
    click wow "https://github.com/danielgregorio/cazalberto/blob/main/cogs/wow_commands.py"
    click clean "https://github.com/danielgregorio/cazalberto/blob/main/clean-commands-json.py"
    click sync "https://github.com/danielgregorio/cazalberto/blob/main/force_sync.py"
    click cmds_data "https://github.com/danielgregorio/cazalberto/blob/main/data/commands.json"
    click playlists "https://github.com/danielgregorio/cazalberto/blob/main/playlists.json"
    click cmds_root "https://github.com/danielgregorio/cazalberto/blob/main/commands.json"
    click cmds_backup "https://github.com/danielgregorio/cazalberto/blob/main/commands_backup.json"
    click utils "https://github.com/danielgregorio/cazalberto/blob/main/utils.py"
    click installer "https://github.com/danielgregorio/cazalberto/blob/main/instalar-servico.bat"

    %% Styles
    classDef core fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef data fill:#d4edda,stroke:#28a745,color:#000;
    classDef external fill:#ffe5b4,stroke:#ff8c00,color:#000;
    classDef script fill:#e2e3e5,stroke:#6c757d,color:#000;
```
