# cycloneaddons/quotient-legacy architecture

> Architecture diagram of the GitHub repository cycloneaddons/quotient-legacy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cycloneaddons/quotient-legacy
- Repository: https://github.com/cycloneaddons/quotient-legacy

## Overview

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: [`src/bot.py`](https://github.com/cycloneaddons/quotient-legacy/blob/main/src/bot.py) (Bot init), [`src/models`](https://github.com/cycloneaddons/quotient-legacy/tree/main/src/models) (ORM models), [`src/core`](https://github.com/cycloneaddons/quotient-legacy/tree/main/src/core) (Core helpers), [`src/cogs/esports`](https://github.com/cycloneaddons/quotient-legacy/tree/main/src/cogs/esports) (Esports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["Runtime surfaces"]
  node_n_start["Start<br/>entrypoint<br/>[start.py]"]
  node_n_botpy["Bot init<br/>bootstrap<br/>[bot.py]"]
  node_n_discord(("Discord API<br/>external platform"))
  node_n_payment["Payment server<br/>http endpoint<br/>[payment.py]"]
  node_n_socketapp["Socket service<br/>realtime server<br/>[app.py]"]
end

subgraph group_grp_bot["Discord bot"]
  node_n_corebot["Bot core<br/>discord wrapper<br/>[Bot.py]"]
  node_n_coreinfra["Core helpers<br/>platform layer"]
  node_n_utils["Utilities<br/>shared helpers"]
end

subgraph group_grp_esports["Esports domain"]
  node_n_esports_root["Esports<br/>feature domain"]
  node_n_esports_events["E-sports handlers<br/>command/event handlers"]
  node_n_esports_views["E-sports UI<br/>discord components"]
  node_n_esports_helpers["E-sports helpers<br/>domain utilities"]
end

subgraph group_grp_others["Supporting features"]
  node_n_cogs_events["Bot events<br/>reactive layer"]
  node_n_cogs_mod["Moderation<br/>admin workflows"]
  node_n_cogs_premium["Premium<br/>access control"]
  node_n_cogs_utility["Utility<br/>guild tools"]
  node_n_cogs_quomisc["Ops tools<br/>internal tooling"]
end

subgraph group_grp_data["Persistence and protocol"]
  node_n_models_root[("ORM models<br/>database layer")]
  node_n_pg[("PostgreSQL<br/>persistent store")]
  node_n_socket_events["Socket events<br/>event protocol"]
  node_n_socket_schemas["Socket schemas<br/>payload contracts"]
end

node_n_start -->|"launches"| node_n_botpy
node_n_botpy -->|"builds"| node_n_corebot
node_n_corebot -->|"uses"| node_n_discord
node_n_botpy -->|"loads"| node_n_cogs_events
node_n_botpy -->|"loads"| node_n_esports_root
node_n_botpy -->|"loads"| node_n_cogs_mod
node_n_botpy -->|"loads"| node_n_cogs_utility
node_n_botpy -->|"loads"| node_n_cogs_premium
node_n_botpy -->|"loads"| node_n_cogs_quomisc
node_n_botpy -->|"starts"| node_n_payment
node_n_botpy -->|"starts"| node_n_socketapp
node_n_cogs_events -->|"uses"| node_n_coreinfra
node_n_cogs_mod -->|"uses"| node_n_coreinfra
node_n_cogs_utility -->|"uses"| node_n_coreinfra
node_n_cogs_premium -->|"uses"| node_n_coreinfra
node_n_esports_root -->|"organizes"| node_n_esports_events
node_n_esports_root -->|"organizes"| node_n_esports_views
node_n_esports_root -->|"organizes"| node_n_esports_helpers
node_n_esports_events -->|"drives"| node_n_esports_views
node_n_esports_events -->|"persists"| node_n_models_root
node_n_esports_views -->|"persists"| node_n_models_root
node_n_esports_helpers -->|"assists"| node_n_models_root
node_n_models_root -->|"stores in"| node_n_pg
node_n_cogs_events -->|"updates"| node_n_models_root
node_n_socketapp -->|"emits"| node_n_socket_events
node_n_socket_events -->|"serializes"| node_n_socket_schemas
node_n_socket_events -->|"reflects"| node_n_models_root
node_n_payment -->|"reads"| node_n_models_root
node_n_coreinfra -->|"builds on"| node_n_utils

click node_n_start "https://github.com/cycloneaddons/quotient-legacy/blob/main/start.py"
click node_n_botpy "https://github.com/cycloneaddons/quotient-legacy/blob/main/src/bot.py"
click node_n_payment "https://github.com/cycloneaddons/quotient-legacy/blob/main/src/server/app/payment.py"
click node_n_socketapp "https://github.com/cycloneaddons/quotient-legacy/blob/main/src/sockets/app/app.py"
click node_n_corebot "https://github.com/cycloneaddons/quotient-legacy/blob/main/src/core/Bot.py"
click node_n_coreinfra "https://github.com/cycloneaddons/quotient-legacy/tree/main/src/core"
click node_n_utils "https://github.com/cycloneaddons/quotient-legacy/tree/main/src/utils"
click node_n_cogs_events "https://github.com/cycloneaddons/quotient-legacy/tree/main/src/cogs/events"
click node_n_cogs_mod "https://github.com/cycloneaddons/quotient-legacy/tree/main/src/cogs/mod"
click node_n_cogs_premium "https://github.com/cycloneaddons/quotient-legacy/tree/main/src/cogs/premium"
click node_n_cogs_utility "https://github.com/cycloneaddons/quotient-legacy/tree/main/src/cogs/utility"
click node_n_cogs_quomisc "https://github.com/cycloneaddons/quotient-legacy/tree/main/src/cogs/quomisc"
click node_n_esports_root "https://github.com/cycloneaddons/quotient-legacy/tree/main/src/cogs/esports"
click node_n_esports_events "https://github.com/cycloneaddons/quotient-legacy/tree/main/src/cogs/esports/events"
click node_n_esports_views "https://github.com/cycloneaddons/quotient-legacy/tree/main/src/cogs/esports/views"
click node_n_esports_helpers "https://github.com/cycloneaddons/quotient-legacy/tree/main/src/cogs/esports/helpers"
click node_n_models_root "https://github.com/cycloneaddons/quotient-legacy/tree/main/src/models"
click node_n_socket_events "https://github.com/cycloneaddons/quotient-legacy/tree/main/src/sockets/events"
click node_n_socket_schemas "https://github.com/cycloneaddons/quotient-legacy/tree/main/src/sockets/schemas"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_start,node_n_botpy,node_n_discord,node_n_payment,node_n_socketapp toneBlue
class node_n_corebot,node_n_coreinfra,node_n_utils toneAmber
class node_n_esports_root,node_n_esports_events,node_n_esports_views,node_n_esports_helpers toneMint
class node_n_cogs_events,node_n_cogs_mod,node_n_cogs_premium,node_n_cogs_utility,node_n_cogs_quomisc toneRose
class node_n_models_root,node_n_pg,node_n_socket_events,node_n_socket_schemas toneIndigo
```

## Components

### Runtime surfaces

Top-level execution and external integration entry points.

- [Start](https://github.com/cycloneaddons/quotient-legacy/blob/main/start.py): entrypoint · Process entry used to launch the application. · `start.py`
- [Bot init](https://github.com/cycloneaddons/quotient-legacy/blob/main/src/bot.py): bootstrap · Main bot launch path and extension wiring. · `src/bot.py`
- **Discord API**: external platform · Discord commands, events, interactions, and component callbacks.
- [Payment server](https://github.com/cycloneaddons/quotient-legacy/blob/main/src/server/app/payment.py): http endpoint · Embedded HTTP surface for payments and gateway callbacks. · `src/server/app/payment.py`
- [Socket service](https://github.com/cycloneaddons/quotient-legacy/blob/main/src/sockets/app/app.py): realtime server · 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](https://github.com/cycloneaddons/quotient-legacy/blob/main/src/core/Bot.py): discord wrapper · Custom bot/client wrapper and shared Discord abstractions. · `src/core/Bot.py`
- [Core helpers](https://github.com/cycloneaddons/quotient-legacy/tree/main/src/core): platform layer · Context, cog base, help behavior, embeds, cache, cooldowns, decorators, and pagination. · `src/core`
- [Utilities](https://github.com/cycloneaddons/quotient-legacy/tree/main/src/utils): shared helpers · 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](https://github.com/cycloneaddons/quotient-legacy/tree/main/src/cogs/esports): feature domain · Main esports application layer for scrims, tournaments, slots, tag checks, and verification. · `src/cogs/esports`
- [E-sports handlers](https://github.com/cycloneaddons/quotient-legacy/tree/main/src/cogs/esports/events): command/event handlers · Domain command entry points and event handlers for esports workflows. · `src/cogs/esports/events`
- [E-sports UI](https://github.com/cycloneaddons/quotient-legacy/tree/main/src/cogs/esports/views): discord components · Interactive views, wizards, paginators, editors, and component-driven workflows. · `src/cogs/esports/views`
- [E-sports helpers](https://github.com/cycloneaddons/quotient-legacy/tree/main/src/cogs/esports/helpers): domain utilities · Converters, image composition, and tournament-specific helper logic. · `src/cogs/esports/helpers`

### Supporting features

Moderation, utility, premium, reminder, and admin workflows.

- [Bot events](https://github.com/cycloneaddons/quotient-legacy/tree/main/src/cogs/events): reactive layer · Global listeners, commands, interactions, logs, votes, and scheduled tasks. · `src/cogs/events`
- [Moderation](https://github.com/cycloneaddons/quotient-legacy/tree/main/src/cogs/mod): admin workflows · Guild lockdown, role management, and moderation UI. · `src/cogs/mod`
- [Premium](https://github.com/cycloneaddons/quotient-legacy/tree/main/src/cogs/premium): access control · Premium lifecycle and premium-facing views. · `src/cogs/premium`
- [Utility](https://github.com/cycloneaddons/quotient-legacy/tree/main/src/cogs/utility): guild tools · Utility events, embed tools, auto-purge, and reminder automation. · `src/cogs/utility`
- [Ops tools](https://github.com/cycloneaddons/quotient-legacy/tree/main/src/cogs/quomisc): internal tooling · Developer helpers, alerts, and miscellaneous operational utilities. · `src/cogs/quomisc`

### Persistence and protocol

Database models plus socket payload contracts.

- [ORM models](https://github.com/cycloneaddons/quotient-legacy/tree/main/src/models): database layer · Tortoise ORM models grouped by esports and miscellaneous domain state. · `src/models`
- **PostgreSQL**: persistent store · Primary persistence backend used through Tortoise ORM.
- [Socket events](https://github.com/cycloneaddons/quotient-legacy/tree/main/src/sockets/events): event protocol · Outbound realtime domain events for guilds, premium, scrims, settings, and tournaments. · `src/sockets/events`
- [Socket schemas](https://github.com/cycloneaddons/quotient-legacy/tree/main/src/sockets/schemas): payload contracts · Structured message schemas for guild, scrim, tournament, and response payloads. · `src/sockets/schemas`

## Connections

- 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.
