# j4spr/ladder_bot architecture

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

- Interactive diagram: https://gitdiagram.com/j4spr/ladder_bot
- Repository: https://github.com/j4spr/ladder_bot

## Overview

Fomranking is a Discord bot for managing game ladders, player standings, challenges, and match results. Users submit slash commands through Discord; the interaction event dispatches them to command handlers, which read and update PostgreSQL and send replies or interactive buttons back through Discord. Moderation commands manage ladder configuration and membership, while player commands cover joining, viewing rankings, challenging, and reporting wins. The tree and sampled handlers support these main flows; unsampled command behavior is represented at its enclosing directory, so finer wiring is not shown.

Main entry points: [`db.js`](https://github.com/j4spr/ladder_bot/blob/main/db.js) (Database adapter), [`main.js`](https://github.com/j4spr/ladder_bot/blob/main/main.js) (Bot startup), [`events/interactionCreate.js`](https://github.com/j4spr/ladder_bot/blob/main/events/interactionCreate.js) (Interaction router), [`commands`](https://github.com/j4spr/ladder_bot/tree/main/commands) (Slash commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_main["Bot startup<br/>[main.js]"]
  node_events["Interaction router"]
  node_commands["Slash commands"]
end

subgraph group_ladder["Ladder management"]
  node_moderation["Ladder administration"]
end

subgraph group_players["Player activity"]
  node_membership["Player membership"]
  node_ranking["Standings display<br/>[ranking.js]"]
  node_challenge["Challenge workflow<br/>[challenge.js]"]
  node_matchresult["Result confirmation<br/>[win.js]"]
end

subgraph group_persistence["Persistence"]
  node_dbmodule["Database adapter<br/>[db.js]"]
  node_postgres[("PostgreSQL")]
end

node_users(("Discord users"))
node_discord{{"Discord platform"}}

node_main -->|"loads handlers"| node_commands
node_main -->|"loads events"| node_events
node_main -->|"registers and logs in"| node_discord
node_discord -->|"delivers interactions"| node_events
node_events -->|"dispatches command"| node_commands
node_users -->|"submits commands"| node_discord
node_commands -->|"replies to user"| node_discord
node_moderation -->|"manages ladder data"| node_dbmodule
node_membership -->|"updates membership"| node_dbmodule
node_ranking -->|"reads standings"| node_dbmodule
node_challenge -->|"records challenge"| node_dbmodule
node_challenge -->|"sends response buttons"| node_discord
node_matchresult -->|"updates match and ranks"| node_dbmodule
node_matchresult -->|"requests confirmation"| node_discord
node_dbmodule -->|"queries and initializes"| node_postgres

click node_main "https://github.com/j4spr/ladder_bot/blob/main/main.js"
click node_events "https://github.com/j4spr/ladder_bot/blob/main/events/interactionCreate.js"
click node_commands "https://github.com/j4spr/ladder_bot/tree/main/commands"
click node_moderation "https://github.com/j4spr/ladder_bot/tree/main/commands/moderation"
click node_membership "https://github.com/j4spr/ladder_bot/tree/main/commands/player"
click node_ranking "https://github.com/j4spr/ladder_bot/blob/main/commands/player/ranking.js"
click node_challenge "https://github.com/j4spr/ladder_bot/blob/main/commands/player/challenge.js"
click node_matchresult "https://github.com/j4spr/ladder_bot/blob/main/commands/player/win.js"
click node_dbmodule "https://github.com/j4spr/ladder_bot/blob/main/db.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_main,node_events,node_commands,node_users toneBlue
class node_moderation toneAmber
class node_membership,node_ranking,node_challenge,node_matchresult toneMint
class node_dbmodule,node_postgres toneRose
class node_discord toneIndigo
```

## Components

### Bot runtime

- [Bot startup](https://github.com/j4spr/ladder_bot/blob/main/main.js): `main.js`
- [Interaction router](https://github.com/j4spr/ladder_bot/blob/main/events/interactionCreate.js): `events/interactionCreate.js`
- [Slash commands](https://github.com/j4spr/ladder_bot/tree/main/commands): `commands`

### Ladder management

- [Ladder administration](https://github.com/j4spr/ladder_bot/tree/main/commands/moderation): `commands/moderation`

### Player activity

- [Player membership](https://github.com/j4spr/ladder_bot/tree/main/commands/player): `commands/player`
- [Standings display](https://github.com/j4spr/ladder_bot/blob/main/commands/player/ranking.js): `commands/player/ranking.js`
- [Challenge workflow](https://github.com/j4spr/ladder_bot/blob/main/commands/player/challenge.js): `commands/player/challenge.js`
- [Result confirmation](https://github.com/j4spr/ladder_bot/blob/main/commands/player/win.js): `commands/player/win.js`

### Persistence

- [Database adapter](https://github.com/j4spr/ladder_bot/blob/main/db.js): `db.js`
- **PostgreSQL**

### Other components

- **Discord users**
- **Discord platform**

## Connections

- Bot startup → Slash commands: loads handlers
- Bot startup → Interaction router: loads events
- Bot startup → Discord platform: registers and logs in
- Discord platform → Interaction router: delivers interactions
- Interaction router → Slash commands: dispatches command
- Discord users → Discord platform: submits commands
- Slash commands → Discord platform: replies to user
- Ladder administration → Database adapter: manages ladder data
- Player membership → Database adapter: updates membership
- Standings display → Database adapter: reads standings
- Challenge workflow → Database adapter: records challenge
- Challenge workflow → Discord platform: sends response buttons
- Result confirmation → Database adapter: updates match and ranks
- Result confirmation → Discord platform: requests confirmation
- Database adapter → PostgreSQL: queries and initializes