How cycloneaddons/quotient-legacy works
1. Overall shape
- This is an async Discord bot for esports management, built on Python 3.11 and discord.py 2.0, with PostgreSQL persistence via Tortoise ORM.
- The repository is split into three major runtime surfaces: the Discord bot, a small HTTP server for payments, and a socket/event service for pushing updates to external clients.
2. Entry points and boot flow
- start.py and src/bot.py are the top-level bot launch path.
- src/core/Bot.py appears to wrap the discord.py client and coordinates extension loading, while src/core/Cog.py, Context.py, and Help.py provide shared bot abstractions.
- Startup likely wires together Discord commands, database models, shared caches, and the auxiliary server/socket subsystems.
3. Discord bot as the main orchestration layer
- The src/cogs/ tree is the primary application layer. Each cog is a feature module that owns its own commands, interaction handlers, event listeners, and UI components.
- The bot is organized by domain: esports, events, moderation, premium, utility, reminder, and a few miscellaneous helpers.
4. Esports domain is the largest subsystem
- src/cogs/esports/ contains the core product logic: scrims, tournaments, slot management, tag checking, social screenshot verification, and related workflows.
- It is split into:
- events/ for command/event handlers,
- slash/ for slash-command entry points,
- views/ for interactive Discord UI flows,
- helpers/ for shared logic like image handling, converters, and tournament utilities.
- This domain likely drives most of the bot’s operational load and state transitions.
5. Discord UI is heavily interaction-driven
- The views/ directories contain the stateful user interfaces built with Discord components: buttons, selects, paginated views, and setup/edit wizards.
- Subfolders like scrims, tourney, slotm, ssmod, groupm, points, and smslotlist indicate separate interactive workflows for each esports feature.
- A good architecture diagram should show users interacting with Discord messages/components, which then route back into cog handlers and model updates.
6. Eventing and background jobs
- src/cogs/events/ and src/cogs/utility/events/ contain listeners, scheduled tasks, logging, vote handling, and auto-purge/reminder automation.
- src/cogs/mod/events/ handles guild moderation state such as lockdowns and role updates.
- These modules represent the bot’s reactive layer: Discord events and timers update database state, send notifications, or mutate server configuration without direct user commands.
7. Persistence boundary
- src/models/ is the database layer, organized by domain:
- models/esports/ for scrims, tournaments, reservations, slot management, verification, and points tables,
- models/misc/ for guild config, users, timers, votes, premium, alerts, commands, lockdowns, tags, and related admin data.
- models/helpers/ provides shared field types, validators, and ORM helper functions.
- The main data flow is: Discord interaction → cog/service logic → ORM model → PostgreSQL.
8. Shared core infrastructure
- src/core/ contains reusable bot infrastructure:
- cache and cooldown management,
- decorators and checks,
- embed formatting and pagination helpers,
- custom context and help behavior.
- src/utils/ holds lower-level utilities such as regex, time formatting, inputs, buttons, converters, and exception helpers.
- These modules act as the “platform layer” used by almost every cog, reducing duplication across feature teams.
9. External service surfaces
- src/server/app/payment.py plus src/server/templates/ suggest an embedded HTTP endpoint for payment processing / gateway callbacks.
- src/sockets/app/app.py and src/sockets/events/ define a separate socket-based push/update channel, likely for dashboards or live status propagation.
- src/sockets/schemas/ defines payload contracts for guild, scrim, tournament, and response messages, which implies a structured event protocol between the bot backend and any realtime frontend.
10. Feature-to-integration mapping
- sockets/events/ includes guilds, premium, scrims, settings, tourney, and dashgate, so the socket layer is not generic—it mirrors the bot’s domain objects and exposes state changes outward.
- src/cogs/premium/expire.py and src/models/misc/premium.py indicate premium access is tracked in the database and enforced in bot logic, with expiration likely handled by scheduled tasks.
- src/cogs/mod/ and src/cogs/quomisc/ provide administrative and internal tooling around roles, alerts, development helpers, and operational utilities.
11. Asset and presentation layer
- src/data/ contains fonts and images used by image/composite generation helpers, which matters for diagramming because some bot features are not purely text-based.
- The bot likely generates rich embeds, status panels, verification images, and formatted announcements as part of esports workflows.
- src/core/embeds.py, src/utils/emote.py, and src/cogs/esports/helpers/image.py are the main presentation helpers.
12. How to diagram it
- Draw the bot as the central node with three outbound infrastructure paths:
1. Discord API for commands, events, and component interactions,
2. PostgreSQL via Tortoise ORM for persistent state,
3. HTTP payment server + socket event service for external integrations and realtime updates.
- Around the bot, group the major feature domains: esports operations, moderation/admin, reminders/utility, and premium.
- Inside the esports domain, emphasize the split between handlers, interactive views, and domain models, since that is the most important architectural boundary in this repository.
Main entry points: bot.py Bot init · models ORM models · core Core helpers · esports Esports
Components 21
Runtime surfaces
Top-level execution and external integration entry points.
- Start · Process entry used to launch the application.
start.py - Bot init · Main bot launch path and extension wiring.
src/bot.py - Discord API · Discord commands, events, interactions, and component callbacks.
- Payment server · Embedded HTTP surface for payments and gateway callbacks.
src/server/app/payment.py - Socket service · Socket-based push channel for external clients and dashboards.
src/sockets/app/app.py
Discord bot
Bot bootstrap, shared core, and feature cogs.
- Bot core · Custom bot/client wrapper and shared Discord abstractions.
src/core/Bot.py - Core helpers · Context, cog base, help behavior, embeds, cache, cooldowns, decorators, and pagination.
src/core - Utilities · Lower-level helpers for checks, converters, formatting, inputs, time, regex, and exceptions.
src/utils
Esports domain
Primary product workflows for scrims, tournaments, slots, tags, and verification.
- Esports · Main esports application layer for scrims, tournaments, slots, tag checks, and verification.
src/cogs/esports - E-sports handlers · Domain command entry points and event handlers for esports workflows.
src/cogs/esports/events - E-sports UI · Interactive views, wizards, paginators, editors, and component-driven workflows.
src/cogs/esports/views - E-sports helpers · Converters, image composition, and tournament-specific helper logic.
src/cogs/esports/helpers
Supporting features
Moderation, utility, premium, reminder, and admin workflows.
- Bot events · Global listeners, commands, interactions, logs, votes, and scheduled tasks.
src/cogs/events - Moderation · Guild lockdown, role management, and moderation UI.
src/cogs/mod - Premium · Premium lifecycle and premium-facing views.
src/cogs/premium - Utility · Utility events, embed tools, auto-purge, and reminder automation.
src/cogs/utility - Ops tools · Developer helpers, alerts, and miscellaneous operational utilities.
src/cogs/quomisc
Persistence and protocol
Database models plus socket payload contracts.
- ORM models · Tortoise ORM models grouped by esports and miscellaneous domain state.
src/models - PostgreSQL · Primary persistence backend used through Tortoise ORM.
- Socket events · Outbound realtime domain events for guilds, premium, scrims, settings, and tournaments.
src/sockets/events - Socket schemas · Structured message schemas for guild, scrim, tournament, and response payloads.
src/sockets/schemas
Connections 29
- Start → Bot init: launches · Process startup hands control to the bot bootstrap.
- Bot init → Bot core: builds · Bot bootstrap constructs the custom Discord client wrapper.
- Bot core → Discord API: uses · The bot wrapper sits on top of discord.py.
- Bot init → Bot events: loads · Boot flow registers global event cogs and listeners.
- Bot init → Esports: loads · Boot flow registers the esports feature domain.
- Bot init → Moderation: loads · Boot flow registers moderation features.
- Bot init → Utility: loads · Boot flow registers utility and automation features.
- Bot init → Premium: loads · Boot flow registers premium handling.
- Bot init → Ops tools: loads · Boot flow registers internal tooling cogs.
- Bot init → Payment server: starts · Auxiliary HTTP payment surface is started alongside the bot.
- Bot init → Socket service: starts · Realtime socket service runs as a companion process surface.
- Bot events → Core helpers: uses · Event cogs depend on the shared bot infrastructure.
- Moderation → Core helpers: uses · Moderation workflows use shared context, checks, and views.
- Utility → Core helpers: uses · Utility workflows reuse core helpers and component primitives.
- Premium → Core helpers: uses · Premium flows use shared bot abstractions.
- Esports → E-sports handlers: organizes · Esports domain is split into handler modules.
- Esports → E-sports UI: organizes · Esports domain is split into interactive Discord UIs.
- Esports → E-sports helpers: organizes · Esports domain is split into reusable domain helpers.
- E-sports handlers → E-sports UI: drives · Handlers trigger component-based workflows and edits.
- E-sports handlers → ORM models: persists · Domain handlers read and write persisted esports state.
- E-sports UI → ORM models: persists · Interactive UIs commit user choices and workflow state.
- E-sports helpers → ORM models: assists · Helpers shape and validate domain data before persistence.
- ORM models → PostgreSQL: stores in · ORM models map application state to PostgreSQL.
- Bot events → ORM models: updates · Global events and tasks mutate shared database state.
- Socket service → Socket events: emits · Socket server publishes domain-specific update events.
- Socket events → Socket schemas: serializes · Events use typed payload contracts.
- Socket events → ORM models: reflects · Outbound events mirror persisted guild and esports state.
- Payment server → ORM models: reads · Payment callbacks likely consult account and premium state.
- Core helpers → Utilities: builds on · Core abstractions rely on lower-level utility helpers.