# mariokartworlditalia/mkw-italia-bot architecture

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

- Interactive diagram: https://gitdiagram.com/mariokartworlditalia/mkw-italia-bot
- Repository: https://github.com/mariokartworlditalia/mkw-italia-bot

## Overview

##### Project Type and Purpose
- This is a single‐service backend application: a Discord bot (“Bot ufficiale del server di Mario Kart World Italia”) implemented in TypeScript/Node.js, packaged with Docker.
- It integrates with the Discord API to handle slash commands and interactions, persists data in a database, and coordinates features like tournaments, friend codes, and emojis.

##### High‐Level Architecture Components
a. Discord Gateway / API
- Receives events (slash commands, interactions).
- Sends responses (messages, embeds, reactions).
b. Bot Application
- Entry Point (src/main.ts, src/application.ts)
- Command Router (src/interaction/*)
- Feature Flag Manager (src/feature_flags/*)
- Tournament Manager (src/tournament_manager/*)
- Emoji Manager (src/emoijs_manager.ts)
- Friend Codes Manager (src/frend_codes.ts)
- Utility Modules (src/utils.ts, src/assert.ts, src/log.ts, src/globals.ts)
c. Persistence Layer
- Database connector (src/database/database.ts)
- ORM / Models (src/database/models/*.ts)
- Repository (src/tournament_manager/tournament_repo.ts)
d. Infrastructure
- Docker container (Dockerfile, .dockerignore)
- TypeScript build (tsconfig.json)
- Package management (package.json, package-lock.json)

##### Component Interactions
- The Discord Gateway delivers an interaction event to the Bot Application (main → application).
- The Command Router dispatches the event to the appropriate handler in src/interaction/*.
- Handlers consult the Feature Flag Manager for rollout logic.
- Handlers may call into:
- Tournament Manager → uses Tournament Repo → Database Models → Database
- Emoji Manager → manages custom emojis or reactions
- Friend Codes Manager → persists or retrieves friend codes via Database
- Responses are sent back through the Discord API.

##### Architectural Patterns & Design Principles
- Modular layers (Interaction Layer, Business Logic Layer, Persistence Layer).
- Dependency inversion via repository interfaces (tournament_repo).
- Feature flag pattern to toggle features at runtime.
- Separation of concerns: each manager handles a distinct domain (tournaments, emojis, codes).
- Single‐process, event‐driven architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    DiscordAPI["Discord API (Gateway & REST)"]:::external
    Database["Database (PostgreSQL)"]:::external

    %% Bot Application Container
    subgraph "Bot Application (Node.js Service)" 
        direction TB

        %% Entry Point
        EntryMain["src/main.ts / src/application.ts"]:::app

        %% Interaction Layer
        subgraph "Interaction Layer" 
            direction TB
            SlashCmd["slash_commands.ts"]:::app
            FriendCodesCmd["friend_codes_commands.ts"]:::app
            TournamentCmd["tournament_commands.ts"]:::app
            UtilCmd["util_commands.ts"]:::app
        end

        %% Core Services Layer
        subgraph "Core Services Layer"
            direction TB
            FeatureFlags["Feature Flags Manager"]:::app
            TournamentMgr["Tournament Manager"]:::app
            EmojiMgr["Emoji Manager"]:::app
            FriendCodesMgr["Friend Codes Manager"]:::app
        end

        %% Persistence Layer
        subgraph "Persistence Layer"
            direction TB
            DBConnector["database.ts"]:::app
            Models["ORM Models"]:::app
            TournamentRepo["Tournament Repository"]:::app
        end

        %% Utility Modules
        subgraph "Utility Modules"
            direction TB
            Utils["utils.ts"]:::app
            Assert["assert.ts"]:::app
            Log["log.ts"]:::app
            Globals["globals.ts"]:::app
        end
    end

    %% Infrastructure
    subgraph "Infrastructure & Config" 
        direction TB
        DockerfileNode["Dockerfile / .dockerignore"]:::infra
        TSConfig["tsconfig.json"]:::infra
        Package["package.json / package-lock.json"]:::infra
        GitIgnore[".gitignore / README.md"]:::infra
    end

    %% Connections - Request Flow
    DiscordAPI -->|Event| EntryMain
    EntryMain -->|Dispatch| SlashCmd
    EntryMain -->|Dispatch| FriendCodesCmd
    EntryMain -->|Dispatch| TournamentCmd
    EntryMain -->|Dispatch| UtilCmd

    SlashCmd -->|Check Flag| FeatureFlags
    FriendCodesCmd -->|Check Flag| FeatureFlags
    TournamentCmd -->|Check Flag| FeatureFlags
    UtilCmd -->|Check Flag| FeatureFlags

    SlashCmd -->|Use| TournamentMgr
    TournamentCmd -->|Use| TournamentMgr
    FriendCodesCmd -->|Use| FriendCodesMgr
    SlashCmd -->|Use| EmojiMgr

    TournamentMgr --> TournamentRepo
    FriendCodesMgr --> TournamentRepo
    TournamentRepo --> DBConnector
    DBConnector --> Models
    Models --> Database

    %% Response Flow
    Models -->|Data| TournamentRepo
    TournamentRepo -->|Result| TournamentMgr
    TournamentMgr -->|Response| SlashCmd
    SlashCmd -->|Reply| DiscordAPI

    %% Utilities usage
    FeatureFlags --> Utils
    TournamentMgr --> Log
    TournamentMgr --> Assert
    FriendCodesMgr --> Globals

    %% Infrastructure relations
    EntryMain --> DockerfileNode
    EntryMain --> TSConfig
    EntryMain --> Package

    %% Click Events
    click EntryMain "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/src/main.ts"
    click EntryMain "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/src/application.ts"
    click SlashCmd "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/src/interaction/slash_commands.ts"
    click FriendCodesCmd "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/src/interaction/friend_codes_commands.ts"
    click TournamentCmd "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/src/interaction/tournament_commands.ts"
    click UtilCmd "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/src/interaction/util_commands.ts"
    click FeatureFlags "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/src/feature_flags/feature_flags_manager.ts"
    click FeatureFlags "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/src/feature_flags/feature_flag_keys.ts"
    click TournamentMgr "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/src/tournament_manager/tournaments.ts"
    click TournamentRepo "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/src/tournament_manager/tournament_repo.ts"
    click EmojiMgr "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/src/emoijs_manager.ts"
    click FriendCodesMgr "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/src/frend_codes.ts"
    click DBConnector "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/src/database/database.ts"
    click Models "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/src/database/models/models.ts"
    click Models "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/src/database/models/defaults.ts"
    click Models "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/src/database/models/tournament_model.ts"
    click Utils "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/src/utils.ts"
    click Assert "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/src/assert.ts"
    click Log "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/src/log.ts"
    click Globals "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/src/globals.ts"
    click DockerfileNode "https://github.com/mariokartworlditalia/mkw-italia-bot/tree/main/Dockerfile"
    click DockerfileNode "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/.dockerignore"
    click TSConfig "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/tsconfig.json"
    click Package "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/package.json"
    click Package "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/package-lock.json"
    click GitIgnore "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/.gitignore"
    click GitIgnore "https://github.com/mariokartworlditalia/mkw-italia-bot/blob/main/README.md"

    %% Styles
    classDef external fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef app fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20;
    classDef infra fill:#eeeeee,stroke:#9e9e9e,color:#424242;
```
