# nicoeugui/atc-discord-bot architecture

> Architecture diagram of the GitHub repository nicoeugui/atc-discord-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nicoeugui/atc-discord-bot
- Repository: https://github.com/nicoeugui/atc-discord-bot

## Overview

##### Project Type and Purpose
- The project is a Discord bot built specifically to fetch and play live ATC streams.
- Its key purpose is to retrieve the correct audio stream URL (using an ICAO code) from LiveATC.net and play it in a Discord voice channel.
- It uses the discord.py library to interact with Discord and relies on external tools (like FFmpeg) for audio processing.

##### Analyzing the File Structure
- Top-level files (.env.example, Pipfile, requeriments.txt) and README indicate standard configuration and dependency management.
- The “bot” directory contains the core Python modules:
- bot.py: The entry point that likely initializes and runs the bot.
- config.py: Handles configuration settings, probably loading environment variables and other constants.
- embed_helper.py: Likely assists in formatting messages (embeds) sent to Discord.
- The “audio” subdirectory includes at least one stream configuration/pls file, which might be used to help determine stream URLs.
- The clear separation of modules indicates a design where distinct components (e.g., command processing, configuration, streaming) are encapsulated in their own files.

##### Main Components
- Discord Interface:
- This is your integration with the discord.py library which connects to Discord’s API.
- It involves both text commands (e.g., !radio, !reconnect) and the voice channel interactions.
- Command and Event Handlers:
- Managed in bot.py and possibly further split into dedicated modules. It interprets user commands and triggers the appropriate actions.
- Configuration Loader:
- Represented by config.py, it retrieves settings such as Discord tokens, channel IDs, and other environment-specific constants from the .env file.
- Audio Streaming Module:
- The logic that fetches the stream URL based on an ICAO code and passes the stream to FFmpeg for processing.
- It interacts with external systems: LiveATC.net for getting the stream URL and FFmpeg for handling the audio stream.
- Error Handling and Permission Checks:
- These components ensure that only authorized users can control the bot and that errors (e.g., playback issues or missing stream URLs) are appropriately handled.
- External Dependencies:
- FFmpeg for audio processing.
- The discord.py library as an abstraction over the Discord API.
- Possibly other libraries included in the Pipfile and requeriments.txt.

##### Relationships and Interactions
- User Commands (e.g., “!radio”) are received by the Discord Bot interface (bot.py) via discord.py.
- The Command Handler queries the Configuration Loader for necessary settings and then interacts with the Audio Streaming Module to fetch and process the audio stream.
- The Audio Module communicates with the LiveATC.net API (or parses the PLS file in the audio directory) to retrieve the stream URL.
- Once the stream URL is obtained, the module hands off the stream to FFmpeg (an external processing tool) to convert/process audio as needed.
- Processed audio is then sent back to the Discord voice channel.
- Throughout this flow, error handling components catch any issues (such as playback errors) and initiate appropriate responses or retries.
- Permissions are verified early in the command processing to ensure that only authorized roles/users can trigger actions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal Bot Layer
    subgraph "Internal Bot Layer"
        Bot["Discord Bot (bot.py)"]:::internal
        Conf["Configuration Loader (config.py)"]:::internal
        Embed["Embed Helper (bot/embed_helper.py)"]:::internal
        Audio["Audio Streaming Module"]:::internal
        Err["Error Handling & Permission Checks"]:::error
    end

    %% External Services
    subgraph "External Services"
        Live["LiveATC.net"]:::external
        FFmpeg["FFmpeg"]:::external
        Voice["Discord Voice Channel"]:::external
    end

    %% Entry Point
    UCI["User Command Input"]:::input

    %% Connections
    UCI -->|"triggers"| Bot
    Bot -->|"load_config"| Conf
    Bot -->|"format_messages"| Embed
    Bot -->|"process_stream"| Audio
    Audio -->|"fetch_stream"| Live
    Audio -->|"handle_audio"| FFmpeg
    FFmpeg -->|"send_audio"| Voice
    Bot -->|"verify_perms"| Err
    Audio -->|"report_errors"| Err
    Err -->|"notify"| Bot

    %% Click Events
    click Bot "https://github.com/nicoeugui/atc-discord-bot/blob/main/bot/bot.py"
    click Conf "https://github.com/nicoeugui/atc-discord-bot/blob/main/bot/config.py"
    click Embed "https://github.com/nicoeugui/atc-discord-bot/blob/main/bot/embed_helper.py"
    click Audio "https://github.com/nicoeugui/atc-discord-bot/tree/main/bot/audio"

    %% Styles
    classDef internal fill:#AEDFF7,stroke:#0A6195,stroke-width:2px;
    classDef external fill:#F7D6AE,stroke:#B45F05,stroke-width:2px;
    classDef input fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef error fill:#F8BBD0,stroke:#C2185B,stroke-width:2px;
```
