# sd-ct7/ctgp-7_time_trials_bot architecture

> Architecture diagram of the GitHub repository sd-ct7/ctgp-7_time_trials_bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sd-ct7/ctgp-7_time_trials_bot
- Repository: https://github.com/sd-ct7/ctgp-7_time_trials_bot

## Overview

This is a Discord bot for submitting and approving Mario Kart time-trial records, managing leaderboard roles, and logging approvals. Discord interactions enter through the worker handler, which dispatches commands; submissions extract and validate proof details before sending records to the GAS backend, while staff approval reads submission messages and updates records. A separate role-setup route applies ranks from a ranking snapshot. The README is empty, so capabilities and relationships here are based on the supplied source excerpts and SOURCE INDEX; the registration command implementation is present in the tree but its wiring is not shown.

Main entry points: [`src/index.js`](https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/index.js) (Request router), [`src/commands/rsubmit.js`](https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/commands/rsubmit.js) (Record submission), [`src/lib/discord.js`](https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/lib/discord.js) (Discord helpers), [`src/lib/gas.js`](https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/lib/gas.js) (GAS client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Worker entry"]
  node_worker["Request router<br/>[index.js]"]
end

subgraph group_commands["Record commands"]
  node_submit["Record submission<br/>[rsubmit.js]"]
  node_approve["Record approval<br/>[approve.js]"]
  node_remove["Remove error message<br/>[removeerror.js]"]
  node_roles_setup["Role setup<br/>[setupRoles.js]"]
  node_registration["Command registration<br/>[register.js]"]
end

subgraph group_services["Domain services"]
  node_discord_helpers["Discord helpers<br/>[discord.js]"]
  node_parser["Submission parsing<br/>[parser.js]"]
  node_track_catalog["Track catalog<br/>[tracks.js]"]
  node_youtube_title["YouTube title lookup<br/>[youtube.js]"]
  node_gas_client["GAS client<br/>[gas.js]"]
  node_approval_log["Approval logging<br/>[log.js]"]
  node_date["Paris date helper<br/>[date.js]"]
  node_role_logic["Ranking role logic<br/>[roles.js]"]
end

subgraph group_integrations["External systems"]
  node_discord_api["Discord API"]
  node_gas_backend["GAS backend"]
  node_ranking_service["Ranking snapshot"]
  node_supabase[("Supabase tracks")]
  node_youtube["YouTube oEmbed"]
end

node_discord_user(("Discord user"))

node_discord_user -->|"sends interactions"| node_worker
node_worker -->|"verifies requests"| node_discord_helpers
node_worker -->|"dispatches command"| node_submit
node_worker -->|"dispatches command"| node_approve
node_worker -->|"dispatches command"| node_remove
node_worker -->|"routes setup"| node_roles_setup
node_worker -->|"checks milestones"| node_gas_client
node_worker -->|"sends followup"| node_discord_helpers
node_submit -->|"loads tracks"| node_track_catalog
node_submit -->|"finds proof message"| node_discord_helpers
node_submit -->|"extracts details"| node_parser
node_submit -->|"looks up title"| node_youtube_title
node_submit -->|"checks and submits"| node_gas_client
node_submit -->|"logs auto-approval"| node_approval_log
node_approve -->|"fetches submission"| node_discord_helpers
node_approve -->|"parses embed"| node_parser
node_approve -->|"approves record"| node_gas_client
node_approve -->|"logs approval"| node_approval_log
node_remove -->|"checks staff"| node_gas_client
node_remove -->|"fetches message"| node_discord_helpers
node_roles_setup -->|"fetches snapshot"| node_ranking_service
node_roles_setup -->|"gets player mapping"| node_gas_client
node_roles_setup -->|"updates ranking roles"| node_role_logic
node_roles_setup -->|"sends announcements"| node_discord_helpers
node_discord_helpers -->|"calls endpoints"| node_discord_api
node_role_logic -->|"updates member roles"| node_discord_api
node_gas_client -->|"sends actions"| node_gas_backend
node_track_catalog -->|"loads tracks"| node_supabase
node_youtube_title -->|"fetches oEmbed title"| node_youtube
node_approval_log -->|"formats date"| node_date
node_approval_log -->|"posts log"| node_discord_api

click node_worker "https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/index.js"
click node_submit "https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/commands/rsubmit.js"
click node_approve "https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/commands/approve.js"
click node_remove "https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/commands/removeerror.js"
click node_roles_setup "https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/commands/setupRoles.js"
click node_registration "https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/commands/register.js"
click node_discord_helpers "https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/lib/discord.js"
click node_parser "https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/lib/parser.js"
click node_track_catalog "https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/lib/tracks.js"
click node_youtube_title "https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/lib/youtube.js"
click node_gas_client "https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/lib/gas.js"
click node_approval_log "https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/lib/log.js"
click node_date "https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/lib/date.js"
click node_role_logic "https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/lib/roles.js"

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_worker,node_discord_user toneBlue
class node_submit,node_approve,node_remove,node_roles_setup,node_registration toneAmber
class node_discord_helpers,node_parser,node_track_catalog,node_youtube_title,node_gas_client,node_approval_log,node_date,node_role_logic toneMint
class node_discord_api,node_gas_backend,node_ranking_service,node_supabase,node_youtube toneRose
```

## Components

### Worker entry

- [Request router](https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/index.js): `src/index.js`

### Record commands

- [Record submission](https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/commands/rsubmit.js): `src/commands/rsubmit.js`
- [Record approval](https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/commands/approve.js): `src/commands/approve.js`
- [Remove error message](https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/commands/removeerror.js): `src/commands/removeerror.js`
- [Role setup](https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/commands/setupRoles.js): `src/commands/setupRoles.js`
- [Command registration](https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/commands/register.js): `src/commands/register.js`

### Domain services

- [Discord helpers](https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/lib/discord.js): `src/lib/discord.js`
- [Submission parsing](https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/lib/parser.js): `src/lib/parser.js`
- [Track catalog](https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/lib/tracks.js): `src/lib/tracks.js`
- [YouTube title lookup](https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/lib/youtube.js): `src/lib/youtube.js`
- [GAS client](https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/lib/gas.js): `src/lib/gas.js`
- [Approval logging](https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/lib/log.js): `src/lib/log.js`
- [Paris date helper](https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/lib/date.js): `src/lib/date.js`
- [Ranking role logic](https://github.com/sd-ct7/ctgp-7_time_trials_bot/blob/main/src/lib/roles.js): `src/lib/roles.js`

### External systems

- **Discord API**
- **GAS backend**
- **Ranking snapshot**
- **Supabase tracks**
- **YouTube oEmbed**

### Other components

- **Discord user**

## Connections

- Discord user → Request router: sends interactions (evidence: `src/index.js`)
- Request router → Discord helpers: verifies requests (evidence: `src/index.js`)
- Request router → Record submission: dispatches command (evidence: `src/index.js`)
- Request router → Record approval: dispatches command (evidence: `src/index.js`)
- Request router → Remove error message: dispatches command (evidence: `src/index.js`)
- Request router → Role setup: routes setup (evidence: `src/index.js`)
- Request router → GAS client: checks milestones (evidence: `src/index.js`)
- Request router → Discord helpers: sends followup (evidence: `src/index.js`)
- Record submission → Track catalog: loads tracks (evidence: `src/commands/rsubmit.js`)
- Record submission → Discord helpers: finds proof message (evidence: `src/commands/rsubmit.js`)
- Record submission → Submission parsing: extracts details (evidence: `src/commands/rsubmit.js`)
- Record submission → YouTube title lookup: looks up title (evidence: `src/commands/rsubmit.js`)
- Record submission → GAS client: checks and submits (evidence: `src/commands/rsubmit.js`)
- Record submission → Approval logging: logs auto-approval (evidence: `src/commands/rsubmit.js`)
- Record approval → Discord helpers: fetches submission (evidence: `src/commands/approve.js`)
- Record approval → Submission parsing: parses embed (evidence: `src/commands/approve.js`)
- Record approval → GAS client: approves record (evidence: `src/commands/approve.js`)
- Record approval → Approval logging: logs approval (evidence: `src/commands/approve.js`)
- Remove error message → GAS client: checks staff (evidence: `src/commands/removeerror.js`)
- Remove error message → Discord helpers: fetches message (evidence: `src/commands/removeerror.js`)
- Role setup → Ranking snapshot: fetches snapshot (evidence: `src/commands/setupRoles.js`)
- Role setup → GAS client: gets player mapping (evidence: `src/commands/setupRoles.js`)
- Role setup → Ranking role logic: updates ranking roles (evidence: `src/commands/setupRoles.js`)
- Role setup → Discord helpers: sends announcements (evidence: `src/commands/setupRoles.js`)
- Discord helpers → Discord API: calls endpoints (evidence: `src/lib/discord.js`)
- Ranking role logic → Discord API: updates member roles (evidence: `src/lib/roles.js`)
- GAS client → GAS backend: sends actions (evidence: `src/lib/gas.js`)
- Track catalog → Supabase tracks: loads tracks (evidence: `src/lib/tracks.js`)
- YouTube title lookup → YouTube oEmbed: fetches oEmbed title (evidence: `src/lib/youtube.js`)
- Approval logging → Paris date helper: formats date (evidence: `src/lib/log.js`)
- Approval logging → Discord API: posts log (evidence: `src/lib/log.js`)
