# sabafly/gobot architecture

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

- Interactive diagram: https://gitdiagram.com/sabafly/gobot
- Repository: https://github.com/sabafly/gobot

## Overview

##### Project Type and Purpose
- gobot is a Discord bot application.
- It listens for events from the Discord Gateway, dispatches them to command handlers, applies business logic (e.g. leveling, role panels, games), and persists data to a MySQL database via the Ent ORM.
- It is packaged as a Dockerized service (the “gobot” container) alongside a MySQL container in docker-compose.

##### File Structure
- Top-level:
– main.go and cmd/root.go: bootstrap the application and CLI flags.
– bot/: command and component definitions.
– internal/: utility packages (i18n, parsing, permissions, rate-limiting, etc.).
– ent/: generated ORM code and schema, plus migration logic.
– database/: abstraction over storage (memory or SQL).
– mysql/: Dockerfile and init scripts for the database.
– Dockerfile, docker-compose.yml: container definitions.
– .github/workflows: CI, linting, security scans.
- Patterns:
– Layered architecture: event ingestion → command dispatch → business logic → persistence.
– Hexagonal flavor: “bot/components” define ports/adapters for Discord, “internal” contains core utilities.

##### README for Insights
- Confirms it’s a multi-feature Discord bot under active development.
- Mentions localization via Crowdin (lang/ and locales/ directories).
- CI badges indicate GitHub Actions pipelines for build and security.

##### Main Components
a. Discord Platform (Gateway API)
b. gobot Service:
– Event Listener (DiscordGo wrapper)
– Command Dispatcher (bot/components/commands.go)
– Command Handlers (bot/commands/*): debug, play, level, role, etc.
– Core Services (internal/*): i18n, rate-limit, permissions, scheduler, translation, UUID, xp calculation.
– Database Abstraction (database/ + memory.go)
– Ent ORM Client (ent/client.go + ent/migrate)
c. MySQL Database (mysql container via docker-compose)
d. External Services:
– Localization (Crowdin integration, lang/*.yaml)
– CI/CD (GitHub Actions workflows)

##### Relationships and Interactions
1. Discord Gateway emits events → gobot’s Event Listener
2. Events → Command Dispatcher → Specific Command Handler
3. Command invokes Core Service(s) for business logic
4. If persistence is needed: Service calls Database Abstraction → Ent ORM → MySQL
5. Responses (embeds, messages) flow back through Discord API to the user
6. Localization subsystem resolves strings via lang/ and locales/

##### Architectural Patterns and Design Principles
- Layered architecture: clearly separate I/O (Discord, DB) from business logic.
- Hexagonal/adapters: “internal” as core logic, “bot/components” and “database” as ports/adapters.
- Code generation: Ent provides schema-first ORM and migrations.
- Dependency injection via simple constructors in bot/components/config.go.

##### Technologies, Frameworks, Libraries
- Go + DiscordGo library
- Ent ORM for type-safe database access
- MySQL as persistent store
- Docker & Docker Compose for containerization
- GitHub Actions for CI/CD
- Crowdin for localization

##### Detail Without Overthinking
- Every high-level component listed above.
- Startup flow (main.go → config → connect to Discord & MySQL → migrate schemas → start event loop).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    Discord["Discord Gateway"]:::external
    Localization["Localization (Crowdin)"]:::external
    CI["CI/CD (GitHub Actions)"]:::external

    %% gobot Container
    subgraph "gobot Container"
        direction TB

        Main["Bootstrap\nmain.go\ncmd/root.go"]:::adapter
        EventListener["Event Listener\n(bot/bot.go)"]:::adapter
        Dispatcher["Command Dispatcher\n(bot/components/commands.go)"]:::adapter

        subgraph "Command Handlers"
            direction TB
            Debug["debug.go"]:::adapter
            GoPoint["gopoint.go"]:::adapter
            Level1["level.go"]:::adapter
            Level2["level_message.go"]:::adapter
            Level3["mee6.go"]:::adapter
            Message1["message.go"]:::adapter
            Message2["text_command.go"]:::adapter
            PermissionCmd["permission.go"]:::adapter
            Ping["ping.go"]:::adapter
            Play1["command.go"]:::adapter
            Play2["bet.go"]:::adapter
            Play3["hal.go"]:::adapter
            Role1["role.go"]:::adapter
            Role2["panel.go"]:::adapter
            Role3["panel_message.go"]:::adapter
            Role4["panel_autocomplete.go"]:::adapter
            Role5["import.go"]:::adapter
            Setting["setting.go"]:::adapter
        end

        subgraph "Core Services"
            direction TB
            I18n["i18n"]:::core
            Ratelimit["ratelimit"]:::core
            Permissions["permissions"]:::core
            ParseTime["parse/time"]:::core
            TranslateSvc["translate"]:::core
            UUID["uuidv7"]:::core
            XP["xppoint"]:::core
            DiscordUtil["discordutil"]:::core
            Embeds["embeds"]:::core
            Scheduler["scheduler"]:::core
        end

        DatabaseAbstraction["Database Abstraction\n(database/database.go\nmemory.go)"]:::adapter
        EntClient["Ent ORM Client\n(ent/client.go\nent/ent.go\nmigrate)"]:::adapter
    end

    MySQL["MySQL Database"]:::database

    %% Data Flows
    Discord -->|events| EventListener
    EventListener -->|dispatch| Dispatcher
    Dispatcher --> Debug
    Dispatcher --> GoPoint
    Dispatcher --> Level1
    Dispatcher --> Level2
    Dispatcher --> Level3
    Dispatcher --> Message1
    Dispatcher --> Message2
    Dispatcher --> PermissionCmd
    Dispatcher --> Ping
    Dispatcher --> Play1
    Dispatcher --> Play2
    Dispatcher --> Play3
    Dispatcher --> Role1
    Dispatcher --> Role2
    Dispatcher --> Role3
    Dispatcher --> Role4
    Dispatcher --> Role5
    Dispatcher --> Setting

    Debug --> I18n
    GoPoint --> XP
    Level1 --> XP
    Level2 --> XP
    Level3 --> XP
    Message1 --> ParseTime
    Message2 --> TranslateSvc
    PermissionCmd --> Permissions
    Ping --> UUID
    Play1 --> Scheduler
    Play2 --> Scheduler
    Play3 --> Scheduler
    Role1 --> DiscordUtil
    Role2 --> DiscordUtil
    Role3 --> DiscordUtil
    Role4 --> DiscordUtil
    Role5 --> DiscordUtil
    Setting --> Ratelimit

    I18n --> DatabaseAbstraction
    Ratelimit --> DatabaseAbstraction
    Permissions --> DatabaseAbstraction
    ParseTime --> DatabaseAbstraction
    TranslateSvc --> DatabaseAbstraction
    UUID --> DatabaseAbstraction
    XP --> DatabaseAbstraction
    DiscordUtil --> DatabaseAbstraction
    Embeds --> DatabaseAbstraction
    Scheduler --> DatabaseAbstraction

    DatabaseAbstraction --> EntClient
    EntClient --> MySQL

    Debug -->|response| Discord
    GoPoint -->|response| Discord
    Level1 -->|response| Discord
    Message1 -->|response| Discord

    Localization -->|resources| I18n
    CI -->|build| Main

    %% Click Events
    click Main "https://github.com/sabafly/gobot/blob/develop/cmd/root.go"
    click EventListener "https://github.com/sabafly/gobot/blob/develop/bot/bot.go"
    click Dispatcher "https://github.com/sabafly/gobot/blob/develop/bot/components/commands.go"
    click Debug "https://github.com/sabafly/gobot/blob/develop/bot/commands/debug/debug.go"
    click GoPoint "https://github.com/sabafly/gobot/blob/develop/bot/commands/gopoint/gopoint.go"
    click Level1 "https://github.com/sabafly/gobot/blob/develop/bot/commands/level/level.go"
    click Level2 "https://github.com/sabafly/gobot/blob/develop/bot/commands/level/level_message.go"
    click Level3 "https://github.com/sabafly/gobot/blob/develop/bot/commands/level/mee6.go"
    click Message1 "https://github.com/sabafly/gobot/blob/develop/bot/commands/message/message.go"
    click Message2 "https://github.com/sabafly/gobot/blob/develop/bot/commands/message/text_command.go"
    click PermissionCmd "https://github.com/sabafly/gobot/blob/develop/bot/commands/permission/permission.go"
    click Ping "https://github.com/sabafly/gobot/blob/develop/bot/commands/ping/ping.go"
    click Play1 "https://github.com/sabafly/gobot/blob/develop/bot/commands/play/command.go"
    click Play2 "https://github.com/sabafly/gobot/blob/develop/bot/commands/play/bet.go"
    click Play3 "https://github.com/sabafly/gobot/blob/develop/bot/commands/play/hal.go"
    click Role1 "https://github.com/sabafly/gobot/blob/develop/bot/commands/role/role.go"
    click Role2 "https://github.com/sabafly/gobot/blob/develop/bot/commands/role/panel.go"
    click Role3 "https://github.com/sabafly/gobot/blob/develop/bot/commands/role/panel_message.go"
    click Role4 "https://github.com/sabafly/gobot/blob/develop/bot/commands/role/panel_autocomplete.go"
    click Role5 "https://github.com/sabafly/gobot/blob/develop/bot/commands/role/import.go"
    click Setting "https://github.com/sabafly/gobot/blob/develop/bot/commands/setting/setting.go"
    click I18n "https://github.com/sabafly/gobot/blob/develop/internal/i18n/component.go"
    click Ratelimit "https://github.com/sabafly/gobot/blob/develop/internal/ratelimit/ratelimit.go"
    click Permissions "https://github.com/sabafly/gobot/blob/develop/internal/permissions/permission.go"
    click ParseTime "https://github.com/sabafly/gobot/blob/develop/internal/parse/time.go"
    click TranslateSvc "https://github.com/sabafly/gobot/blob/develop/internal/translate/translate.go"
    click UUID "https://github.com/sabafly/gobot/blob/develop/internal/uuidv7/uuid.go"
    click XP "https://github.com/sabafly/gobot/blob/develop/internal/xppoint/xp.go"
    click DiscordUtil "https://github.com/sabafly/gobot/blob/develop/internal/discordutil/message.go"
    click Embeds "https://github.com/sabafly/gobot/blob/develop/internal/embeds/embed.go"
    click Scheduler "https://github.com/sabafly/gobot/blob/develop/bot/components/scheduler.go"
    click DatabaseAbstraction "https://github.com/sabafly/gobot/blob/develop/database/database.go"
    click EntClient "https://github.com/sabafly/gobot/blob/develop/ent/client.go"
    click MySQL "https://github.com/sabafly/gobot/tree/develop/mysql/Dockerfile"

    %% Styles
    classDef external fill:#E0F7FA,stroke:#006064,color:#006064
    classDef adapter fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef core fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32
    classDef database fill:#ECEFF1,stroke:#546E7A,color:#546E7A
```
