# kevinfinalboss/aurora architecture

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

- Interactive diagram: https://gitdiagram.com/kevinfinalboss/aurora
- Repository: https://github.com/kevinfinalboss/aurora

## Overview

##### Project Type and Purpose
- This is a standalone backend service: a Discord bot built on Node.js (discord.js) with support for shards, a database, AWS Parameter Store, scheduled tasks, and multiple external APIs (Riot, DDragon, Pterodactyl).
- It is not a traditional “full-stack” web app but rather a message-driven microservice that interacts bi-directionally with the Discord gateway and various third-party services.

##### File Structure Analysis
- Top level:
- index.js (entry point)
- Dockerfile & docker-compose.yml (deployment)
- package.json (dependencies)
- bot/discord/structures:
- client.js (initializes Discord.Client, shard manager, event router)
- configuration (reads config from JSON or AWS Parameter Store)
- database (connects to DB, defines repository + migrations)
- events (client & guild event handlers)
- commands & slashcommands (prefix-based and slash command handlers, grouped by domain: admin, info, music, ptero, quotation, utils, vlr)
- functions (utilities: logger, cache cleaning, wrappers for Riot & DDragon APIs)
- music, ptero, schedules (third-party integrations & cron jobs)

##### Key Behaviors from README
- Sharding: multiple connections to Discord gateway when >2,500 servers
- Hot-reload: dynamic reloading of commands/events without downtime
- Permissions & developer/guild-only flags per command
- Optional DB integration toggled via config

##### Main Components
a. Discord Bot Service
- Discord.Client + Shard Manager
- Command Handler (prefix + slash)
- Event Dispatcher
- Scheduler
- Configuration Loader (JSON & AWS Parameter Store)
- Database Layer (Connector + Repositories + Migrations)
- Utility Modules (Logger, CacheCleaner, RiotAPI, DDragonAPI, PteroClient)
b. External Systems
- Discord Gateway API
- AWS Parameter Store
- Database (e.g., MongoDB, Postgres)
- Riot Games APIs & Data Dragon
- Pterodactyl API
c. Deployment
- Docker Container
- docker-compose orchestration

##### Relationships & Data Flow
- At startup, Configuration Loader fetches env vars & secrets (local JSON or AWS).
- Bot Service initializes shards (Shard Manager) and connects to Discord Gateway.
- On Gateway events, Event Dispatcher routes to appropriate handler modules.
- Command Handler interprets prefix/slash commands, applies permission checks, then invokes business logic.
- Business logic may:
- Read/write from Database via Repositories
- Call external APIs (Riot, DDragon, Pterodactyl) via utility clients
- Schedule future jobs or quotes
- All actions are logged via Logger module.

##### Architectural Patterns & Principles
- Event-Driven Architecture: everything triggered by Discord Gateway events or cron schedules.
- Modular Handler Pattern: one directory per feature domain; each module exports metadata + run method.
- Dependency Injection (config toggles DB, shards).
- Single Responsibility: split config, commands, events, database, and external integrations.
- Hot-swap Reloaders: dynamic require/uncache for commands and events.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker Container" 
        direction TB
        index["index.js"]:::deployment
        dockerfile["Dockerfile"]:::deployment
        compose["docker-compose.yml"]:::deployment
        pkg["package.json"]:::deployment

        subgraph "Config Loader" 
            direction TB
            json["Local JSON Config"]:::internal
            awsparam["AWS Parameter Store"]:::internal
        end

        subgraph "Discord Bot Service" 
            direction TB
            shard["Shard Manager & Discord.Client"]:::internal
            dispatcher["Event Dispatcher"]:::internal

            subgraph "Command Processors" 
                direction TB
                prefix["Prefix Commands"]:::internal
                slash["Slash Commands"]:::internal
            end

            scheduler["Scheduler (Cron Jobs)"]:::internal

            subgraph "Database Layer" 
                direction TB
                connector["DB Connector"]:::internal
                repo["Guild Repository"]:::internal
                migrate["Migrations"]:::internal
            end

            subgraph "Utility Modules" 
                direction TB
                logger["Logger"]:::internal
                cachec["Cache Cleaner"]:::internal
                riot["Riot API Client"]:::internal
                ddragon["DDragon API Client"]:::internal
                pteroClient["Ptero Client"]:::internal

                subgraph "Music Integration" 
                    direction TB
                    riffycfg["Riffy Config"]:::internal
                    riffyevt["Riffy Events"]:::internal
                end
            end
        end
    end

    subgraph "External Services"
        direction TB
        discordAPI["Discord Gateway API"]:::external
        awsPS["AWS Parameter Store Service"]:::external
        db["Database (Mongo/Postgres)"]:::datastore
        riotSvc["Riot Games API"]:::external
        ddragonSvc["DDragon CDN"]:::external
        pteroSvc["Pterodactyl API"]:::external
    end

    index -->|starts| shard
    json -->|provides config| shard
    awsparam -->|fetches secrets| shard

    shard -->|connects| discordAPI
    discordAPI -->|events| dispatcher
    dispatcher -->|routes to| prefix
    dispatcher -->|routes to| slash

    prefix -->|executes| repo
    slash -->|executes| repo

    repo -->|reads/writes| db
    migrate -->|runs migrations on| db

    prefix -->|calls| riot
    prefix -->|calls| ddragon
    prefix -->|calls| pteroSvc
    slash -->|calls| riot
    slash -->|calls| ddragon
    slash -->|calls| pteroSvc

    scheduler -->|triggers| dispatcher

    shard -->|logs to| logger
    dispatcher -->|logs to| logger
    prefix -->|logs to| logger
    slash -->|logs to| logger

    riot -->|requests| riotSvc
    ddragon -->|requests| ddragonSvc
    pteroClient -->|requests| pteroSvc

    shard -->|init DB via| connector
    connector -->|provides repos| repo

    %% Click Events
    click shard "https://github.com/kevinfinalboss/aurora/blob/master/bot/discord/structures/client.js"
    click json "https://github.com/kevinfinalboss/aurora/blob/master/bot/discord/structures/configuration/index.js"
    click awsparam "https://github.com/kevinfinalboss/aurora/blob/master/bot/discord/structures/aws/parameter-store/retrieve-stores.js"
    click connector "https://github.com/kevinfinalboss/aurora/blob/master/bot/discord/structures/database/connect.js"
    click repo "https://github.com/kevinfinalboss/aurora/blob/master/bot/discord/structures/database/repository/guildRepository.js"
    click migrate "https://github.com/kevinfinalboss/aurora/blob/master/bot/discord/structures/database/schema/migrations.js"
    click prefix "https://github.com/kevinfinalboss/aurora/tree/master/bot/discord/structures/commands"
    click slash "https://github.com/kevinfinalboss/aurora/tree/master/bot/discord/structures/slashcommands"
    click scheduler "https://github.com/kevinfinalboss/aurora/blob/master/bot/discord/structures/schedules/quotation.js"
    click logger "https://github.com/kevinfinalboss/aurora/blob/master/bot/discord/structures/functions/logger.js"
    click cachec "https://github.com/kevinfinalboss/aurora/blob/master/bot/discord/structures/functions/cache_clean.js"
    click riot "https://github.com/kevinfinalboss/aurora/blob/master/bot/discord/structures/functions/riot/riotApi.js"
    click ddragon "https://github.com/kevinfinalboss/aurora/blob/master/bot/discord/structures/functions/riot/ddragonApi.js"
    click pteroClient "https://github.com/kevinfinalboss/aurora/blob/master/bot/discord/structures/ptero/client.js"
    click riffycfg "https://github.com/kevinfinalboss/aurora/blob/master/bot/discord/structures/music/riffy-config.js"
    click riffyevt "https://github.com/kevinfinalboss/aurora/blob/master/bot/discord/structures/music/riffy-events.js"

    classDef internal fill:#D0E6FF,stroke:#0044CC,color:#000
    classDef external fill:#DFFFE0,stroke:#44AA00,color:#000
    classDef datastore fill:#FFE6B3,stroke:#CC6600,color:#000
    classDef deployment fill:#F2F2F2,stroke:#999999,color:#000,stroke-dasharray: 5 5
```
