How usnofsot/paul works
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)