# sleepymaidbot/sleepymaid architecture

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

- Interactive diagram: https://gitdiagram.com/sleepymaidbot/sleepymaid
- Repository: https://github.com/sleepymaidbot/sleepymaid

## Overview

##### Project Type and Purpose
- This is a TypeScript monorepo for a suite of Discord utility bots and a companion web dashboard, all orchestrated via Docker Compose.
- The “services” directory contains several independent Discord bot services (sleepymaid, helper, clarity, watcher, testbot) plus an API service and a Remix-based website.
- The “packages” directory holds shared libraries:
- db (Drizzle ORM configs and schemas)
- handler (command/listener/task framework for bots)
- logger (logging abstraction)
- shared (core utilities: config, localization, permissions, RabbitMQ integration)
- util (generic helpers & tests)

##### High-Level Architecture Components
a. Containers (Dockerized services):
- Database (PostgreSQL or similar)
- Message Broker (RabbitMQ)
- API service (serves JSON endpoints to website)
- Bot services (sleepymaid, helper, clarity, watcher, testbot)
- Website (Remix app)
b. Internal Modules (Node libraries consumed by containers):
- @sleepymaid/db
- @sleepymaid/handler
- @sleepymaid/logger
- @sleepymaid/shared
- @sleepymaid/util
c. External Systems:
- Discord API (for bots)
- Docker Registry / CI (GitHub Actions)

##### Component Relationships and Data Flows
- Each bot service container imports handler + shared + logger packages to register commands, listeners, and tasks against the Discord API.
- Bot services read/write application state in the Database using the db package and emit or consume events from RabbitMQ via shared/rabbitmq.
- The API service talks to the Database for CRUD operations and reads/writes to RabbitMQ for asynchronous tasks (if any).
- The Website calls the API service over HTTP, persists session data in the Database, and may dispatch jobs via the Message Broker.
- GitHub Actions CI builds, tests, and publishes container images to the Docker Registry; Docker Compose (dev/prod configs) spins up all containers together.

##### Architectural Patterns and Design Principles
- Monorepo + internal packages for code reuse (handler, logger, shared, util).
- Microservices: each Discord bot is its own container, allowing independent scaling and deployment.
- Event-driven communication via RabbitMQ for cross-service hooks or background tasks.
- Layered organization:
- Presentation: Website (Remix)
- API: REST service
- Domain logic: Bot services + shared libraries
- Persistence: Relational DB (Drizzle ORM)
- Infrastructure as Code: Dockerfiles, Docker Compose, GitHub Actions.

b. “RabbitMQ” to the side of the DB. Label it “Message Broker”.
d. Inside that boundary, add:
- For each Bot service:
e. Outside the Docker boundary, show:
- Discord API cloud connecting to each bot.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Docker Compose Network
    subgraph "Docker Compose Network"
        direction TB
        DB["PostgreSQL (Drizzle ORM)"]:::infra
        RabbitMQ["Message Broker"]:::infra

        API["API Service"]:::service
        Website["Website (Remix App)"]:::ui

        subgraph "Bot Services"
            direction TB
            Sleepymaid["Sleepymaid Bot"]:::service
            Helper["Helper Bot"]:::service
            Clarity["Clarity Bot"]:::service
            Watcher["Watcher Bot"]:::service
            Testbot["Testbot Bot"]:::service
        end
    end

    %% External Systems
    DiscordAPI["Discord API"]:::external
    GitHubCI["GitHub Actions / Docker Registry"]:::external

    %% Connections - Synchronous
    API -->|"Reads/Writes"| DB
    Website -->|"HTTP Calls"| API
    Sleepymaid -->|"DB: Read/Write Settings"| DB
    Helper -->|"DB: Read/Write Settings"| DB
    Clarity -->|"DB: Read/Write Settings"| DB
    Watcher -->|"DB: Read/Write Settings"| DB
    Testbot -->|"DB: Read/Write Settings"| DB

    %% Connections - Asynchronous (RabbitMQ)
    API -.->|"Publishes/Consumes"| RabbitMQ
    Sleepymaid -.->|"Events/Tasks"| RabbitMQ
    Helper -.->|"Events/Tasks"| RabbitMQ
    Clarity -.->|"Events/Tasks"| RabbitMQ
    Watcher -.->|"Events/Tasks"| RabbitMQ
    Testbot -.->|"Events/Tasks"| RabbitMQ

    %% External Bot Integration
    Sleepymaid -->|"REST/WebSocket"| DiscordAPI
    Helper -->|"REST/WebSocket"| DiscordAPI
    Clarity -->|"REST/WebSocket"| DiscordAPI
    Watcher -->|"REST/WebSocket"| DiscordAPI
    Testbot -->|"REST/WebSocket"| DiscordAPI

    %% CI/CD
    GitHubCI -->|"Builds & Publishes Images"| API
    GitHubCI -->|"Builds & Publishes Images"| Sleepymaid
    GitHubCI -->|"Builds & Publishes Images"| Helper
    GitHubCI -->|"Builds & Publishes Images"| Clarity
    GitHubCI -->|"Builds & Publishes Images"| Watcher
    GitHubCI -->|"Builds & Publishes Images"| Testbot
    GitHubCI -->|"Builds & Publishes Images"| Website

    %% Click Events
    click DB "https://github.com/sleepymaidbot/sleepymaid/tree/main/packages/db"
    click RabbitMQ "https://github.com/sleepymaidbot/sleepymaid/blob/main/packages/shared/src/rabbitmq.ts"
    click API "https://github.com/sleepymaidbot/sleepymaid/blob/main/services/api/src/index.ts"
    click Sleepymaid "https://github.com/sleepymaidbot/sleepymaid/blob/main/services/sleepymaid/src/index.ts"
    click Helper "https://github.com/sleepymaidbot/sleepymaid/blob/main/services/helper/src/index.ts"
    click Clarity "https://github.com/sleepymaidbot/sleepymaid/blob/main/services/clarity/src/index.ts"
    click Watcher "https://github.com/sleepymaidbot/sleepymaid/blob/main/services/watcher/src/index.ts"
    click Testbot "https://github.com/sleepymaidbot/sleepymaid/blob/main/services/testbot/src/index.ts"
    click Website "https://github.com/sleepymaidbot/sleepymaid/tree/main/services/website"
    click Handler "https://github.com/sleepymaidbot/sleepymaid/tree/main/packages/handler/src"
    click Logger "https://github.com/sleepymaidbot/sleepymaid/tree/main/packages/logger/src"
    click Shared "https://github.com/sleepymaidbot/sleepymaid/tree/main/packages/shared/src"
    click Util "https://github.com/sleepymaidbot/sleepymaid/tree/main/packages/util/src"
    click DockerCompose "https://github.com/sleepymaidbot/sleepymaid/blob/main/compose/docker-compose.dev.yml"
    click Dockerfile "https://github.com/sleepymaidbot/sleepymaid/tree/main/docker/services/Dockerfile"
    click CI "https://github.com/sleepymaidbot/sleepymaid/blob/main/ .github/workflows/test.yml"

    %% Styles
    classDef infra fill:#D0E8FF,stroke:#0066CC,color:#003366
    classDef service fill:#E0FFD8,stroke:#33AA33,color:#005500
    classDef ui fill:#FFE8B0,stroke:#FFAA00,color:#773300
    classDef external fill:#EEEEEE,stroke:#888888,color:#555555
```
