# s0ca/lambda-bot architecture

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

- Interactive diagram: https://gitdiagram.com/s0ca/lambda-bot
- Repository: https://github.com/s0ca/lambda-bot

## Overview

##### Project type and purpose
- Lambda-Bot is a self-hostable, modular Discord bot written in Python.
- It employs a “cog” (plugin) system: each file in the `cogs/` folder encapsulates one feature (music, notes, quiz, etc.).
- It persists state to a local SQLite database and various JSON files, and it even ships with a small static web tool to generate quiz content.

##### File structure
Top-level files and folders:
- `.env.sample` & `settings.py`: configuration placeholders and environment variables (BOT_TOKEN, ADMIN_ROLE_NAME, etc.)
- `LambdaBot.py`: main entry point—initializes bot, loads cogs, connects to Discord
- `cogs/`: individual feature modules (administration.py, music.py, quiz.py, etc.)
- `init_db.py`: script to create the SQLite schema for the notes plugin
- `custom_commands.json`, `magic.json`: file-based storage for custom commands and “magic” responses
- `data/quiz/`: directory of quiz data JSON files
- `playlists/`: user-managed playlist files for the music plugin
- `quiz_editor.py` & `tool/quiz_generator/`: a small static web UI (HTML/CSS/JS) to create quiz JSON
- `requirements.txt`: Python dependencies (discord.py, sqlite3, etc.)

##### README for additional insights
- Confirms Python 3.6+, sqlite3, and plugin-based extensibility.
- Instructions on cloning, dependency installation, DB initialization, environment config, and running.
- Mentions future plans: Docker image, improved rights management, more cogs.

##### Final advice
- Every folder/file group as a logical component.
- Be granular but not overwhelming: group similar cogs if necessary (e.g., all utility cogs together).
- Dynamic behavior (e.g., plugin loading, DB schema init) with notes or legends.
- Keep it up to date whenever new cogs or tools are added.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    subgraph "External Services"
        direction TB
        Discord["Discord Gateway & REST API"]:::external
        Voice["Discord Voice Channel"]:::external
        ExternalMedia["External Media Source / ffmpeg"]:::external
    end

    %% Core System
    subgraph "Bot Core"
        direction TB
        LambdaBot["LambdaBot.py"]:::core
        Settings["settings.py"]:::core
        EnvSample[".env.sample"]:::core
    end

    %% Plugin Modules
    subgraph "Cog Modules"
        direction TB
        CogsDir["cogs/"]:::cogs
        Administration["Administration Cog"]:::cogs
        Cipher["Cipher Cog"]:::cogs
        Encoding["Encoding Cog"]:::cogs
        Music["Music Cog"]:::cogs
        Notes["Notes Cog"]:::cogs
        Pilouface["Pilouface Cog"]:::cogs
        Punchline["Punchline Cog"]:::cogs
        QuizCog["Quiz Cog"]:::cogs
        Utility["Utility Cog"]:::cogs
        Warn["Warn Cog"]:::cogs
    end

    %% Data Storage
    subgraph "Data Storage"
        direction TB
        SQLiteDB[(SQLite Database)]:::storage
        InitDB["init_db.py"]:::storage
        CustomCommands[(custom_commands.json)]:::storage
        MagicResponses[(magic.json)]:::storage
        QuizDataDir["data/quiz/"]:::storage
        PlaylistsDir["playlists/"]:::storage
    end

    %% Static Web Tool
    subgraph "Quiz Generator Web Tool"
        direction TB
        QuizEditorScript["quiz_editor.py"]:::webtool
        WebIndex["index.html"]:::webtool
        WebScript["script.js"]:::webtool
        WebStyle["style.css"]:::webtool
    end

    %% Dependencies
    Requirements["requirements.txt"]:::core

    %% Connections
    Discord -->|connects to| LambdaBot
    LambdaBot -->|loads| CogsDir
    LambdaBot -->|loads| Settings
    LambdaBot -->|loads| EnvSample
    LambdaBot -->|uses| Requirements

    CogsDir --> Administration
    CogsDir --> Cipher
    CogsDir --> Encoding
    CogsDir --> Music
    CogsDir --> Notes
    CogsDir --> Pilouface
    CogsDir --> Punchline
    CogsDir --> QuizCog
    CogsDir --> Utility
    CogsDir --> Warn

    Administration -->|reads/writes| CustomCommands
    Cipher -->|reads/writes| MagicResponses
    Notes -->|reads/writes| SQLiteDB
    Notes -->|initialized by| InitDB
    QuizCog -->|loads| QuizDataDir
    Music -->|reads| PlaylistsDir

    Music -->|streams via| ExternalMedia
    ExternalMedia -->|outputs to| Voice

    QuizEditorScript -->|exports to| QuizDataDir
    WebIndex -->|part of| QuizGenerator
    WebScript -->|part of| QuizGenerator
    WebStyle -->|part of| QuizGenerator

    QuizEditorScript -->|uses| WebIndex
    QuizEditorScript -->|uses| WebScript
    QuizEditorScript -->|uses| WebStyle

    %% Click Events
    click LambdaBot "https://github.com/s0ca/lambda-bot/blob/main/LambdaBot.py"
    click Settings "https://github.com/s0ca/lambda-bot/blob/main/settings.py"
    click EnvSample "https://github.com/s0ca/lambda-bot/blob/main/.env.sample"
    click CogsDir "https://github.com/s0ca/lambda-bot/tree/main/cogs/"
    click Administration "https://github.com/s0ca/lambda-bot/blob/main/cogs/administration.py"
    click Cipher "https://github.com/s0ca/lambda-bot/blob/main/cogs/cipher.py"
    click Encoding "https://github.com/s0ca/lambda-bot/blob/main/cogs/encoding.py"
    click Music "https://github.com/s0ca/lambda-bot/blob/main/cogs/music.py"
    click Notes "https://github.com/s0ca/lambda-bot/blob/main/cogs/notes.py"
    click Pilouface "https://github.com/s0ca/lambda-bot/blob/main/cogs/pilouface.py"
    click Punchline "https://github.com/s0ca/lambda-bot/blob/main/cogs/punchline.py"
    click QuizCog "https://github.com/s0ca/lambda-bot/blob/main/cogs/quiz.py"
    click Utility "https://github.com/s0ca/lambda-bot/blob/main/cogs/utility.py"
    click Warn "https://github.com/s0ca/lambda-bot/blob/main/cogs/warn.py"
    click InitDB "https://github.com/s0ca/lambda-bot/blob/main/init_db.py"
    click CustomCommands "https://github.com/s0ca/lambda-bot/blob/main/custom_commands.json"
    click MagicResponses "https://github.com/s0ca/lambda-bot/blob/main/magic.json"
    click QuizDataDir "https://github.com/s0ca/lambda-bot/tree/main/data/quiz/"
    click PlaylistsDir "https://github.com/s0ca/lambda-bot/tree/main/playlists/"
    click QuizEditorScript "https://github.com/s0ca/lambda-bot/blob/main/quiz_editor.py"
    click WebIndex "https://github.com/s0ca/lambda-bot/blob/main/tool/quiz_generator/index.html"
    click WebScript "https://github.com/s0ca/lambda-bot/blob/main/tool/quiz_generator/script.js"
    click WebStyle "https://github.com/s0ca/lambda-bot/blob/main/tool/quiz_generator/style.css"
    click Requirements "https://github.com/s0ca/lambda-bot/blob/main/requirements.txt"

    %% Styles
    classDef core fill:#D0E6FA,stroke:#0366D6,color:#0366D6
    classDef cogs fill:#E6F4EA,stroke:#2F8F2F,color:#2F8F2F
    classDef storage fill:#FFE5B4,stroke:#E68A00,color:#E68A00
    classDef external fill:#F3E6FF,stroke:#8A2BE2,color:#8A2BE2
    classDef webtool fill:#FFF5CC,stroke:#D4AF37,color:#D4AF37
```
