# staciax/lattebot architecture

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

- Interactive diagram: https://gitdiagram.com/staciax/lattebot
- Repository: https://github.com/staciax/lattebot

## Overview

##### Project Type and Purpose
- Lattebot is a single‐service backend application: a Python‐based Discord bot. It connects to the Discord Gateway, listens for events (messages, interactions), and responds via commands and UI components. It uses a plugin‑style architecture (“cogs”) for modular features.

##### File‐Structure Analysis
- Top‑level scripts:
- pre_start.py – syncs slash commands to Discord (one‐time setup).
- launcher.py – entry point to start the bot.
- Configuration:
- .env.example → .env file for environment variables (Discord token, etc.).
- pyproject.toml, Makefile, Dockerfile, docker-compose.yaml – build/deploy scripts.
- Core application (“lattebot” package):
- core/ – bot bootstrap, configuration loader, translation, command tree management.
- cogs/ – feature modules, grouped by domain (about, admin, events, help, custom jsk/test cogs).
- ui/ – Discord UI abstraction (views, modals).
- chat_formatting.py, embeds.py, utils.py, logging.py – shared utilities.
- Tests/ – pytest tests for core components.

##### Key Components
a. External Services
- Discord Gateway & REST API
- (Optional) Docker host or local machine environment
b. Scripts & Processes
- pre_start.py (Command Synchronization)
- launcher.py → Bot Process
c. Bot Process Internals
- Core Layer
– Bot bootstrap (bot.py)
– Config loader (config.py)
– Translator/localization (translator.py + locales)
– Command tree manager (tree.py)
- Cogs Layer
– Individual modules (about, admin, events, help, custom)
– Each implements event handlers and slash/app commands
- UI Layer
– Modal & View abstractions
- Shared Utils
– Chat formatting, embeds, logging, general utilities

##### Component Interactions and Data Flow
- pre_start.py reads .env → authenticates with Discord REST → syncs slash commands
- launcher.py reads .env → instantiates Bot (core.bot) → connects to Discord Gateway
- Discord Gateway → emits events (messages, interactions) → Bot dispatch → Cog handlers
- Cog handlers → make internal calls to core utilities (translator, chat_formatting, embeds)
- UI interactions (modals, button clicks) → UI.View / UI.Modal classes → dispatched back to bot
- Bot → sends responses via Discord REST through the Gateway connection
- Logging component captures each step and writes to console/file

##### Architectural Patterns & Principles
- Plugin‑style modularity: each “cog” is a self‑contained feature
- Separation of concerns: core bootstrapping/config, cogs for commands/events, ui for interactive elements, utils for shared logic
- Twelve‑factor app principles: environment configuration via .env, stateless service

##### Technologies & Frameworks
- Python 3.13+
- uv (Astral’s task runner) for script execution
- discord.py or fork (implicitly used by core.bot)
- pytest for testing
- Docker & docker-compose for containerized deployment

##### Essential Elements
- Config loading once at startup, feeding into all subsystems.
- Translator/locales feeding into cogs or utilities that need localization.
- Scripts (pre_start, launcher) as separate entry‑point nodes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Entry Scripts"
        PRE["pre_start.py"]:::script
        LCH["launcher.py"]:::script
    end

    ENV[".env"]:::config

    PRE -->|"reads .env"| ENV
    LCH -->|"reads .env"| ENV

    PRE -->|"Slash Command Sync"| DISCORD["Discord API/Gateway"]:::external
    LCH -->|"start Bot"| BOT["Bot Process"]:::core

    ENV -->|"ENV Vars"| CFG["Config Loader"]:::core
    CFG --> BOT

    subgraph "Bot Process Internals"
        BOT_CORE["Bot Bootstrap"]:::core
        TRANS["Translator/Localization"]:::core
        TREE["Command Tree Manager"]:::core
        COG_BASE["Cog Base Class"]:::core

        BOT --> BOT_CORE
        BOT_CORE --> CFG
        BOT_CORE --> TRANS
        BOT_CORE --> TREE
        BOT_CORE --> COG_BASE

        subgraph "Cogs (Plugins)"
            ABOUT["About Cog"]:::cogs
            ADMIN["Admin Cog"]:::cogs
            EVENTS["Events Cog"]:::cogs
            HELP["Help Cog"]:::cogs
            JSK["JSK Custom Cog"]:::cogs
            TESTCOG["Test Cog"]:::cogs
        end

        BOT -->|"dispatch events"| ABOUT
        BOT -->|"dispatch events"| ADMIN
        BOT -->|"dispatch events"| EVENTS
        BOT -->|"dispatch events"| HELP
        BOT -->|"dispatch events"| JSK
        BOT -->|"dispatch events"| TESTCOG

        subgraph "UI Components"
            MODAL["Modal Abstraction"]:::ui
            VIEW["View Abstraction"]:::ui
        end

        BOT -->|"UI Interactions"| MODAL
        BOT -->|"UI Interactions"| VIEW
        MODAL --> BOT
        VIEW --> BOT

        subgraph "Shared Utilities"
            CHAT["Chat Formatting"]:::utils
            EMBED["Embeds Builder"]:::utils
            LOGGING["Logging Setup"]:::utils
            UTIL["General Utilities"]:::utils
            CHECKS["Command Checks"]:::utils
        end

        ABOUT --> CHAT
        ADMIN --> LOGGING
        EVENTS --> UTIL
        HELP --> EMBED
        HELP --> UTIL
        JSK --> UTIL
        TESTCOG --> UTIL
    end

    DISCORD -->|"Event Dispatch"| BOT
    BOT -->|"Responses"| DISCORD

    click PRE "https://github.com/staciax/lattebot/blob/master/pre_start.py"
    click LCH "https://github.com/staciax/lattebot/blob/master/launcher.py"
    click BOT_CORE "https://github.com/staciax/lattebot/blob/master/lattebot/core/bot.py"
    click CFG "https://github.com/staciax/lattebot/blob/master/lattebot/core/config.py"
    click TRANS "https://github.com/staciax/lattebot/blob/master/lattebot/core/translator.py"
    click TREE "https://github.com/staciax/lattebot/blob/master/lattebot/core/tree.py"
    click COG_BASE "https://github.com/staciax/lattebot/blob/master/lattebot/core/cog.py"
    click ABOUT "https://github.com/staciax/lattebot/blob/master/lattebot/cogs/about/main.py"
    click ADMIN "https://github.com/staciax/lattebot/blob/master/lattebot/cogs/admin/main.py"
    click EVENTS "https://github.com/staciax/lattebot/blob/master/lattebot/cogs/events/main.py"
    click HELP "https://github.com/staciax/lattebot/blob/master/lattebot/cogs/help/main.py"
    click JSK "https://github.com/staciax/lattebot/blob/master/lattebot/cogs/jsk.py"
    click TESTCOG "https://github.com/staciax/lattebot/blob/master/lattebot/cogs/test.py"
    click MODAL "https://github.com/staciax/lattebot/blob/master/lattebot/ui/modal.py"
    click VIEW "https://github.com/staciax/lattebot/blob/master/lattebot/ui/view.py"
    click CHAT "https://github.com/staciax/lattebot/blob/master/lattebot/chat_formatting.py"
    click EMBED "https://github.com/staciax/lattebot/blob/master/lattebot/embeds.py"
    click LOGGING "https://github.com/staciax/lattebot/blob/master/lattebot/logging.py"
    click UTIL "https://github.com/staciax/lattebot/blob/master/lattebot/utils.py"
    click CHECKS "https://github.com/staciax/lattebot/blob/master/lattebot/checks.py"

    classDef core fill:#f9f,stroke:#333,stroke-width:1px
    classDef cogs fill:#9f9,stroke:#333,stroke-width:1px
    classDef ui fill:#99f,stroke:#333,stroke-width:1px
    classDef utils fill:#ff9,stroke:#333,stroke-width:1px
    classDef external fill:#f99,stroke:#333,stroke-width:1px
    classDef script fill:#9ff,stroke:#333,stroke-width:1px
    classDef config fill:#ccc,stroke:#333,stroke-width:1px
```
