# matt-the-thew/andy-ai architecture

> Architecture diagram of the GitHub repository matt-the-thew/andy-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/matt-the-thew/andy-ai
- Repository: https://github.com/matt-the-thew/andy-ai

## Overview

##### Project type and purpose
- This is a full-stack (single-process) Discord bot written in Python.
- Purpose: listen for user mentions/commands in Discord, forward them to OpenAI’s GPT-4 model, apply caching, rate limiting, and logging, and send back a concise response.

##### File structure
- Entry point: main.py (initializes the bot, loads config, cogs, and runs the event loop).
- cogs/ (Discord “cogs”—modular event handlers):
- message_handler.py: receives and parses Discord messages, extracts user input.
- services/:
- llm_service.py: encapsulates all interaction with OpenAI’s API (ask, retry, cache lookup).
- utils/:
- cache.py: in-memory TTL cache
- rate_limit.py: per-user and per-guild limiter
- logger.py: structured logger with file rotation
- config/:
- settings.py: loads environment variables into a Config object
- tests/: unit tests for LLMService and utils.
- start.sh, requirements.txt: deployment scripts and dependencies.

##### README for additional insights
- Architectural patterns:
- Modular “cogs” (plug-in handlers)
- Service layer for external API
- Cross-cutting concerns (logging, caching, rate limiting) factored into utils
- Runtime dependencies: Discord API, OpenAI API

a. Main components:
1. Discord Gateway (external)
2. Bot Process (Python):
- Config Loader (settings.py)
- Main Controller (main.py)
- MessageHandler Cog
- LLMService
- Utilities (Cache, RateLimiter, Logger)
3. OpenAI API (external)
b. Relationships and interactions:
- Discord Gateway → (websocket events) → Main Controller → MessageHandler
- MessageHandler → (calls) → RateLimiter → allows or blocks request
- If allowed: MessageHandler → LLMService.ask
- LLMService.ask → (checks) → Cache
- Hit → returns cached response
- Miss → calls OpenAI API (with retry/backoff) → stores result in Cache
- LLMService → returns text → MessageHandler → sends message back via Discord API
- All steps use Logger to emit structured logs
- Config is globally accessible to all modules
c. Architectural patterns & design principles:
- Separation of concerns:
- Cogs for Discord events
- Service layer for external API
- Utils for cross-cutting
- Dependency inversion: modules depend on abstractions (e.g., Config, Logger)
- Single process, asynchronous event-driven architecture (Discord.py)
d. Key technologies/frameworks:
- discord.py (or similar) for Discord Gateway
- OpenAI Python SDK (requests under the hood)
- Python’s asyncio event loop
- In-memory cache (dict + TTL)
- Pytest for tests
- dotenv/envvars for configuration

##### Elements
- Clear labels for each component (e.g., “MessageHandler Cog,” “LLMService,” “Cache”)
- Discord → MessageHandler → LLMService → OpenAI → LLMService → MessageHandler → Discord
- Clouds for external services (Discord, OpenAI)
- Rectangles for internal modules

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Systems"
        Discord((Discord Gateway)):::external
        OpenAI((OpenAI API)):::external
    end

    subgraph "Bot Process"
        Main["Main Controller"]:::controller
        subgraph "Config Layer"
            Config["Config Loader"]:::config
        end
        subgraph "Presentation/Event Layer"
            MH["MessageHandler Cog"]:::event
        end
        subgraph "Business Logic Layer"
            LLM["LLMService"]:::service
        end
        subgraph "Cross-Cutting Layer"
            Cache["Cache (TTL 3600s)"]:::cache
            RL["Rate Limiter"]:::rate
            Logger["Logger (bot.log, rotation)"]:::log
        end
    end

    subgraph "Supporting Files"
        start["start.sh"]:::script
        req["requirements.txt"]:::script
        t1["tests/test_llm_service.py"]:::test
        t2["tests/test_utils.py"]:::test
    end

    Discord -->|"websocket events"| MH
    MH -->|checks| RL
    MH -->|"message text"| LLM
    LLM -->|checks cache| Cache
    Cache -->|hit| LLM
    Cache -->|miss| LLM
    LLM -->|"REST (retry/backoff)"| OpenAI
    OpenAI -->|"response"| LLM
    LLM -->|"text response"| MH
    MH -->|"send message"| Discord

    Main --> Config
    Main --> MH
    Main --> LLM
    Main --> Cache
    Main --> RL
    Main --> Logger

    Config --> MH
    Config --> LLM
    Config --> Cache
    Config --> RL
    Config --> Logger

    MH --> Logger
    LLM --> Logger
    RL --> Logger
    Cache --> Logger

    click Config "https://github.com/matt-the-thew/andy-ai/blob/main/config/settings.py"
    click Main "https://github.com/matt-the-thew/andy-ai/blob/main/main.py"
    click MH "https://github.com/matt-the-thew/andy-ai/blob/main/cogs/message_handler.py"
    click LLM "https://github.com/matt-the-thew/andy-ai/blob/main/services/llm_service.py"
    click Cache "https://github.com/matt-the-thew/andy-ai/blob/main/utils/cache.py"
    click RL "https://github.com/matt-the-thew/andy-ai/blob/main/utils/rate_limit.py"
    click Logger "https://github.com/matt-the-thew/andy-ai/blob/main/utils/logger.py"
    click start "https://github.com/matt-the-thew/andy-ai/blob/main/start.sh"
    click req "https://github.com/matt-the-thew/andy-ai/blob/main/requirements.txt"
    click t1 "https://github.com/matt-the-thew/andy-ai/blob/main/tests/test_llm_service.py"
    click t2 "https://github.com/matt-the-thew/andy-ai/blob/main/tests/test_utils.py"

    classDef external fill:#B3E5FC,stroke:#0277BD,color:#01579B;
    classDef controller fill:#E1BEE7,stroke:#6A1B9A,color:#4A148C;
    classDef config fill:#FFF9C4,stroke:#F9A825,color:#F57F17;
    classDef event fill:#C8E6C9,stroke:#388E3C,color:#1B5E20;
    classDef service fill:#FFE0B2,stroke:#FB8C00,color:#E65100;
    classDef cache fill:#E0E0E0,stroke:#616161,color:#212121;
    classDef rate fill:#E0E0E0,stroke:#616161,color:#212121;
    classDef log fill:#E0E0E0,stroke:#616161,color:#212121;
    classDef script fill:#F8BBD0,stroke:#C2185B,color:#880E4F;
    classDef test fill:#B2EBF2,stroke:#0097A7,color:#006064;
```
