# barkloaf/holidaybot architecture

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

- Interactive diagram: https://gitdiagram.com/barkloaf/holidaybot
- Repository: https://github.com/barkloaf/holidaybot

## Overview

##### Main Architectural Components
- Main Application (main.go): This is the entry point. It’s responsible for initializing the DiscordGo session, loading configuration (using misc/Config.go), and setting up event and command handlers.
- Event Handlers (folder: events): Contains Go files like Ready.go, GuildCreate.go, MessageCreate.go, etc. These modules process Discord events (connectivity, guild updates, channel deletions, interactions) and then forward them to the appropriate handlers.
- Command Handlers (folder: commands): Houses the implementation for each bot command (e.g., /about, /ping, /stats, /h, /set and its subcommands). Each command module (About.go, Ping.go, etc.) encapsulates the logic to respond to user interactions.
- Database Module (folder: db): Contains functions to initialize the database, insert, update, and select guild settings. This module persists settings like timezones, content filters (adult content), daily posting preferences, and channel configurations.
- Daily Posting Scheduler and Logic (dailyPosting.go): Handles the scheduling of daily messages that provide holiday information at midnight based on server-specific timezone settings.
- Utility/Helper Functions (folder: misc): Offers support with time zone calculations (using zoneinfo directory and misc/Zone.go), logging (misc/Logger.go), and fetching default configuration values for timezones and channels.
- Zoneinfo Data (folder: zoneinfo): Contains timezone data files that support the command (/h) and settings (/set timezone) feature. This ensures the bot uses accurate timezone information.

##### Relationships and Data Flow
- The Main Application initiates a Discord session and registers event listeners.
- Event Handlers receive events from Discord (via DiscordGo) and dispatch the relevant events to either command handlers or to update the database (for instance, updating guild settings upon creation or deletion).
- Command Handlers receive slash command interactions and, depending on the command issued (examples: /about, /ping, /set, /h), call the appropriate function. Some commands modify the database (settings adjustments) or trigger responses.
- The Database Module is used both when responding to commands (to return or update settings) and when scheduling daily postings (to retrieve each guild’s configuration like timezone or channel).
- The Daily Posting module periodically retrieves the necessary settings (using the Database Module) and sends holiday messages in the designated channel.
- Utility modules (under misc) provide key functions required by all other components such as logging activities, configuration management, and fetching default timezone/channel data.
- The Zoneinfo data supports timezone lookup for both command processing and the scheduling logic, ensuring that holiday posting adheres to each server’s local time settings.

##### Architectural Patterns & Design Principles
- Event-Driven Architecture: The project heavily relies on event and command handlers—each listening for specific Discord events and reacting accordingly.
- Modular Separation of Concerns: The codebase is split into distinct directories (events, commands, db, misc) where each module has a clear responsibility.
- Dependency on External Libraries: The project primarily uses DiscordGo to interface with Discord’s API.
- Extensibility: With separate modules for commands and events, new functionality or commands can be added with minimal impact on the rest of the system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Main Application (main.go)"]:::core
    B["Utilities & Config (misc)"]:::utility
    C["Event Handlers (events)"]:::core
    D["Command Handlers (commands)"]:::core
    E["Database Module (db)"]:::core
    F["Daily Posting Scheduler (dailyPosting.go)"]:::core
    G["Zoneinfo Data (zoneinfo)"]:::utility
    H["Discord API (DiscordGo)"]:::external

    %% Main initialization and configuration
    A -->|"loadsConfig"| B
    A -->|"registersEvents"| C
    A -->|"initiatesSession"| H

    %% Event and command flow
    H -->|"sendsEvents"| C
    C -->|"dispatchesCommands"| D
    D -->|"queriesUpdatesDB"| E

    %% Daily posting scheduler flow
    F -->|"retrievesGuildConfig"| E
    F -->|"sendsDailyMessages"| H

    %% Utility support connections
    B -->|"supportsMain"| A
    B -->|"logsAndConfig"| C
    B -->|"logsAndConfig"| D
    G -->|"timezoneLookup"| D

    %% Legend (Annotations)
    %% Core Processing Blocks (Blue): A, C, D, E, F
    %% Utility/Config Blocks (Yellow): B, G
    %% External Services (Red): H

    %% Click Events
    click A "https://github.com/barkloaf/holidaybot/blob/master/main.go"
    click B "https://github.com/barkloaf/holidaybot/blob/master/misc/Config.go"
    click C "https://github.com/barkloaf/holidaybot/tree/master/events"
    click D "https://github.com/barkloaf/holidaybot/tree/master/commands"
    click E "https://github.com/barkloaf/holidaybot/tree/master/db"
    click F "https://github.com/barkloaf/holidaybot/blob/master/dailyPosting.go"
    click G "https://github.com/barkloaf/holidaybot/tree/master/zoneinfo"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef utility fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
