# godelfin/pmxbot architecture

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

- Interactive diagram: https://gitdiagram.com/godelfin/pmxbot
- Repository: https://github.com/godelfin/pmxbot

## Overview

pmxbot is a chat bot for IRC and Slack. Messages enter through a platform adapter and reach the bot’s handler/command runtime; commands and phrase handlers produce replies or side effects such as logging, quotes, karma, and image generation. Persisted logs and karma are also reviewed through the web viewer. The graph preserves README capabilities and the indexed command modules; some connections are documented rather than visible in sampled implementation excerpts.

Main entry points: [`pmxbot/commands.py`](https://github.com/godelfin/pmxbot/blob/main/pmxbot/commands.py) (Command handlers), [`pmxbot/images.py`](https://github.com/godelfin/pmxbot/blob/main/pmxbot/images.py) (Image generation), [`pmxbot/core.py`](https://github.com/godelfin/pmxbot/blob/main/pmxbot/core.py) (Handler runtime), [`pmxbot/storage.py`](https://github.com/godelfin/pmxbot/blob/main/pmxbot/storage.py) (Storage backends)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_irc["IRC adapter<br/>[irc.py]"]
  node_slack["Slack adapter<br/>[slack.py]"]
  node_engine["Handler runtime<br/>[core.py]"]
end

subgraph group_features["Bot capabilities"]
  node_commands["Command handlers<br/>[commands.py]"]
  node_phrases["Phrase responses<br/>[phrases.py]"]
  node_quote["Quote libraries<br/>[quotes.py]"]
  node_karma["Karma tracking<br/>[karma.py]"]
  node_music["Music library<br/>[music.py]"]
  node_albums["Album selection<br/>[albums.py]"]
  node_images["Image generation<br/>[images.py]"]
  node_webutil["Web utilities<br/>[util.py]"]
end

subgraph group_persistence["Persistence"]
  node_storage["Storage backends<br/>[storage.py]"]
  node_logs["Message logs<br/>[logging.py]"]
  node_database[("SQLite or MongoDB<br/>[storage.py]")]
end

subgraph group_web["Web viewer"]
  node_viewer["Log and karma viewer<br/>[viewer.py]"]
end

node_user(("Chat user"))
node_openai["OpenAI API"]
node_r2["Cloudflare R2"]

node_user -->|"sends messages"| node_irc
node_user -->|"sends messages"| node_slack
node_irc -->|"dispatches messages"| node_engine
node_slack -->|"dispatches messages"| node_engine
node_engine -->|"registers handlers"| node_commands
node_commands -->|"runs quote commands"| node_quote
node_commands -->|"runs karma commands"| node_karma
node_commands -->|"starts image requests"| node_images
node_commands -->|"uses lookup helpers"| node_webutil
node_commands -->|"uses response phrases"| node_phrases
node_engine -->|"records messages"| node_logs
node_logs -->|"selects backend"| node_storage
node_quote -->|"selects backend"| node_storage
node_karma -->|"selects backend"| node_storage
node_storage -->|"opens configured store"| node_database
node_viewer -->|"reads log history"| node_logs
node_viewer -->|"shows karma"| node_karma
node_commands -.->|"selects music"| node_music
node_images -->|"creates album covers"| node_music
node_images -.->|"uses album selection"| node_albums
node_images -->|"caches image records"| node_database
node_images -->|"requests image"| node_openai
node_images -->|"uploads image"| node_r2

click node_irc "https://github.com/godelfin/pmxbot/blob/main/pmxbot/irc.py"
click node_slack "https://github.com/godelfin/pmxbot/blob/main/pmxbot/slack.py"
click node_engine "https://github.com/godelfin/pmxbot/blob/main/pmxbot/core.py"
click node_commands "https://github.com/godelfin/pmxbot/blob/main/pmxbot/commands.py"
click node_phrases "https://github.com/godelfin/pmxbot/blob/main/pmxbot/phrases.py"
click node_quote "https://github.com/godelfin/pmxbot/blob/main/pmxbot/quotes.py"
click node_karma "https://github.com/godelfin/pmxbot/blob/main/pmxbot/karma.py"
click node_music "https://github.com/godelfin/pmxbot/blob/main/pmxbot/music.py"
click node_albums "https://github.com/godelfin/pmxbot/blob/main/pmxbot/albums.py"
click node_images "https://github.com/godelfin/pmxbot/blob/main/pmxbot/images.py"
click node_webutil "https://github.com/godelfin/pmxbot/blob/main/pmxbot/util.py"
click node_storage "https://github.com/godelfin/pmxbot/blob/main/pmxbot/storage.py"
click node_logs "https://github.com/godelfin/pmxbot/blob/main/pmxbot/logging.py"
click node_database "https://github.com/godelfin/pmxbot/blob/main/pmxbot/storage.py"
click node_viewer "https://github.com/godelfin/pmxbot/blob/main/pmxbot/web/viewer.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_irc,node_slack,node_engine,node_user toneBlue
class node_commands,node_phrases,node_quote,node_karma,node_music,node_albums,node_images,node_webutil toneAmber
class node_storage,node_logs,node_database,node_openai toneMint
class node_viewer toneRose
class node_r2 toneIndigo
```

## Components

### Bot runtime

- [IRC adapter](https://github.com/godelfin/pmxbot/blob/main/pmxbot/irc.py): `pmxbot/irc.py`
- [Slack adapter](https://github.com/godelfin/pmxbot/blob/main/pmxbot/slack.py): `pmxbot/slack.py`
- [Handler runtime](https://github.com/godelfin/pmxbot/blob/main/pmxbot/core.py): `pmxbot/core.py`

### Bot capabilities

- [Command handlers](https://github.com/godelfin/pmxbot/blob/main/pmxbot/commands.py): `pmxbot/commands.py`
- [Phrase responses](https://github.com/godelfin/pmxbot/blob/main/pmxbot/phrases.py): `pmxbot/phrases.py`
- [Quote libraries](https://github.com/godelfin/pmxbot/blob/main/pmxbot/quotes.py): `pmxbot/quotes.py`
- [Karma tracking](https://github.com/godelfin/pmxbot/blob/main/pmxbot/karma.py): `pmxbot/karma.py`
- [Music library](https://github.com/godelfin/pmxbot/blob/main/pmxbot/music.py): `pmxbot/music.py`
- [Album selection](https://github.com/godelfin/pmxbot/blob/main/pmxbot/albums.py): `pmxbot/albums.py`
- [Image generation](https://github.com/godelfin/pmxbot/blob/main/pmxbot/images.py): `pmxbot/images.py`
- [Web utilities](https://github.com/godelfin/pmxbot/blob/main/pmxbot/util.py): `pmxbot/util.py`

### Persistence

- [Storage backends](https://github.com/godelfin/pmxbot/blob/main/pmxbot/storage.py): `pmxbot/storage.py`
- [Message logs](https://github.com/godelfin/pmxbot/blob/main/pmxbot/logging.py): `pmxbot/logging.py`
- [SQLite or MongoDB](https://github.com/godelfin/pmxbot/blob/main/pmxbot/storage.py): `pmxbot/storage.py`

### Web viewer

- [Log and karma viewer](https://github.com/godelfin/pmxbot/blob/main/pmxbot/web/viewer.py): `pmxbot/web/viewer.py`

### Other components

- **Chat user**
- **OpenAI API**
- **Cloudflare R2**

## Connections

- Chat user → IRC adapter: sends messages (evidence: `README.rst`)
- Chat user → Slack adapter: sends messages (evidence: `README.rst`)
- IRC adapter → Handler runtime: dispatches messages (evidence: `pmxbot/irc.py`)
- Slack adapter → Handler runtime: dispatches messages (evidence: `pmxbot/slack.py`)
- Handler runtime → Command handlers: registers handlers (evidence: `pmxbot/commands.py`)
- Command handlers → Quote libraries: runs quote commands (evidence: `pmxbot/commands.py`)
- Command handlers → Karma tracking: runs karma commands (evidence: `pmxbot/commands.py`)
- Command handlers → Image generation: starts image requests (evidence: `pmxbot/commands.py`)
- Command handlers → Web utilities: uses lookup helpers (evidence: `pmxbot/commands.py`)
- Command handlers → Phrase responses: uses response phrases (evidence: `pmxbot/commands.py`)
- Handler runtime → Message logs: records messages (evidence: `pmxbot/core.py`)
- Message logs → Storage backends: selects backend (evidence: `pmxbot/logging.py`)
- Quote libraries → Storage backends: selects backend (evidence: `pmxbot/quotes.py`)
- Karma tracking → Storage backends: selects backend (evidence: `pmxbot/karma.py`)
- Storage backends → SQLite or MongoDB: opens configured store (evidence: `pmxbot/storage.py`)
- Log and karma viewer → Message logs: reads log history (evidence: `README.rst`)
- Log and karma viewer → Karma tracking: shows karma (evidence: `README.rst`)
- Command handlers → Music library: selects music
- Image generation → Music library: creates album covers (evidence: `pmxbot/images.py`)
- Image generation → Album selection: uses album selection (evidence: `pmxbot/images.py`)
- Image generation → SQLite or MongoDB: caches image records (evidence: `README.rst`)
- Image generation → OpenAI API: requests image (evidence: `README.rst`)
- Image generation → Cloudflare R2: uploads image (evidence: `README.rst`)
