# tanisjam/eradrin-bot architecture

> Architecture diagram of the GitHub repository tanisjam/eradrin-bot, 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/tanisjam/eradrin-bot
- Repository: https://github.com/tanisjam/eradrin-bot

## Overview

##### Main Components
- Discord Bot Client: At the heart of the system lies the Discord client that connects to Discord’s API, listens for events, and dispatches commands.
- Command Handlers: The bot’s functionality is modularized into individual commands. In the file tree, the src/commands directory contains commands such as /ask, /character, /ping, /roll, /rollstats, etc.
- AI Integration Service: The src/ai-model.ts along with related configuration (in src/config.ts) handles the integration with the Gemini AI API to provide chatbot capabilities.
- External API Integration – Nivel20: The bot provides links and character lookups for Nivel20, and there is a dedicated service (src/services/nivel20.service.ts) to interact with the Nivel20 site.
- Dice Rolling and Stat Generation: Commands like /roll and /rollstats utilize internal or external libraries (e.g., RPG Dice Roller mentioned in the README) to process game mechanics.
- Database Layer: The presence of database.sqlite and the src/database folder (which holds configuration and models including Character, User, PingHistory, etc.) indicates that the bot tracks user interactions or maintains state/history.
- Utility Modules: Helper functions and utilities (e.g., discord.utils.ts, format-text.ts) to process data and ensure clean separation of concerns.

##### Relationships and Interactions
- The Discord Bot Client (src/bot.ts and src/index.ts) acts as the entry point, and it routes user interactions to the specific command handlers found in src/commands.
- Commands like /ask are connected to the AI integration service (src/ai-model.ts) where user input is sent to the Gemini API.
- The /character command interacts with the Nivel20 service (src/services/nivel20.service.ts) to provide direct links or search results.
- Dice rolling and stat generation commands may use both in-house logic and third-party libraries (integrated via package.json), representing another module in the system.
- Data persistence is handled via a SQLite database, and models in the src/database/models represent the schema for various entities.
- The configuration module (src/config.ts) along with environment files (.env) ensure that essential variables like Discord tokens and API keys are maintained securely.
- Utility modules provide cross-cutting functionality to various components.

##### Highlighting Architectural Patterns and Design Principles
- Modular Design: Each command or functionality is separated into its own file/folder, which is a clean separation of concerns.
- Service Layer Abstraction: There is a clear distinction between command handling and the underlying services (e.g., nivel20.service.ts, Character.service.ts) that abstract the integration with external APIs and business logic.
- MVC/Multi-layered Approach: Even if loosely applied, the separation of command controllers (presentation), services (business logic), and database models (data access) mimics common layered approaches.
- Containerization: The Dockerfile and docker-compose file indicate a microservices-friendly, containerized deployment environment.

##### Final Steps
- Expand each module so that each command (e.g., /ask, /roll, /character) is detailed with its dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    BotClient["Discord Bot Client"]:::client
    Config["Configuration"]:::config
    AIService["AI Integration Service (Gemini API)"]:::service
    Nivel20Service["Nivel20 Integration Service"]:::service
    DiceModule["Dice Rolling Module"]:::service
    Database["Database (SQLite & Models)"]:::db
    Utilities["Utility Modules"]:::util
    Deployment["Deployment/Configuration"]:::deployment
    GeminiAPI["Gemini AI API (External)"]:::external
    Nivel20Site["Nivel20 Site (External)"]:::external

    subgraph "Command Handlers"
        AskCmd["/ask Command"]:::handlers
        CharacterCmd["/character Command"]:::handlers
        RollCmd["/roll Command"]:::handlers
        RollStatsCmd["/rollstats Command"]:::handlers
        PingCmd["/ping Command"]:::handlers
    end

    %% Connections from Bot Client to Commands
    BotClient -->|"triggers"| AskCmd
    BotClient -->|"triggers"| CharacterCmd
    BotClient -->|"triggers"| RollCmd
    BotClient -->|"triggers"| RollStatsCmd
    BotClient -->|"triggers"| PingCmd

    %% Command interactions with services
    AskCmd -->|"calls"| AIService
    CharacterCmd -->|"calls"| Nivel20Service
    RollCmd -->|"invokes"| DiceModule
    RollStatsCmd -->|"invokes"| DiceModule
    PingCmd -->|"logs"| Database

    %% Service external API calls
    AIService -->|"queries"| GeminiAPI
    Nivel20Service -->|"requests"| Nivel20Site

    %% Services and modules dependencies
    AIService -->|"uses"| Config
    BotClient -->|"utilizes"| Utilities

    %% Commands also interact with the Database
    CharacterCmd -->|"reads/writes"| Database

    %% Deployment provides configuration and deployment
    Deployment -->|"deploys"| BotClient
    Deployment -->|"deploys"| AIService
    Deployment -->|"deploys"| Nivel20Service
    Deployment -->|"deploys"| Database
    Deployment -->|"provides"| Config

    %% Click Events
    click BotClient "https://github.com/tanisjam/eradrin-bot/blob/main/src/bot.ts, src/index.ts"
    click AskCmd "https://github.com/tanisjam/eradrin-bot/blob/main/src/commands/ask.ts"
    click CharacterCmd "https://github.com/tanisjam/eradrin-bot/blob/main/src/commands/character.ts"
    click RollCmd "https://github.com/tanisjam/eradrin-bot/blob/main/src/commands/roll.ts"
    click RollStatsCmd "https://github.com/tanisjam/eradrin-bot/blob/main/src/commands/rollstats.ts"
    click PingCmd "https://github.com/tanisjam/eradrin-bot/blob/main/src/commands/ping.ts"
    click AIService "https://github.com/tanisjam/eradrin-bot/blob/main/src/ai-model.ts"
    click Config "https://github.com/tanisjam/eradrin-bot/blob/main/src/config.ts"
    click Nivel20Service "https://github.com/tanisjam/eradrin-bot/blob/main/src/services/nivel20.service.ts, src/models/nivel20response.ts"
    click DiceModule "https://github.com/tanisjam/eradrin-bot/blob/main/src/commands/roll.ts, src/commands/rollstats.ts"
    click Database "https://github.com/tanisjam/eradrin-bot/tree/main/database.sqlite, src/database"
    click Utilities "https://github.com/tanisjam/eradrin-bot/blob/main/src/utils/discord.utils.ts, src/utils/format-text.ts"
    click Deployment "https://github.com/tanisjam/eradrin-bot/blob/main/Dockerfile, docker-compose.yaml, .env.example, tsconfig.json"

    %% Class definitions for styling
    classDef client fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef handlers fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef service fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef db fill:#d1ecf1,stroke:#333,stroke-width:2px;
    classDef util fill:#e2e3e5,stroke:#333,stroke-width:2px;
    classDef config fill:#fefefe,stroke:#333,stroke-width:2px;
    classDef deployment fill:#f5c6cb,stroke:#333,stroke-width:2px;
```
