# emilyxfox/janitor-discord-bot architecture

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

- Interactive diagram: https://gitdiagram.com/emilyxfox/janitor-discord-bot
- Repository: https://github.com/emilyxfox/janitor-discord-bot

## Overview

##### Project Type and Purpose
- The project is a Discord bot built using TypeScript and running on the Deno runtime.
- Its purpose is to serve a private Discord server by handling commands, cron jobs, and various events (like guild member activities, message processing, etc.). It is designed to be extensible so that any server member can contribute new functionality.
- The README and file structure show that it also integrates with database functionality (using migration scripts and a schema) and logging, as well as third-party services (e.g., Bluesky).

##### Analysis of the File Structure
- Top-Level Files and Folders:
- .github, Dockerfile, compose.yaml, .env.example, etc.: Indicates CI/CD integration with GitHub Actions and containerization via Docker Compose.
- main.ts: The likely entry point of the application.
- deno.json and deno.lock: Deno-specific configuration and dependencies.
- Application Core Directories:
- "discord": Contains code related to the Discord bot functionality. It is further segmented into subdirectories like:
- Command handling (commands folder) with separate command modules (e.g., BulkDelete, CreatePoll, Ping, etc.).
- Event handling (events folder): Further divided into modules based on event types (guildMemberAdd, messageCreate, interactionCreate, ready, shardDisconnect, etc.).
- Cron jobs folder for scheduled tasks.
- "database": Contains the database connection logic (database.ts, schema.ts) along with migration files (drizzle directory with SQL migrations and snapshots).
- "logging": Contains centralized logging logic/file.
- "exec": Contains scripts that might be used for one-off or maintenance tasks (i.e., deregistering global commands).
- Other Utility Folders: "utils" for graceful shutdown, environment configuration and healthcheck functions; "types" for shared TypeScript types which help enforce contracts across components.

##### Identifying Main Components
- Core Application:
- Client/Entry Point (main.ts) that bootstraps the application.
- Discord Bot module (located in discord/DiscordBot.ts) serving as the core engine.
- Discord Interaction Layer:
- CommandHandler, CronHandler, and EventHandler modules that process commands and events.
- Specific command modules (within discord/commands) that implement distinct bot functionality.
- Specific event modules (within discord/events) that capture various Discord events (guild member events, message creation, button interactions, etc.).
- Database Component:
- Database connection logic (database/database.ts, database/schema.ts).
- Migration and versioning logic (drizzle directory scripts and meta snapshots), ensuring the database structure is in sync.
- Logging and Utility Modules:
- Centralized logging (logging/logger.ts).
- Healthcheck and graceful shutdown utilities (utils folder).
- External Services/Integrations:
- Discord APIs for bot interaction.
- Bluesky integration (noted via badges in the README).
- Container orchestration (Docker, Docker Compose service definitions).
- GitHub Actions for CI/CD pipelines as configured in the .github directory.

##### Relationships and Interactions
- The main.ts file is the starting point that creates an instance of the Discord Bot.
- It initializes the Discord Bot module, which in turn sets up various handlers (commands, events, and cron jobs).
- Command modules and event modules are registered with their respective handlers to respond dynamically to Discord API interactions.
- The bot integrates with the Database component to persist or retrieve information when required by commands or events.
- Logging is pervasive throughout the system to record activities and errors, and the graceful shutdown utilities ensure proper cleanup.
- The Docker Compose file links the bot container to a database container showing the external dependency if the app is run in production.
- The README additionally hints at configuring environment variables (like DISCORD_TOKEN, DB_URL, etc.) that connect these components with external services.

##### Architectural Patterns and Technologies
- Modular design is enforced with separation of concerns: commands, events, cron jobs, and database are kept in individual modules.
- Micro-kernel or plugin-based architecture hints at the ease of adding additional command/event modules.
- Usage of Deno as the runtime and TypeScript for strict type checking, along with configuration files like deno.json.
- Containerization (Docker, Docker Compose) allows for separation between the bot and its database, ensuring a production-like architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Application Layer
    Main["Client/Entry (main.ts)"]:::core
    DiscordBot["Discord Bot Core (DiscordBot)"]:::core

    %% Discord Interaction Layer
    subgraph "Discord Bot Layer"
        CmdHandler["Command Handler (CommandHandler)"]:::core
        CmdModules["Command Modules (discord/commands/)"]:::core
        EvtHandler["Event Handler (EventHandler)"]:::core
        EvtModules["Event Modules (discord/events/)"]:::core
        CronHandler["Cron Job Handler (CronHandler)"]:::core
        CronJobs["Cron Jobs (discord/cron-jobs/)"]:::core
    end

    %% Database Layer
    subgraph "Database Layer"
        DBConn["DB Connection (database.ts & schema.ts)"]:::core
        DBMigrate["DB Migrations (drizzle/)"]:::core
    end

    %% Support & Utility Modules
    Logger["Logging Module (logger.ts)"]:::core
    Utils["Utility Modules (utils/)"]:::utility
    Exec["Exec Scripts (exec/)"]:::utility
    Types["Type Declarations (types/)"]:::utility

    %% External Services
    DiscordAPI["Discord API"]:::external
    Bluesky["Bluesky Integration"]:::external

    %% Containerization & CI/CD
    DockerBot["Bot Container (Docker Compose)"]:::external
    DockerDB["DB Container (Docker Compose)"]:::external
    GitHub["GitHub Actions (CI/CD)"]:::external

    %% Relationships
    Main -->|"bootstraps"| DiscordBot
    DiscordBot -->|"initializes"| CmdHandler
    DiscordBot -->|"initializes"| EvtHandler
    DiscordBot -->|"initializes"| CronHandler

    CmdHandler -->|"loads"| CmdModules
    EvtHandler -->|"loads"| EvtModules
    CronHandler -->|"schedules"| CronJobs

    %% Handlers interacting with core modules
    DiscordBot -->|"queries"| DBConn
    CmdHandler -- "persist/retrieve" --> DBConn
    EvtHandler -- "persist/retrieve" --> DBConn

    %% Database migrations
    DBConn -->|"managed by"| DBMigrate

    %% Logging and utilities
    DiscordBot -->|"logs to"| Logger
    CmdHandler -->|"logs to"| Logger
    EvtHandler -->|"logs to"| Logger

    DiscordBot -->|"config & shutdown"| Utils
    DiscordBot -->|"maintenance"| Exec
    DiscordBot -->|"enforces types"| Types

    %% External integrations
    DiscordBot -->|"communicates"| DiscordAPI
    DiscordBot -->|"calls"| Bluesky

    %% Containerization and CI/CD integration
    DockerBot -->|"runs"| DiscordBot
    DockerDB -->|"hosts"| DBConn
    GitHub -->|"deploys to"| DockerBot
    GitHub -->|"deploys to"| DockerDB

    %% Click Events
    click Main "https://github.com/emilyxfox/janitor-discord-bot/blob/main/main.ts"
    click DiscordBot "https://github.com/emilyxfox/janitor-discord-bot/blob/main/discord/DiscordBot.ts"
    click CmdHandler "https://github.com/emilyxfox/janitor-discord-bot/blob/main/discord/CommandHandler.ts"
    click CmdModules "https://github.com/emilyxfox/janitor-discord-bot/tree/main/discord/commands/"
    click EvtHandler "https://github.com/emilyxfox/janitor-discord-bot/blob/main/discord/EventHandler.ts"
    click EvtModules "https://github.com/emilyxfox/janitor-discord-bot/tree/main/discord/events/"
    click CronHandler "https://github.com/emilyxfox/janitor-discord-bot/blob/main/discord/CronHandler.ts"
    click CronJobs "https://github.com/emilyxfox/janitor-discord-bot/tree/main/discord/cron-jobs/"
    click DBConn "https://github.com/emilyxfox/janitor-discord-bot/blob/main/database/database.ts"
    click DBConn "https://github.com/emilyxfox/janitor-discord-bot/blob/main/database/schema.ts"
    click DBMigrate "https://github.com/emilyxfox/janitor-discord-bot/tree/main/database/drizzle/"
    click Logger "https://github.com/emilyxfox/janitor-discord-bot/blob/main/logging/logger.ts"
    click Utils "https://github.com/emilyxfox/janitor-discord-bot/tree/main/utils/"
    click Exec "https://github.com/emilyxfox/janitor-discord-bot/tree/main/exec/"
    click Types "https://github.com/emilyxfox/janitor-discord-bot/tree/main/types/"

    %% Styles
    classDef core fill:#8ec07c,stroke:#333,stroke-width:2px;
    classDef external fill:#83a598,stroke:#333,stroke-width:2px,stroke-dasharray: 4 2;
    classDef utility fill:#fabd2f,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
```
