# xsota/meowgent architecture

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

- Interactive diagram: https://gitdiagram.com/xsota/meowgent
- Repository: https://github.com/xsota/meowgent

## Overview

##### Project Type and Purpose
- This is a Python-based Discord bot (“meowgent”) built as a modular backend service. It connects to Discord, processes events/messages via “cogs,” calls AI and other external services, and persists state (e.g., stamina) in Firebase. Its key features are interactive chat (LLM-powered), voice channel notifications, a stamina system, and tool integrations (web search, crypto prices, IGDB).

##### File Structure Analysis
- Top-level configs and deployment scripts:
- .env.example / .python-version / Dockerfile / docker-compose.yml / fly.toml / Procfile / pyproject.toml
- Source code under src/:
- bot.py: bot initialization & Discord client setup
- meowgent.py: core logic for LLM calls and prompt management
- cogs/: plugin modules for each feature
– chart_cog.py (ASCII charts, uses asciichart.py + graph.py)
– price_cog.py (crypto price lookup)
– events_cog.py (voice-channel join/leave notifications)
– proposal_cog.py (game proposals via IGDB?)
- Modules:
– firebase.py (state persistence for stamina, message history)
– igdb.py (game database queries)
– discord_messages_state.py (in-memory or cached state)
– tools/: utility scripts (get_current_time, task_manager, web_search)
- CI/issue templates under .github/, plus version control ignores.

##### README Insights
- Confirms core features and use of environment‐variable configuration for API keys (Discord, OpenAI, SERP).
- Deployment via fly.io and Docker, typical 12-factor app.

a. Main Components
- Discord Gateway (external service)
- Bot Application (container/service)
– Discord Client & Event Loop
– Cog Manager (loads chart, price, events, proposal cogs)
– Core Logic (meowgent.py for LLM prompts, stamina checks)
- State Store: Firebase (NoSQL)
- External APIs:
– OpenAI (LLM)
– SERP API (web_search)
– Crypto Price API (price_cog)
– IGDB API (proposal_cog)
- Utility Modules (asciichart, graph, task_manager, time service)
b. Relationships & Data Flows
1. User → Discord → Bot (bot.py)
2. Bot routes event to appropriate Cog
3. Cog may:
– Query Firebase for state/stamina
– Call meowgent.py → OpenAI for NLP response
– Call tool modules (web_search, get_current_time)
– Call external domain API (price or IGDB)
4. Bot sends response → Discord → User
5. Bot writes updated state → Firebase
c. Architectural Patterns & Principles
- Plugin/Cog pattern for separation of features
- Single-responsibility modules (each module/cog handles one domain)
- Event-driven design (Discord events trigger handlers)
- Externalize state and secrets for portability (Firebase + .env)
d. Key Technologies & Frameworks
- discord.py (Discord client)
- Python 3.12+, uv (task runner)
- Firebase SDK
- OpenAI API
- SERP API, IGDB API
- Docker & fly.io for containerized deployment

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    Discord["Discord Gateway"]:::external
    OpenAI["OpenAI API"]:::external
    SERP["SERP API (Web Search)"]:::external
    CryptoAPI["Crypto Price API"]:::external
    IGDB["IGDB API"]:::external
    Firebase["Firebase State Store"]:::datastore

    %% Bot Application Container
    subgraph "Bot Application (Docker Container)" 
        direction TB
        BC["Discord Client & Event Loop"]:::internal
        Meow["Core Logic (LLM prompts & stamina checks)"]:::internal
        subgraph "Cog Manager"
            direction TB
            Chart["Chart Cog"]:::cog
            Price["Price Cog"]:::cog
            Events["Events Cog"]:::cog
            Proposal["Proposal Cog"]:::cog
        end
        Cache["Message State Cache"]:::internal
        subgraph "Utilities"
            direction TB
            ASCII["Ascii Chart Utility"]:::util
            Graph["Graph Utilities"]:::util
            Web["Web Search Tool"]:::util
            Task["Task Manager Utility"]:::util
            Time["Time Service Utility"]:::util
        end
    end

    %% Data Flows
    Discord --> BC
    BC --> Chart
    BC --> Price
    BC --> Events
    BC --> Proposal

    Chart --> Meow
    Price --> Meow
    Events --> Meow
    Proposal --> Meow

    Meow --> OpenAI
    Chart --> ASCII
    Chart --> Graph
    Price --> CryptoAPI
    Proposal --> IGDB

    Chart --> Firebase
    Price --> Firebase
    Events --> Firebase
    Proposal --> Firebase

    Chart --> Discord
    Price --> Discord
    Events --> Discord
    Proposal --> Discord

    Cache --> Meow
    Meow --> Firebase

    %% Click Events
    click BC "https://github.com/xsota/meowgent/blob/main/src/bot.py"
    click Meow "https://github.com/xsota/meowgent/blob/main/src/meowgent.py"
    click Chart "https://github.com/xsota/meowgent/blob/main/src/cogs/chart_cog.py"
    click Price "https://github.com/xsota/meowgent/blob/main/src/cogs/price_cog.py"
    click Events "https://github.com/xsota/meowgent/blob/main/src/cogs/events_cog.py"
    click Proposal "https://github.com/xsota/meowgent/blob/main/src/cogs/proposal_cog.py"
    click Firebase "https://github.com/xsota/meowgent/blob/main/src/firebase.py"
    click Cache "https://github.com/xsota/meowgent/blob/main/src/discord_messages_state.py"
    click IGDB "https://github.com/xsota/meowgent/blob/main/src/igdb.py"
    click ASCII "https://github.com/xsota/meowgent/blob/main/src/asciichart.py"
    click Graph "https://github.com/xsota/meowgent/blob/main/src/graph.py"
    click Web "https://github.com/xsota/meowgent/blob/main/src/tools/web_search.py"
    click Task "https://github.com/xsota/meowgent/blob/main/src/tools/task_manager.py"
    click Time "https://github.com/xsota/meowgent/blob/main/src/tools/get_current_time.py"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef internal fill:#98FB98,stroke:#000,stroke-width:1px
    classDef cog fill:#90EE90,stroke:#000,stroke-width:1px
    classDef util fill:#CCFFCC,stroke:#000,stroke-width:1px
    classDef datastore fill:#FFA500,stroke:#000,stroke-width:1px
```
