# opensourcewinter/sirdeep architecture

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

- Interactive diagram: https://gitdiagram.com/opensourcewinter/sirdeep
- Repository: https://github.com/opensourcewinter/sirdeep

## Overview

SirDeep is a self-hosted Discord community bot. Discord members interact through the bot’s AI chat and controls, while gateway events drive moderation, audit logging, contributor progression/cards, radio playback, and scheduled engineering debates. The README documents main.py as the async client and dispatcher; its source was not sampled, so those dispatch links are documented rather than source-verified. Several capability details likewise come from the README, with unsampled implementation paths represented only where the tree supports them.

Main entry points: [`main.py`](https://github.com/opensourcewinter/sirdeep/blob/main/main.py) (Async Bot Client), [`src/modules/debates/engine.py`](https://github.com/opensourcewinter/sirdeep/blob/main/src/modules/debates/engine.py) (Debate Scheduler), [`src/modules/radio/player.py`](https://github.com/opensourcewinter/sirdeep/blob/main/src/modules/radio/player.py) (Radio Player), [`src/modules/leveling/engine.py`](https://github.com/opensourcewinter/sirdeep/blob/main/src/modules/leveling/engine.py) (XP and Reputation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot Runtime"]
  node_bot["Async Bot Client<br/>[main.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_safety["Safety and Audit"]
  node_audit["Audit Logger<br/>[audit.py]"]
  node_security["Anti-Nuke Sentinel<br/>[security.py]"]
end

subgraph group_community["Community Features"]
  node_aiui["AI Lounge Controls<br/>[view.py]"]
  node_ai["AI Companion<br/>[engine.py]"]
  node_leveling["XP and Reputation<br/>[engine.py]"]
  node_cards["Contributor Card Renderer<br/>[cards.py]"]
  node_debates["Debate Scheduler<br/>[engine.py]"]
end

subgraph group_media["Audio Streaming"]
  node_radio_view["Radio Controls<br/>[view.py]"]
  node_radio["Radio Player<br/>[player.py]"]
end

node_member(("Discord Members"))
node_gateway{{"Discord Gateway"}}
node_ai_services{{"AI Providers"}}
node_debate_pool["Debate Topic Pool<br/>[debates.json]"]
node_ffmpeg{{"FFmpeg"}}
node_discord{{"Discord Services"}}

node_gateway -->|"delivers events"| node_bot
node_member -.->|"interacts"| node_bot
node_bot -.->|"loads settings"| node_config
node_bot -->|"dispatches audit events"| node_audit
node_bot -->|"dispatches safety events"| node_security
node_bot -->|"routes chat"| node_ai
node_bot -.->|"registers controls"| node_aiui
node_aiui -->|"requests profile"| node_leveling
node_ai -->|"sends inference requests"| node_ai_services
node_bot -->|"routes messages"| node_leveling
node_leveling -->|"renders card"| node_cards
node_bot -->|"schedules debates"| node_debates
node_debates -->|"reads topics"| node_debate_pool
node_bot -.->|"registers controls"| node_radio_view
node_radio_view -->|"controls playback"| node_radio
node_radio -->|"transcodes streams"| node_ffmpeg
node_audit -->|"posts audit logs"| node_discord
node_security -->|"quarantines actors"| node_discord
node_debates -->|"posts threads"| node_discord
node_radio -->|"streams to voice"| node_discord
node_cards -->|"fetches avatars"| node_discord

click node_bot "https://github.com/opensourcewinter/sirdeep/blob/main/main.py"
click node_config "https://github.com/opensourcewinter/sirdeep/blob/main/src/core/config.py"
click node_audit "https://github.com/opensourcewinter/sirdeep/blob/main/src/core/audit.py"
click node_security "https://github.com/opensourcewinter/sirdeep/blob/main/src/core/security.py"
click node_aiui "https://github.com/opensourcewinter/sirdeep/blob/main/src/modules/ai/view.py"
click node_ai "https://github.com/opensourcewinter/sirdeep/blob/main/src/modules/ai/engine.py"
click node_leveling "https://github.com/opensourcewinter/sirdeep/blob/main/src/modules/leveling/engine.py"
click node_cards "https://github.com/opensourcewinter/sirdeep/blob/main/src/modules/leveling/cards.py"
click node_debates "https://github.com/opensourcewinter/sirdeep/blob/main/src/modules/debates/engine.py"
click node_debate_pool "https://github.com/opensourcewinter/sirdeep/blob/main/config/debates.json"
click node_radio_view "https://github.com/opensourcewinter/sirdeep/blob/main/src/modules/radio/view.py"
click node_radio "https://github.com/opensourcewinter/sirdeep/blob/main/src/modules/radio/player.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_config toneBlue
class node_audit,node_security toneAmber
class node_aiui,node_ai,node_leveling,node_cards,node_debates toneMint
class node_radio_view,node_radio toneRose
class node_member,node_gateway,node_ai_services,node_ffmpeg,node_discord toneIndigo
class node_debate_pool toneTeal
```

## Components

### Bot Runtime

- [Async Bot Client](https://github.com/opensourcewinter/sirdeep/blob/main/main.py): `main.py`
- [Configuration](https://github.com/opensourcewinter/sirdeep/blob/main/src/core/config.py): `src/core/config.py`

### Safety and Audit

- [Audit Logger](https://github.com/opensourcewinter/sirdeep/blob/main/src/core/audit.py): `src/core/audit.py`
- [Anti-Nuke Sentinel](https://github.com/opensourcewinter/sirdeep/blob/main/src/core/security.py): `src/core/security.py`

### Community Features

- [AI Lounge Controls](https://github.com/opensourcewinter/sirdeep/blob/main/src/modules/ai/view.py): `src/modules/ai/view.py`
- [AI Companion](https://github.com/opensourcewinter/sirdeep/blob/main/src/modules/ai/engine.py): `src/modules/ai/engine.py`
- [XP and Reputation](https://github.com/opensourcewinter/sirdeep/blob/main/src/modules/leveling/engine.py): `src/modules/leveling/engine.py`
- [Contributor Card Renderer](https://github.com/opensourcewinter/sirdeep/blob/main/src/modules/leveling/cards.py): `src/modules/leveling/cards.py`
- [Debate Scheduler](https://github.com/opensourcewinter/sirdeep/blob/main/src/modules/debates/engine.py): `src/modules/debates/engine.py`

### Audio Streaming

- [Radio Controls](https://github.com/opensourcewinter/sirdeep/blob/main/src/modules/radio/view.py): `src/modules/radio/view.py`
- [Radio Player](https://github.com/opensourcewinter/sirdeep/blob/main/src/modules/radio/player.py): `src/modules/radio/player.py`

### Other components

- **Discord Members**
- **Discord Gateway**
- **AI Providers**
- [Debate Topic Pool](https://github.com/opensourcewinter/sirdeep/blob/main/config/debates.json): `config/debates.json`
- **FFmpeg**
- **Discord Services**

## Connections

- Discord Gateway → Async Bot Client: delivers events (evidence: `README.md`)
- Discord Members → Async Bot Client: interacts
- Async Bot Client → Configuration: loads settings
- Async Bot Client → Audit Logger: dispatches audit events (evidence: `README.md`)
- Async Bot Client → Anti-Nuke Sentinel: dispatches safety events (evidence: `README.md`)
- Async Bot Client → AI Companion: routes chat (evidence: `README.md`)
- Async Bot Client → AI Lounge Controls: registers controls
- AI Lounge Controls → XP and Reputation: requests profile (evidence: `src/modules/ai/view.py`)
- AI Companion → AI Providers: sends inference requests (evidence: `src/modules/ai/engine.py`)
- Async Bot Client → XP and Reputation: routes messages (evidence: `README.md`)
- XP and Reputation → Contributor Card Renderer: renders card (evidence: `src/modules/leveling/engine.py`)
- Async Bot Client → Debate Scheduler: schedules debates (evidence: `README.md`)
- Debate Scheduler → Debate Topic Pool: reads topics (evidence: `src/modules/debates/engine.py`)
- Async Bot Client → Radio Controls: registers controls
- Radio Controls → Radio Player: controls playback (evidence: `src/modules/radio/view.py`)
- Radio Player → FFmpeg: transcodes streams (evidence: `src/modules/radio/player.py`)
- Audit Logger → Discord Services: posts audit logs (evidence: `src/core/audit.py`)
- Anti-Nuke Sentinel → Discord Services: quarantines actors (evidence: `src/core/security.py`)
- Debate Scheduler → Discord Services: posts threads (evidence: `src/modules/debates/engine.py`)
- Radio Player → Discord Services: streams to voice (evidence: `src/modules/radio/player.py`)
- Contributor Card Renderer → Discord Services: fetches avatars (evidence: `src/modules/leveling/cards.py`)