# juddisjudd/oxbot architecture

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

- Interactive diagram: https://gitdiagram.com/juddisjudd/oxbot
- Repository: https://github.com/juddisjudd/oxbot

## Overview

##### Project type and purpose
- OxBot is an open-source Discord bot built in TypeScript using discord.js and Prisma.
- It listens for Discord events (messages, slash commands, member updates), runs command logic (fun, moderation, misc, “ox” commands), and persists data via a PostgreSQL database (accessed through Prisma).

##### File structure
- Top-level files and folders
- Dockerfile, docker-compose.yaml (dev & production) → containerization and deployment
- prisma/ → database schema and migrations
- src/ → application source
– commands/ (fun, misc, moderation, ox) → individual command modules
– events/ → event listeners for Discord events
– handlers/ → core logic for dispatching events and commands
– utils/, interfaces/, config.ts, constants.ts → shared utilities, type definitions, configuration
- Configuration files (.env template, package.json, tsconfig.json, nodemon.json) and CI workflow (.github/workflows/docker-push.yml) indicate a Docker-based, TypeScript-driven CI/CD pipeline.

##### README for additional insights
- Technologies: TypeScript, pnpm, Docker, Prisma, discord.js
- Purpose: Bot for Overextended Discord, no external support—focus on extensibility and clarity.

##### Elements
- Components labeled clearly (Discord Gateway, Bot Process, Handlers, Command Modules, Prisma Client, PostgreSQL, Docker Host, CI/CD)
- Bi-directional between Bot Process and Discord API (WebSocket & REST)
- Uni-directional from Command Modules to Prisma Client → PostgreSQL
- Deployment flow from CI/CD → Docker Registry → Docker Host
- Application layers (rectangles, blue)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    subgraph "External Services"
        DiscordAPI["Discord API\n(Gateway & REST)"]:::external
    end

    %% Infrastructure Components
    subgraph "Infrastructure"
        CI["GitHub Actions (CI/CD)"]:::infra
        Registry["Docker Registry"]:::infra
        DockerHost["Docker Host"]:::infra
    end

    %% Database Layer
    subgraph "Database"
        PrismaClient["Prisma Client"]:::database
        Postgres["PostgreSQL"]:::database
    end

    %% Application Container
    subgraph "Bot Process (Docker Container)"
        DockerContainer["Docker Container\n(Bot Process)"]:::infra

        subgraph "Config & Utilities"
            Env[".env + config.ts"]:::app
            Constants["constants.ts"]:::app
            Utils["utils\n(logger, patterns, riskScoring)"]:::app
        end

        subgraph "Presentation Layer"
            DiscordClient["Discord Client"]:::app
            subgraph "Event Listeners"
                onReady["onReady"]:::app
                onMsgCreate["onMessageCreate"]:::app
                onSlash["onSlashCommand"]:::app
                onMemberJoin["onMemberJoin"]:::app
                onMemberLeave["onMemberLeave"]:::app
                onMemberKick["onMemberKick"]:::app
                onMemberBan["onMemberBan"]:::app
                onMemberUnban["onMemberUnban"]:::app
                onMemberRole["onMemberRoleUpdate"]:::app
                onMemberWarn["onMemberWarn"]:::app
                onMsgDelete["onMessageDelete"]:::app
                onPurge["onPurge"]:::app
            end
        end

        subgraph "Application Layer"
            CmdHandler["Command Handler"]:::app
            RespHandler["Bot Responses Handler"]:::app
        end

        subgraph "Domain Layer"
            Interface["Command Interface"]:::app
            subgraph "Command Modules"
                fun["Fun Commands"]:::app
                misc["Misc Commands"]:::app
                mod["Moderation Commands"]:::app
                ox["Ox Commands"]:::app
            end
        end

        subgraph "Prisma Migrations"
            Migrations["prisma/migrations"]:::infra
            Schema["schema.prisma"]:::infra
        end
    end

    %% Event and Data Flows
    DockerContainer -->|reads| Env
    DockerContainer --> DiscordClient
    DiscordClient <--> DiscordAPI
    onReady --> CmdHandler
    onMsgCreate --> CmdHandler
    onSlash --> CmdHandler
    onMemberJoin --> CmdHandler
    onMemberLeave --> CmdHandler
    onMemberKick --> CmdHandler
    onMemberBan --> CmdHandler
    onMemberUnban --> CmdHandler
    onMemberRole --> CmdHandler
    onMemberWarn --> CmdHandler
    onMsgDelete --> CmdHandler
    onPurge --> CmdHandler
    CmdHandler --> Interface
    Interface --> fun
    Interface --> misc
    Interface --> mod
    Interface --> ox
    fun --> Utils
    misc --> Utils
    mod --> Utils
    ox --> Utils
    fun --> PrismaClient
    misc --> PrismaClient
    mod --> PrismaClient
    ox --> PrismaClient
    PrismaClient --> Postgres
    CmdHandler --> RespHandler
    RespHandler --> DiscordAPI
    Schema --> PrismaClient
    Migrations --> PrismaClient

    %% Deployment Flow
    CI --> Registry
    Registry --> DockerHost
    DockerHost --> DockerContainer

    %% Click Events
    click DockerContainer "https://github.com/juddisjudd/oxbot/blob/master/src/index.ts"
    click onReady "https://github.com/juddisjudd/oxbot/blob/master/src/events/onReady.ts"
    click onMsgCreate "https://github.com/juddisjudd/oxbot/blob/master/src/events/onMessageCreate.ts"
    click onSlash "https://github.com/juddisjudd/oxbot/blob/master/src/events/onSlashCommand.ts"
    click onMemberJoin "https://github.com/juddisjudd/oxbot/blob/master/src/events/onMemberJoin.ts"
    click onMemberLeave "https://github.com/juddisjudd/oxbot/blob/master/src/events/onMemberLeave.ts"
    click onMemberKick "https://github.com/juddisjudd/oxbot/blob/master/src/events/onMemberKick.ts"
    click onMemberBan "https://github.com/juddisjudd/oxbot/blob/master/src/events/onMemberBan.ts"
    click onMemberUnban "https://github.com/juddisjudd/oxbot/blob/master/src/events/onMemberUnban.ts"
    click onMemberRole "https://github.com/juddisjudd/oxbot/blob/master/src/events/onMemberRoleUpdate.ts"
    click onMemberWarn "https://github.com/juddisjudd/oxbot/blob/master/src/events/onMemberWarn.ts"
    click onMsgDelete "https://github.com/juddisjudd/oxbot/blob/master/src/events/onMessageDelete.ts"
    click onPurge "https://github.com/juddisjudd/oxbot/blob/master/src/events/onPurge.ts"
    click CmdHandler "https://github.com/juddisjudd/oxbot/blob/master/src/handlers/commandHandler.ts"
    click RespHandler "https://github.com/juddisjudd/oxbot/blob/master/src/handlers/botResponsesHandler.ts"
    click Interface "https://github.com/juddisjudd/oxbot/blob/master/src/interfaces/command.ts"
    click fun "https://github.com/juddisjudd/oxbot/blob/master/src/commands/fun/coinflip.ts"
    click misc "https://github.com/juddisjudd/oxbot/blob/master/src/commands/misc/ping.ts"
    click mod "https://github.com/juddisjudd/oxbot/blob/master/src/commands/moderation/ban.ts"
    click ox "https://github.com/juddisjudd/oxbot/blob/master/src/commands/ox/ox.ts"
    click Env "https://github.com/juddisjudd/oxbot/blob/master/src/config.ts"
    click Constants "https://github.com/juddisjudd/oxbot/blob/master/src/constants.ts"
    click Utils "https://github.com/juddisjudd/oxbot/blob/master/src/utils/logger.ts"
    click Schema "https://github.com/juddisjudd/oxbot/blob/master/prisma/schema.prisma"
    click Migrations "https://github.com/juddisjudd/oxbot/tree/master/prisma/migrations/"
    click CI "https://github.com/juddisjudd/oxbot/blob/master/.github/workflows/docker-push.yml"

    %% Styles
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px
    classDef app fill:#b3d1ff,stroke:#333,stroke-width:1px
    classDef database fill:#b3ffb3,stroke:#333,stroke-width:1px
    classDef infra fill:#ffcc99,stroke:#333,stroke-width:1px
```
