# adrian-ortega/aodevbot architecture

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

- Interactive diagram: https://gitdiagram.com/adrian-ortega/aodevbot
- Repository: https://github.com/adrian-ortega/aodevbot

## Overview

##### Main Components
- Bot Core & API Server: The core “engine” of the bot is found in the “src/server.js” and “src/app/http” directories. This is where the Express REST API is implemented with various controllers (e.g., TwitchAuthController, TwitchController, ChatController, SpotifyAuthController, etc.) and routes to handle endpoints.
- WebSocket Server: Under “src/app/websockets” you have modules handling real-time actions such as chat messages, debug commands, and events related to Spotify and stats – indicating a dedicated real-time communication service.
- Twitch Integration Module: The “src/app/twitch” folder contains interactions with Twitch including authentication, chat commands, events, and handling leaderboard and stream events. It’s safe to encapsulate all Twitch-specific logic as a module.
- Spotify Integration Module: Similarly, the “src/app/spotify” folder groups together authentication, chat-related actions (commands, caching), and other Spotify-specific logic.
- Logging & Support: The “src/app/log” directory indicates a subsystem for capturing logs, while “src/app/support” contains various helper modules (e.g., for file handling, string manipulation, timestamps, UUID generation) that support the application’s operations.
- Data Models: In “src/app/models” you have a set of data model definitions (e.g., Chat, Chatter, Game, Stream, Token, etc.) which you might later tie to a database as outlined in the TODO list (choose a schema/database). This forms the persistence layer.
- Statistics/Analytics: The “src/app/stats” directory shows components for calculating and managing statistics (such as song-requests, followers, bits leaders), which should be illustrated as a module that interacts with both the core data and external event triggers.
- Frontend/Overlay Assets: Located under “src/public”, there is an HTML file and additional assets (CSS, JS, audio files), which together serve as the overlay/browser source component, signaling that the bot pushes notifications to a connected browser overlay.

##### Relationships and Flow
- The Express REST API (HTTP Server) acts as the entry point for external client operations (e.g., administrative interfaces, manual interactions, maybe even API calls for overlays).
- The WebSocket Server runs parallel to the REST API to push notifications and real-time event updates (chat events, stats, etc.) to connected overlay clients.
- Within the bot core, Twitch and Spotify modules listen to and interact with their respective external services: for Twitch, this includes authentication, registering chat commands, and responding to events; for Spotify, it handles playback, search, and command processing.
- The models are leveraged by both the API and integration modules for CRUD operations and for logging activities/events.
- Logging and support utilities cut across most components to unify error handling, debugging, and utility functions.
- Deploy and environment management (Dockerfile, docker-compose.yml, .env files) wrap the whole architecture environment, indicating containerized deployment.

##### Highlighting Architectural Patterns and Technologies
- Modular Design: The project is clearly modularized (separation of concerns) across controllers, routers, and integration modules (Twitch, Spotify, etc.). This separation is conducive to a microservices-inspired design even if all modules are deployed together.
- Event-Driven Patterns: With WebSocket-based communication and event modules (e.g., Twitch chat events, Spotify events), the system employs an asynchronous event-driven architecture.
- MVC-Like Routing: The use of HTTP controllers and routes indicates an MVC (or similar) approach for handling API requests.
- Technology Stack: This is a Node.js application (with Express for REST APIs) using libraries such as tmi.js for Twitch interaction, and likely other npm packages for logging, WebSocket management, and possibly ESLint/Prettier for code quality.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Services
    subgraph "External Services"
        EC["External Clients (Overlay/Browser)"]:::external
        TS["Twitch Service"]:::external
        SS["Spotify Service"]:::external
    end

    %% Core Services
    subgraph "Core Services"
        BotCore["Bot Core & API Server"]:::core
        WS["WebSocket Server"]:::core
    end

    %% Integration Modules
    subgraph "Integration Modules"
        TIntegration["Twitch Integration Module"]:::integration
        SIntegration["Spotify Integration Module"]:::integration
    end

    %% Utilities
    subgraph "Utilities"
        LogSupport["Logging & Support"]:::utility
        Models["Data Models / Persistence"]:::data
        Stats["Statistics & Analytics"]:::data
    end

    %% Frontend Components
    subgraph "Frontend Components"
        Overlay["Frontend/Overlay Assets"]:::frontend
    end

    %% Deployment Environment
    subgraph "Deployment"
        Docker["Deployment (Docker)"]:::deployment
    end

    %% Connections from External Actors
    EC -->|"HTTP"| BotCore
    EC -->|"WebSocket"| WS
    TS -->|"sendsEvents"| TIntegration
    SS -->|"sendsEvents"| SIntegration

    %% Core Service Interactions
    BotCore -->|"APIcalls"| Models
    BotCore -->|"Logs"| LogSupport
    BotCore -->|"Commands"| TIntegration
    BotCore -->|"Commands"| SIntegration

    %% Integration Module Communications
    TIntegration -->|"realTimeUpdates"| WS
    SIntegration -->|"realTimeUpdates"| WS
    TIntegration -->|"updatesStats"| Stats
    SIntegration -->|"updatesStats"| Stats
    TIntegration -->|"logs"| LogSupport
    SIntegration -->|"logs"| LogSupport

    %% WebSocket to Frontend
    WS -->|"pushesUpdates"| Overlay

    %% Deployment Connections
    Docker --> BotCore
    Docker --> WS
    Docker --> TIntegration
    Docker --> SIntegration
    Docker --> Models
    Docker --> LogSupport
    Docker --> Stats

    %% Click Events
    click BotCore "https://github.com/adrian-ortega/aodevbot/blob/master/src/server.js"
    click WS "https://github.com/adrian-ortega/aodevbot/tree/master/src/app/websockets/"
    click TIntegration "https://github.com/adrian-ortega/aodevbot/tree/master/src/app/twitch/"
    click SIntegration "https://github.com/adrian-ortega/aodevbot/tree/master/src/app/spotify/"
    click LogSupport "https://github.com/adrian-ortega/aodevbot/tree/master/src/app/log/"
    click Models "https://github.com/adrian-ortega/aodevbot/tree/master/src/app/models/"
    click Stats "https://github.com/adrian-ortega/aodevbot/tree/master/src/app/stats/"
    click Overlay "https://github.com/adrian-ortega/aodevbot/tree/master/src/public/"

    %% Class Definitions for Colors
    classDef external fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef core fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef integration fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
    classDef utility fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef data fill:#E1BEE7,stroke:#6A1B9A,stroke-width:2px;
    classDef frontend fill:#D1C4E9,stroke:#4527A0,stroke-width:2px;
    classDef deployment fill:#FFE082,stroke:#FF8F00,stroke-width:2px;
```
