# pikachutw/tails-bot architecture

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

- Interactive diagram: https://gitdiagram.com/pikachutw/tails-bot
- Repository: https://github.com/pikachutw/tails-bot

## Overview

##### Project type and purpose
- This is a single‐process, full-featured Discord bot (Node.js) named “Tails Bot,” designed to serve a community with modular commands, event listeners, and interactive components.
- It’s not microservices-based but follows a plugin-style architecture with clear separation of commands, events, interactions, data models, and utilities.

##### File structure
- Top-level files:
- index.js: entry point
- config.js, version.js, pm2.config.js: configuration & process management
- package.json, .eslintrc.js, .gitignore, .vscode: toolchain
- Directories:
- commands/: command modules grouped by domain (economy, information, message, misc, mission, moderator, phase1, system, tool)
- events/: raw Discord event handlers
- interactions/: button, context, modal, select, slash handlers
- models/: Mongoose schemas for persistent data
- modules/: shared utilities (Logger, canvas, generic functions)
- assets (fonts/, images/, 7000words/…): static resources

##### Key insights from README
- It’s an open-source, community-oriented bot supporting many commands.

##### Main components
a. External Service
- Discord Gateway & REST API
b. Bot Core (Node.js runtime)
- Entry Point (index.js)
- Configuration (config.js)
- Process Manager (PM2)
c. Handlers
- Event Handler (events/*.js)
- Command Handler (commands/**/*.js)
- Interaction Handler (interactions/**/*.js)
d. Business Logic Modules (modules/*.js)
e. Data Layer
- Models (models/*.js) – MongoDB via Mongoose
f. Static Assets
- Fonts, images, JSON word lists
g. Logging & Monitoring
- modules/Logger.js, pm2 logs

##### Relationships & data flow
1. Discord client → Gateway → Bot Core
2. Bot Core routes incoming payloads →
- events handler → modules → models → DB → respond via Discord API
- command handler → modules → models → DB → respond via Discord API
- interaction handler → modules → models → DB → respond via Discord API
3. Modules encapsulate reusable logic (e.g., Canvas drawing, generic helpers)
4. Mongoose models persist and retrieve data from MongoDB
5. Bot logs events & errors via Logger → stdout/PM2

##### Architectural patterns & principles
- Plugin Architecture: each command or interaction is a self-contained module
- Separation of Concerns: handlers (events/commands/interactions), business logic (modules), data layer (models)
- Utility Layer: shared code in modules/
- Resilience & Monitoring: PM2 for process management, Logger for audit

##### Technologies & frameworks
- Node.js, discord.js (implied)
- MongoDB with Mongoose
- PM2 for deployment
- ESLint, VSCode settings for development
- Canvas (modules/canvas.js) for image generation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: External Service
    DiscordAPI["Discord API & Gateway"]:::external

    %% Layer 2: Bot Core
    subgraph "Bot Core (Node.js Runtime)" 
        direction TB
        Entry["Entry Point\nindex.js"]:::core
        Config["Configuration\nconfig.js"]:::core
        Version["Version Info\nversion.js"]:::core
        PM2["Process Manager\npm2.config.js"]:::core
    end

    %% Layer 3: Handlers
    subgraph "Handlers"
        direction TB
        Events["Event Handler\n(events/)"]:::handler
        Commands["Command Handler\n(commands/)"]:::handler
        Interactions["Interaction Handler\n(interactions/)"]:::handler
    end

    %% Layer 4: Logic & Data
    subgraph "Business Logic & Data Layer"
        direction TB
        Modules["Utilities\n(modules/)"]:::util
        Models["Data Models\n(models/)"]:::db
        MongoDB["MongoDB"]:::db
    end

    %% Layer 5: Static Assets
    Static["Static Assets\n(fonts/, images/, 7000words/)"]:::static

    %% Layer 6: Logging & Monitoring
    Logging["Logging & Monitoring\n(modules/Logger.js, PM2 logs)"]:::logging

    %% Connections
    DiscordAPI -->|"Incoming Events"| Entry
    Entry --> Config
    Entry --> Version
    Entry --> PM2

    Entry -->|"Route Payloads"| Events
    Entry -->|"Route Payloads"| Commands
    Entry -->|"Route Payloads"| Interactions

    Events -->|"Uses Utilities"| Modules
    Commands -->|"Uses Utilities"| Modules
    Interactions -->|"Uses Utilities"| Modules

    Events -->|"Reads/Writes"| Models
    Commands -->|"Reads/Writes"| Models
    Interactions -->|"Reads/Writes"| Models

    Models --> MongoDB
    Modules --> MongoDB

    Modules --> Static
    Modules --> Logging
    Events --> Logging
    Commands --> Logging
    Interactions --> Logging

    Entry -->|"Outgoing Responses"| DiscordAPI

    %% Click Events for component mapping
    click Entry "https://github.com/pikachutw/tails-bot/blob/main/index.js"
    click Config "https://github.com/pikachutw/tails-bot/blob/main/config.js"
    click Version "https://github.com/pikachutw/tails-bot/blob/main/version.js"
    click PM2 "https://github.com/pikachutw/tails-bot/blob/main/pm2.config.js"
    click Commands "https://github.com/pikachutw/tails-bot/tree/main/commands/"
    click Events "https://github.com/pikachutw/tails-bot/tree/main/events/"
    click Interactions "https://github.com/pikachutw/tails-bot/tree/main/interactions/"
    click Modules "https://github.com/pikachutw/tails-bot/tree/main/modules/"
    click Models "https://github.com/pikachutw/tails-bot/tree/main/models/"
    click Static "https://github.com/pikachutw/tails-bot/tree/main/fonts/"
    click Logging "https://github.com/pikachutw/tails-bot/blob/main/modules/Logger.js"

    %% Styles
    classDef external fill:#add8e6,stroke:#333,stroke-width:1px
    classDef core fill:#90ee90,stroke:#333,stroke-width:1px
    classDef handler fill:#98fb98,stroke:#333,stroke-width:1px
    classDef util fill:#ffffe0,stroke:#333,stroke-width:1px
    classDef db fill:#ffa500,stroke:#333,stroke-width:1px
    classDef static fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef logging fill:#ffdead,stroke:#333,stroke-width:1px
```
