# usnofsot/paul architecture

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

- Interactive diagram: https://gitdiagram.com/usnofsot/paul
- Repository: https://github.com/usnofsot/paul

## Overview

##### Project type and purpose
- This is a Python-based Discord bot (“Paul”) that manages sailor records for a Sea of Thieves community server.
- It connects to Discord’s Gateway/API, listens to events, executes command “cogs” (plugins), applies business logic, and reads/writes to a database via ORM/repositories.

##### File structure
- Top-level:
- src/main.py → entry point
- src/core/bot.py → Bot startup, loads cogs
- src/cogs/… → Commands (slash‐commands) and event handlers, organized by category
- src/data/… → SQLAlchemy engine, Alembic migrations, models.py, repository pattern
- src/utils/… → Business logic helpers, Discord embed builders, logging, report utilities
- src/config/… → Static lookup tables (ranks, emojis, servers, synonyms)
- Config & deployment:
- .env for Discord token, DB settings
- alembic.ini + migrations for database schema
- GitHub Actions CI workflow

##### README for insights
- Bot startup sequence: main.py → core.bot → loads cogs → connects to Discord
- Workflow: virtualenv, env vars, PYTHONPATH
- Cogs are plug-ins: commands (commandsync) and event listeners (on_message, on_ready, etc.)

##### Sketch the main components
a. Discord Platform (Discord Gateway / REST API)
b. Bot Runtime (hosted environment / container / VM)
- Entry Point: main.py
- Bot Core: core/bot.py (loads extensions)
- Cog Layer: src/cogs (commands & events)
- Utils Layer: src/utils (business logic, formatting)
- Config Layer: src/config (static enums, mapping files)
- Data Layer: src/data
- Engine (SQLAlchemy)
- Migrations (Alembic)
- Models & Schemas
- Repositories (CRUD interfaces)
c. External Database (PostgreSQL/MySQL)
d. GitHub / CI (for completeness: source repo → CI workflow → deployments)

##### Relationships and interactions
- Discord → (WebSocket events) → core.bot.on_ready / on_message → dispatch to cogs/events
- User issues slash-command → Discord REST → Gateway event → command handler in cog
- Command handler → calls utils or repository through service layer
- Repository → ORM → Database
- Database → returns data → repository → command → Discord embed via utils → REST reply back to Discord
- Config modules are injected into cogs/utils for static data
- Logging utility writes logs to console or file

##### Architectural patterns & principles
- Plugin architecture (Discord.py cogs as interchangeable modules)
- Repository pattern for data access, decoupling business logic from ORM
- Layered design: Presentation (Discord events/commands), Business (utils), Data (repositories/models)
- Migrations for evolving schema (Alembic)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    Discord["Discord Gateway & REST API"]:::external
    Database["External Database\n(PostgreSQL/MySQL)"]:::external
    CI["GitHub Actions CI"]:::external

    %% Bot Runtime
    subgraph "Bot Runtime"
        direction TB
        Entry["Entry Point\nmain.py"]:::code
        Core["Bot Core\ncore/bot.py"]:::code

        subgraph "Cogs Layer"
            direction TB
            Commands["Commands\nsrc/cogs/commands"]:::code
            Events["Events\nsrc/cogs/events"]:::code
            Tasks["Scheduled Tasks\nsrc/cogs/tasks"]:::code
        end

        subgraph "Utils Layer"
            direction TB
            Utils["Utils\nsrc/utils"]:::utils
        end

        subgraph "Config Layer"
            direction TB
            Abbrev["abbreviations.py"]:::config
            Awards["awards.py"]:::config
            Emojis["emojis.py"]:::config
            MainSrv["main_server.py"]:::config
            Netc["netc_server.py"]:::config
            Ranks["ranks.py"]:::config
            Roles["ranks_roles.py"]:::config
            Req["requirements.py"]:::config
            ShipRoles["ship_roles.py"]:::config
            Ships["ships.py"]:::config
            SPD["spd_servers.py"]:::config
            Subcls["subclasses.py"]:::config
            Synonyms["synonyms.py"]:::config
            TrainingCfg["training.py"]:::config
        end

        subgraph "Data Layer"
            direction TB
            Engine["Engine\nengine.py"]:::data
            Migrations["Migrations\nmigrations/"]:::data
            Models["Models & Schemas\nmodels.py"]:::data
            Report["Report Utilities\nreport.py"]:::data

            subgraph "Repositories"
                direction TB
                BaseRepo["base_repository.py"]:::data
                AuditRepo["auditlog_repository.py"]:::data
                CoinRepo["coin_repository.py"]:::data
                ForceRepo["forceadd_repository.py"]:::data
                HostedRepo["hosted_repository.py"]:::data
                ModNoteRepo["modnote_repository.py"]:::data
                SailorRepo["sailor_repository.py"]:::data
                ShipRepo["ship_repository.py"]:::data
                SubclassRepo["subclass_repository.py"]:::data
                TrainingRepo["training_records_repository.py"]:::data
                VoyageRepo["voyage_repository.py"]:::data
                InitRepo["__init__.py"]:::data
            end

            Structs["Data Structs\nstructs.py"]:::data
        end
    end

    %% Environment & Config
    Env["Environment Vars\n.env.example"]:::config
    Alembic["alembic.ini"]:::config
    Docs["Documentation\ndocs/"]:::external

    %% Connections
    Discord -->|"WebSocket Events"| Core
    Core -->|"loads cogs"| Commands
    Core --> Commands
    Core --> Events
    Core --> Tasks
    Commands -->|"calls util"| Utils
    Events --> Utils
    Tasks --> Utils
    Commands -->|"uses repositories"| SailorRepo
    Events --> HostedRepo
    Tasks --> VoyageRepo
    SailorRepo -->|query/insert| Database
    HostedRepo --> Database
    VoyageRepo --> Database
    Utils -->|"REST reply (embed)"| Discord
    Entry --> Core
    Entry --> Env
    Entry --> Alembic
    Entry --> Engine
    Core --> Abbrev & Awards & Emojis & MainSrv & Netc & Ranks & Roles & Req & ShipRoles & Ships & SPD & Subcls & Synonyms & TrainingCfg
    Commands & Events & Tasks --> Abbrev

    Engine --> Migrations
    Migrations --> Alembic

    CI --> Entry
    CI --> Migrations
    Docs --> Entry

    %% Click Events
    click Entry "https://github.com/usnofsot/paul/blob/main/src/main.py"
    click Core "https://github.com/usnofsot/paul/blob/main/src/core/bot.py"
    click Commands "https://github.com/usnofsot/paul/tree/main/src/cogs/commands"
    click Events "https://github.com/usnofsot/paul/tree/main/src/cogs/events"
    click Tasks "https://github.com/usnofsot/paul/tree/main/src/cogs/tasks"
    click Utils "https://github.com/usnofsot/paul/tree/main/src/utils"
    click Abbrev "https://github.com/usnofsot/paul/blob/main/src/config/abbreviations.py"
    click Awards "https://github.com/usnofsot/paul/blob/main/src/config/awards.py"
    click Emojis "https://github.com/usnofsot/paul/blob/main/src/config/emojis.py"
    click MainSrv "https://github.com/usnofsot/paul/blob/main/src/config/main_server.py"
    click Netc "https://github.com/usnofsot/paul/blob/main/src/config/netc_server.py"
    click Ranks "https://github.com/usnofsot/paul/blob/main/src/config/ranks.py"
    click Roles "https://github.com/usnofsot/paul/blob/main/src/config/ranks_roles.py"
    click Req "https://github.com/usnofsot/paul/blob/main/src/config/requirements.py"
    click ShipRoles "https://github.com/usnofsot/paul/blob/main/src/config/ship_roles.py"
    click Ships "https://github.com/usnofsot/paul/blob/main/src/config/ships.py"
    click SPD "https://github.com/usnofsot/paul/blob/main/src/config/spd_servers.py"
    click Subcls "https://github.com/usnofsot/paul/blob/main/src/config/subclasses.py"
    click Synonyms "https://github.com/usnofsot/paul/blob/main/src/config/synonyms.py"
    click TrainingCfg "https://github.com/usnofsot/paul/blob/main/src/config/training.py"
    click Engine "https://github.com/usnofsot/paul/blob/main/src/data/engine.py"
    click Migrations "https://github.com/usnofsot/paul/tree/main/src/data/migrations"
    click Models "https://github.com/usnofsot/paul/blob/main/src/data/models.py"
    click Report "https://github.com/usnofsot/paul/blob/main/src/data/report.py"
    click BaseRepo "https://github.com/usnofsot/paul/blob/main/src/data/repository/common/base_repository.py"
    click AuditRepo "https://github.com/usnofsot/paul/blob/main/src/data/repository/auditlog_repository.py"
    click CoinRepo "https://github.com/usnofsot/paul/blob/main/src/data/repository/coin_repository.py"
    click ForceRepo "https://github.com/usnofsot/paul/blob/main/src/data/repository/forceadd_repository.py"
    click HostedRepo "https://github.com/usnofsot/paul/blob/main/src/data/repository/hosted_repository.py"
    click ModNoteRepo "https://github.com/usnofsot/paul/blob/main/src/data/repository/modnote_repository.py"
    click SailorRepo "https://github.com/usnofsot/paul/blob/main/src/data/repository/sailor_repository.py"
    click ShipRepo "https://github.com/usnofsot/paul/blob/main/src/data/repository/ship_repository.py"
    click SubclassRepo "https://github.com/usnofsot/paul/blob/main/src/data/repository/subclass_repository.py"
    click TrainingRepo "https://github.com/usnofsot/paul/blob/main/src/data/repository/training_records_repository.py"
    click VoyageRepo "https://github.com/usnofsot/paul/blob/main/src/data/repository/voyage_repository.py"
    click InitRepo "https://github.com/usnofsot/paul/blob/main/src/data/repository/__init__.py"
    click Structs "https://github.com/usnofsot/paul/blob/main/src/data/structs.py"
    click Env "https://github.com/usnofsot/paul/blob/main/.env.example"
    click Alembic "https://github.com/usnofsot/paul/blob/main/alembic.ini"
    click CI "https://github.com/usnofsot/paul/blob/main/.github/workflows/ci.yaml"
    click Docs "https://github.com/usnofsot/paul/blob/main/docs/architecture.md"

    %% Styles
    classDef external fill:#fde2e2,stroke:#c30000
    classDef code fill:#e0f7fa,stroke:#006064
    classDef data fill:#e8f5e9,stroke:#1b5e20
    classDef config fill:#f3e5f5,stroke:#4a148c
    classDef utils fill:#fff3e0,stroke:#e65100
    class Entry,Core,Commands,Events,Tasks code
    class Utils utils
    class Engine,Migrations,Models,Report,BaseRepo,AuditRepo,CoinRepo,ForceRepo,HostedRepo,ModNoteRepo,SailorRepo,ShipRepo,SubclassRepo,TrainingRepo,VoyageRepo,Structs data
    class Abbrev,Awards,Emojis,MainSrv,Netc,Ranks,Roles,Req,ShipRoles,Ships,SPD,Subcls,Synonyms,TrainingCfg,Env,Alembic config
```
