# angle-brackets/rotibot architecture

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

- Interactive diagram: https://gitdiagram.com/angle-brackets/rotibot
- Repository: https://github.com/angle-brackets/rotibot

## Overview

Roti is a Discord bot whose slash-command and message workflows turn server or user requests into replies, generated content, playback, lookups, and usage metrics. The main entry point initializes shared state and storage; feature cogs handle distinct domains, with Supabase backing persistent features and external services powering AI, code execution, and music. The README documents capabilities beyond the sampled excerpts; those feature nodes are retained, but uncertain implementation-level connections are omitted.

Main entry points: [`database/data.py`](https://github.com/angle-brackets/rotibot/blob/main/database/data.py) (Persistent data), [`main.py`](https://github.com/angle-brackets/rotibot/blob/main/main.py) (Roti bot), [`cogs/generate/RotiBrain.py`](https://github.com/angle-brackets/rotibot/blob/main/cogs/generate/RotiBrain.py) (Generation engine), [`cogs/talkbacks/talkback.py`](https://github.com/angle-brackets/rotibot/blob/main/cogs/talkbacks/talkback.py) (Talkbacks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Bot runtime"]
  node_bot["Roti bot<br/>[main.py]"]
end

subgraph group_features["Discord features"]
  node_talkbacks["Talkbacks<br/>[talkback.py]"]
  node_generation["AI generation<br/>[generate.py]"]
  node_music["Music playback<br/>[music.py]"]
  node_quotes["Quotes<br/>[quote.py]"]
  node_settings["Server settings<br/>[settings.py]"]
  node_motd["Personal statuses<br/>[motd.py]"]
  node_wikipedia["Wikipedia lookup<br/>[wikipedia.py]"]
  node_wiz["Wizard101 wiki<br/>[wiz.py]"]
  node_execute["Code execution<br/>[execute.py]"]
  node_help["Help and changelog<br/>[help.py]"]
  node_statistics["Usage statistics<br/>[statistics.py]"]
end

subgraph group_support["Shared services"]
  node_state["Runtime state<br/>[bot_state.py]"]
  node_db[("Persistent data<br/>[data.py]")]
  node_brain["Generation engine<br/>[RotiBrain.py]"]
  node_engine["Execution engine<br/>[ExecutionEngine.py]"]
  node_stat_helpers["Metrics and caching"]
  node_utilities["Bot utilities<br/>[RotiUtilities.py]"]
  node_singleton["Singleton helper<br/>[Singleton.py]"]
end

subgraph group_integrations["External services"]
  node_supabase[("Supabase")]
  node_pollinations["Pollinations API"]
  node_lavalink["Lavalink"]
  node_piston["Piston execution API"]
  node_wizwiki["WizWiki"]
  node_wikipedia_service["Wikipedia"]
end

node_discord(("Discord users"))

node_discord -->|"sends commands"| node_bot
node_bot -->|"initializes"| node_state
node_bot -->|"initializes"| node_db
node_bot -->|"configures logging"| node_utilities
node_talkbacks -->|"replies in chat"| node_discord
node_talkbacks -->|"reads and writes"| node_db
node_talkbacks -->|"generates replies"| node_brain
node_generation -->|"requests generation"| node_brain
node_brain -->|"requests models"| node_pollinations
node_music -->|"controls playback"| node_lavalink
node_music -->|"uses settings"| node_db
node_quotes -->|"reads and writes"| node_db
node_settings -->|"reads and writes"| node_db
node_settings -->|"configures generation"| node_brain
node_motd -->|"stores statuses"| node_db
node_wikipedia -->|"searches articles"| node_wikipedia_service
node_wiz -->|"looks up wiki data"| node_wizwiki
node_execute -->|"runs submitted code"| node_engine
node_engine -->|"executes code"| node_piston
node_engine -->|"records metrics"| node_stat_helpers
node_statistics -->|"gets metrics"| node_stat_helpers
node_stat_helpers -->|"queries usage"| node_db
node_help -->|"uses utilities"| node_utilities
node_db -->|"persists records"| node_supabase
node_db -->|"uses singleton"| node_singleton
node_state -->|"uses singleton"| node_singleton

click node_bot "https://github.com/angle-brackets/rotibot/blob/main/main.py"
click node_state "https://github.com/angle-brackets/rotibot/blob/main/database/bot_state.py"
click node_db "https://github.com/angle-brackets/rotibot/blob/main/database/data.py"
click node_talkbacks "https://github.com/angle-brackets/rotibot/blob/main/cogs/talkbacks/talkback.py"
click node_generation "https://github.com/angle-brackets/rotibot/blob/main/cogs/generate/generate.py"
click node_brain "https://github.com/angle-brackets/rotibot/blob/main/cogs/generate/RotiBrain.py"
click node_music "https://github.com/angle-brackets/rotibot/blob/main/cogs/music/music.py"
click node_quotes "https://github.com/angle-brackets/rotibot/blob/main/cogs/quotes/quote.py"
click node_settings "https://github.com/angle-brackets/rotibot/blob/main/cogs/settings/settings.py"
click node_motd "https://github.com/angle-brackets/rotibot/blob/main/cogs/motd/motd.py"
click node_wikipedia "https://github.com/angle-brackets/rotibot/blob/main/cogs/wiki/wikipedia.py"
click node_wiz "https://github.com/angle-brackets/rotibot/blob/main/cogs/wiz/wiz.py"
click node_execute "https://github.com/angle-brackets/rotibot/blob/main/cogs/execute/execute.py"
click node_engine "https://github.com/angle-brackets/rotibot/blob/main/cogs/execute/ExecutionEngine.py"
click node_help "https://github.com/angle-brackets/rotibot/blob/main/cogs/help/help.py"
click node_statistics "https://github.com/angle-brackets/rotibot/blob/main/cogs/statistics/statistics.py"
click node_stat_helpers "https://github.com/angle-brackets/rotibot/blob/main/cogs/statistics/statistics_helpers.py"
click node_utilities "https://github.com/angle-brackets/rotibot/blob/main/utils/RotiUtilities.py"
click node_singleton "https://github.com/angle-brackets/rotibot/blob/main/utils/Singleton.py"

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_bot,node_discord toneBlue
class node_talkbacks,node_generation,node_music,node_quotes,node_settings,node_motd,node_wikipedia,node_wiz,node_execute,node_help,node_statistics toneAmber
class node_state,node_db,node_brain,node_engine,node_stat_helpers,node_utilities,node_singleton toneMint
class node_supabase,node_pollinations,node_lavalink,node_piston,node_wizwiki,node_wikipedia_service toneRose
```

## Components

### Bot runtime

- [Roti bot](https://github.com/angle-brackets/rotibot/blob/main/main.py): `main.py`

### Discord features

- [Talkbacks](https://github.com/angle-brackets/rotibot/blob/main/cogs/talkbacks/talkback.py): `cogs/talkbacks/talkback.py`
- [AI generation](https://github.com/angle-brackets/rotibot/blob/main/cogs/generate/generate.py): `cogs/generate/generate.py`
- [Music playback](https://github.com/angle-brackets/rotibot/blob/main/cogs/music/music.py): `cogs/music/music.py`
- [Quotes](https://github.com/angle-brackets/rotibot/blob/main/cogs/quotes/quote.py): `cogs/quotes/quote.py`
- [Server settings](https://github.com/angle-brackets/rotibot/blob/main/cogs/settings/settings.py): `cogs/settings/settings.py`
- [Personal statuses](https://github.com/angle-brackets/rotibot/blob/main/cogs/motd/motd.py): `cogs/motd/motd.py`
- [Wikipedia lookup](https://github.com/angle-brackets/rotibot/blob/main/cogs/wiki/wikipedia.py): `cogs/wiki/wikipedia.py`
- [Wizard101 wiki](https://github.com/angle-brackets/rotibot/blob/main/cogs/wiz/wiz.py): `cogs/wiz/wiz.py`
- [Code execution](https://github.com/angle-brackets/rotibot/blob/main/cogs/execute/execute.py): `cogs/execute/execute.py`
- [Help and changelog](https://github.com/angle-brackets/rotibot/blob/main/cogs/help/help.py): `cogs/help/help.py`
- [Usage statistics](https://github.com/angle-brackets/rotibot/blob/main/cogs/statistics/statistics.py): `cogs/statistics/statistics.py`

### Shared services

- [Runtime state](https://github.com/angle-brackets/rotibot/blob/main/database/bot_state.py): `database/bot_state.py`
- [Persistent data](https://github.com/angle-brackets/rotibot/blob/main/database/data.py): `database/data.py`
- [Generation engine](https://github.com/angle-brackets/rotibot/blob/main/cogs/generate/RotiBrain.py): `cogs/generate/RotiBrain.py`
- [Execution engine](https://github.com/angle-brackets/rotibot/blob/main/cogs/execute/ExecutionEngine.py): `cogs/execute/ExecutionEngine.py`
- [Metrics and caching](https://github.com/angle-brackets/rotibot/blob/main/cogs/statistics/statistics_helpers.py): `cogs/statistics/statistics_helpers.py`
- [Bot utilities](https://github.com/angle-brackets/rotibot/blob/main/utils/RotiUtilities.py): `utils/RotiUtilities.py`
- [Singleton helper](https://github.com/angle-brackets/rotibot/blob/main/utils/Singleton.py): `utils/Singleton.py`

### External services

- **Supabase**
- **Pollinations API**
- **Lavalink**
- **Piston execution API**
- **WizWiki**
- **Wikipedia**

### Other components

- **Discord users**

## Connections

- Discord users → Roti bot: sends commands (evidence: `README.md`)
- Roti bot → Runtime state: initializes (evidence: `main.py`)
- Roti bot → Persistent data: initializes (evidence: `main.py`)
- Roti bot → Bot utilities: configures logging (evidence: `main.py`)
- Talkbacks → Discord users: replies in chat (evidence: `README.md`)
- Talkbacks → Persistent data: reads and writes (evidence: `cogs/talkbacks/talkback.py`)
- Talkbacks → Generation engine: generates replies (evidence: `cogs/talkbacks/talkback.py`)
- AI generation → Generation engine: requests generation (evidence: `cogs/generate/generate.py`)
- Generation engine → Pollinations API: requests models (evidence: `cogs/generate/RotiBrain.py`)
- Music playback → Lavalink: controls playback (evidence: `README.md`)
- Music playback → Persistent data: uses settings (evidence: `cogs/music/music.py`)
- Quotes → Persistent data: reads and writes (evidence: `cogs/quotes/quote.py`)
- Server settings → Persistent data: reads and writes (evidence: `cogs/settings/settings.py`)
- Server settings → Generation engine: configures generation (evidence: `cogs/settings/settings.py`)
- Personal statuses → Persistent data: stores statuses (evidence: `cogs/motd/motd.py`)
- Wikipedia lookup → Wikipedia: searches articles (evidence: `README.md`)
- Wizard101 wiki → WizWiki: looks up wiki data (evidence: `README.md`)
- Code execution → Execution engine: runs submitted code (evidence: `cogs/execute/execute.py`)
- Execution engine → Piston execution API: executes code (evidence: `cogs/execute/ExecutionEngine.py`)
- Execution engine → Metrics and caching: records metrics (evidence: `cogs/execute/ExecutionEngine.py`)
- Usage statistics → Metrics and caching: gets metrics (evidence: `cogs/statistics/statistics.py`)
- Metrics and caching → Persistent data: queries usage (evidence: `cogs/statistics/statistics_helpers.py`)
- Help and changelog → Bot utilities: uses utilities (evidence: `cogs/help/help.py`)
- Persistent data → Supabase: persists records (evidence: `database/data.py`)
- Persistent data → Singleton helper: uses singleton (evidence: `database/data.py`)
- Runtime state → Singleton helper: uses singleton (evidence: `database/bot_state.py`)
