# olliequ/kittybot architecture

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

- Interactive diagram: https://gitdiagram.com/olliequ/kittybot
- Repository: https://github.com/olliequ/kittybot

## Overview

##### Main Components
- Bot Core (bot.py): This is the entry point that initializes the Discord bot and ties all modules together.
- Commands Module (commands folder): Contains individual Python files that implement various slash and text commands (e.g., /ping, /fortune, /translate, etc.). Each file represents a command’s logic.
- Behaviours Module (behaviours folder): Implements background or ongoing actions that the bot performs on events (e.g., auto-assigning roles, duplicate message policing, meme repost blocking, etc.).
- Common Utilities (commons folder): Implements shared utilities such as handling message formatting, emoji caching, or any common internal logic.
- Database/State Management (db.py): Manages persistence. Although the specifics aren’t deeply detailed, this component is responsible for storing data like user stats or message counts.
- External Assets & Resources: Includes additional assets such as the JSON file (e.g., pickuplinesgalore.json in the assets folder), fonts, and images. These support the bot’s functionality and UI elements when needed.
- Environment & Configuration (e.g., .env file, pyproject.toml, Dockerfile, docker-compose.yaml): These files provide deployment and runtime configuration, including sensitive variables like bot tokens, guild IDs, and other parameters.
- Testing (tests folder): Contains the test cases that ensure functionality remains correct as the project evolves.

##### Mapping Out Relationships and Interactions
- The Bot Core in bot.py initializes the client and registers both commands and behaviours.
- When a Discord event is received (like a user command or message), control flows from the core to the relevant command module or behaviour module.
- The commands module interacts with the commons utilities to process data, generate responses, and sometimes query/update persistent data via the database component.
- The behaviours module listens to ongoing events (like message events, image uploads) and may interact with external assets (e.g., using the pickuplines JSON or interfacing with third-party APIs such as for fortunes or translations).
- Dockerfiles and docker-compose.yaml illustrate how the service is containerized and deployed in a production/cloud setting.
- The Github workflows and configuration files show continuous integration (using Black and Pyright) enforcing code style and type checking.

##### Highlighted Architectural Patterns and Design Principles
- Modularity: Clear separation of concerns where commands and behaviours are split into their own modules.
- Extensibility: The README encourages adding new commands as new Python files (e.g., placing new command files in an “extensions” folder – not shown in the file tree but suggested), facilitating team contributions.
- Configuration/Environment Separation: Use of environment variables (via .env file) ensures deployment-time separation from code logic.
- Docker-based Deployment: The Dockerfile and docker-compose.yaml indicate containerization which is useful for deployment and scaling.

##### Including Key Technologies and Libraries
- Hikari & Lightbulb: Primary libraries used for Discord interactions and command handling.
- Python 3.11: The required runtime environment.
- Docker: For containerization, as shown by Dockerfile and docker-compose files.
- External tools: The fortunes package for the /fortune command, and potentially BeautifulSoup (mentioned in further ideas) for web scraping tasks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Discord Client"]:::external
    B["Bot Core (bot.py)"]:::core
    A -->|"EventTrigger"| B

    B -->|"Registers"| C["Commands Module (commands/)"]:::commands
    B -->|"Registers"| D["Behaviours Module (behaviours/)"]:::behaviours
    
    C -->|"Uses"| E["Common Utilities (commons/)"]:::utilities
    C -->|"DataPersistence"| F["Database/State Management (db.py)"]:::database
    E -->|"QueryUpdate"| F

    D -->|"UsesAssets"| G1["assets/pickuplinesgalore.json"]:::externalAssets
    D -->|"UsesAssets"| H1["fonts/"]:::externalAssets
    D -->|"UsesAssets"| I1["images/"]:::externalAssets

    subgraph "Environment & Configuration"
        J[".example.env"]:::envConfig
        K["Dockerfile"]:::envConfig
        L["docker-compose.yaml"]:::envConfig
        M["pyproject.toml"]:::envConfig
    end
    K -->|"configures"| B
    K -->|"configures"| C
    K -->|"configures"| D

    N["Testing (tests/)"]:::testing
    N -->|"Tests"| B
    N -->|"Tests"| C
    N -->|"Tests"| E

    click B "https://github.com/olliequ/kittybot/blob/main/bot.py"
    click C "https://github.com/olliequ/kittybot/tree/main/commands/"
    click D "https://github.com/olliequ/kittybot/tree/main/behaviours/"
    click E "https://github.com/olliequ/kittybot/tree/main/commons/"
    click F "https://github.com/olliequ/kittybot/blob/main/db.py"
    click G1 "https://github.com/olliequ/kittybot/blob/main/assets/pickuplinesgalore.json"
    click H1 "https://github.com/olliequ/kittybot/tree/main/fonts/"
    click I1 "https://github.com/olliequ/kittybot/tree/main/images/"
    click J "https://github.com/olliequ/kittybot/blob/main/.example.env"
    click K "https://github.com/olliequ/kittybot/tree/main/Dockerfile"
    click L "https://github.com/olliequ/kittybot/blob/main/docker-compose.yaml"
    click M "https://github.com/olliequ/kittybot/blob/main/pyproject.toml"
    click N "https://github.com/olliequ/kittybot/tree/main/tests/"

    classDef external fill:#b3d9ff,stroke:#333,stroke-width:1px;
    classDef core fill:#ffcccb,stroke:#333,stroke-width:2px;
    classDef commands fill:#ffe680,stroke:#333,stroke-width:1px;
    classDef behaviours fill:#d9ead3,stroke:#333,stroke-width:1px;
    classDef utilities fill:#c9daf8,stroke:#333,stroke-width:1px;
    classDef database fill:#f4cccc,stroke:#333,stroke-width:1px;
    classDef externalAssets fill:#ead1dc,stroke:#333,stroke-width:1px;
    classDef envConfig fill:#fff2cc,stroke:#333,stroke-width:1px;
    classDef testing fill:#d0e0e3,stroke:#333,stroke-width:1px;
```
