# discord/airhornbot architecture

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

## Overview

- Bot Service:
- Discord Integration: Include subcomponents such as command handlers (e.g., SoundboardCommand, InviteCommand, StatsCommand), listeners (e.g., ReadyListener, ShardListener, InteractionCreateListener), and Discord-specific utilities.
- Routes/API: Show the API routes (e.g., ApiAdminRouter, ApiEventsRoute, and the admin API controllers under bot/src/routes/api/admin) used for administrative interactions and possibly data updates.
- Sound Management: Represent the sound resources (organized under bot/sounds) and utilities related to audio playback (e.g., AirhornAudio in utils) that the bot uses to play sound effects.
- Database Layer: Represent the Prisma integration (under bot/prisma with migrations and schema) that uses Postgres as the backend datastore.
- Website Frontend:
- UI Components: Include components such as AirhornCounter, StatsPanel, various islands (IslandDoubleTree, IslandForest, etc.) and others that build the user interface.
- State Management & Actions: Show the stores (AirhornStatsStore, OAuthStore, ResponsiveStore, ShareStore) which manage the app state and the actions (OAuthActions, StatsActions, ResponsiveActions, ShareActions) that handle events and data flow.
- Assets: Illustrate static assets like images, audio files, and videos that are part of the interface.
- Shared or Supporting Services:
- CI/CD Pipelines: Although not part of the runtime system, include a note or a separate section for the automated deployment workflows (in .github/workflows) that ensure continuous integration and deployment for both parts.
- Deployment & Configuration: Briefly note the environment configuration files (.env.example) and build tools/configurations (Webpack in the website, tsconfig.json for both parts).

##### Relationships and Interactions
- The Bot Service communicates with Discord (external service) and listens for events/interactions.
- The Bot processes commands, which might trigger routes/API endpoints that interact with the database.
- The Website Frontend communicates with the Bot’s API endpoints (if applicable) to fetch or display stats.
- Both Bot and Website depend on environment configurations and build processes for deployment.
- Interactions from the Discord API into the Bot’s command and listener layers. Then connect the command processing modules to utility modules (for audio, etc.), and further down to the database layer (via Prisma).

##### Architectural Patterns and Technical Stack
- Modular separation between the Discord bot functionalities (commands, events, routes) and the frontend website.
- Use of frameworks and tools: TypeScript throughout the project; Prisma as the ORM for database interactions; and modern web development tooling (Webpack, Babel, and a component-based UI library likely using React).
- The file structure (folders for routes, commands, listeners, and components) suggests an organizational pattern that promotes separation of concerns and modularity.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    Discord_API["Discord API"]:::external
    Postgres["Postgres Database"]:::external

    %% Bot Service
    subgraph "Bot Service"
        %% Discord Integration
        subgraph "Discord Integration"
            Bot_Commands["Commands"]:::bot
            Bot_Listeners["Listeners"]:::bot
            Bot_Types["Discord Types"]:::bot
            Bot_Buttons["Discord Buttons"]:::bot
        end

        %% API / Routes
        subgraph "API / Routes"
            Bot_API["Primary API Routes"]:::bot
            Bot_Admin["Admin API Controllers"]:::bot
        end

        %% Sound Management
        subgraph "Sound Management"
            Bot_Sounds["Sound Files"]:::bot
            Bot_Audio["Sound Playback Utilities"]:::bot
        end

        %% Database Layer
        subgraph "Database Layer"
            Bot_Prism["Prisma Integration"]:::bot
        end
    end

    %% Website Frontend
    subgraph "Website Frontend"
        %% UI Components
        subgraph "UI Components"
            Web_Components["Component Files"]:::website
            Web_Islands["Island Components"]:::website
        end

        %% State Management & Actions
        subgraph "State Management & Actions"
            Web_Stores["State Stores"]:::website
            Web_Actions["Actions"]:::website
        end

        %% Assets
        subgraph "Assets"
            Web_Public["Static Assets"]:::website
            Web_Audio["Audio Assets"]:::website
            Web_Images["Image Assets"]:::website
            Web_Videos["Video Assets"]:::website
        end
    end

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment"
        CI_CD["CI/CD Workflows"]:::shared
        BotEnv["Bot Env Config"]:::shared
        WebEnv["Website Env Config"]:::shared
        Build_Tools["Webpack Config"]:::shared
        TSConfig["TypeScript Config"]:::shared
    end

    %% Connections - Bot Service
    Discord_API -->|"sendsEvents"| Bot_Listeners
    Bot_Listeners -->|"triggers"| Bot_Commands
    Bot_API -->|"callsAdmin"| Bot_Admin
    Bot_API -->|"usesDB"| Bot_Prism
    Bot_Sounds -->|"usedBy"| Bot_Audio
    Bot_Prism -->|"dbOperations"| Postgres

    %% Connections - Website & Bot Interaction
    Web_Components -->|"apiCalls"| Bot_API

    %% Connections - CI/CD & Deployment to Services
    CI_CD -->|"deploys"| Bot_API
    CI_CD -->|"deploys"| Web_Components
    BotEnv -->|"configures"| Bot_API
    WebEnv -->|"configures"| Web_Components
    Build_Tools -->|"builds"| Web_Components
    TSConfig -->|"compiles"| Bot_API
    TSConfig -->|"compiles"| Web_Components

    %% Class Definitions
    classDef bot fill:#f9f,stroke:#333,stroke-width:1px;
    classDef website fill:#9f9,stroke:#333,stroke-width:1px;
    classDef external fill:#ff9,stroke:#333,stroke-width:1px;
    classDef shared fill:#9ff,stroke:#333,stroke-width:1px;

    %% Click Events for Bot Service – Discord Integration
    click Bot_Commands "https://github.com/discord/airhornbot/tree/main/bot/src/discord/commands"
    click Bot_Listeners "https://github.com/discord/airhornbot/tree/main/bot/src/discord/listeners"
    click Bot_Types "https://github.com/discord/airhornbot/tree/main/bot/src/discord/types"
    click Bot_Buttons "https://github.com/discord/airhornbot/tree/main/bot/src/discord/buttons"

    %% Click Events for Bot Service – API Routes / Admin Endpoints
    click Bot_API "https://github.com/discord/airhornbot/tree/main/bot/src/routes"
    click Bot_Admin "https://github.com/discord/airhornbot/tree/main/bot/src/routes/api/admin"

    %% Click Events for Bot Service – Sound Management
    click Bot_Sounds "https://github.com/discord/airhornbot/tree/main/bot/sounds"
    click Bot_Audio "https://github.com/discord/airhornbot/blob/main/bot/src/utils/AirhornAudio.ts"

    %% Click Event for Bot Service – Database Layer
    click Bot_Prism "https://github.com/discord/airhornbot/tree/main/bot/prisma"

    %% Click Events for Website Frontend – UI Components
    click Web_Components "https://github.com/discord/airhornbot/tree/main/website/src/components"
    click Web_Islands "https://github.com/discord/airhornbot/tree/main/website/src/components/islands"

    %% Click Events for Website Frontend – State Management & Actions
    click Web_Stores "https://github.com/discord/airhornbot/tree/main/website/src/stores"
    click Web_Actions "https://github.com/discord/airhornbot/tree/main/website/src/actions"

    %% Click Events for Website Frontend – Assets
    click Web_Public "https://github.com/discord/airhornbot/tree/main/website/public"
    click Web_Audio "https://github.com/discord/airhornbot/tree/main/website/src/audio"
    click Web_Images "https://github.com/discord/airhornbot/tree/main/website/src/images"
    click Web_Videos "https://github.com/discord/airhornbot/tree/main/website/src/videos"

    %% Click Events for Shared/Supporting CI/CD & Deployment
    click CI_CD "https://github.com/discord/airhornbot/tree/main/.github/workflows"
    click BotEnv "https://github.com/discord/airhornbot/blob/main/bot/.env.example"
    click WebEnv "https://github.com/discord/airhornbot/blob/main/website/.env.example"
    click Build_Tools "https://github.com/discord/airhornbot/blob/main/website/webpack.config.ts"
    click TSConfig "https://github.com/discord/airhornbot/blob/main/tsconfig.json"
```
