# kingshot-project/kingshot-discord-bot architecture

> Architecture diagram of the GitHub repository kingshot-project/kingshot-discord-bot, 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/kingshot-project/kingshot-discord-bot
- Repository: https://github.com/kingshot-project/kingshot-discord-bot

## Overview

Kingshot Discord Bot is a self-hosted Discord application for alliance administration and game-event operations. Its user-facing workflow runs through Discord interactions: administrators manage alliances and members, record or review attendance (including screenshot OCR), redeem gift codes, plan minister appointments, and configure reminders. Shared permission and theme modules support these features. The README documents the product capabilities; the source index confirms several module dependencies, but startup wiring and many unsampled cog interactions cannot be verified here.

Main entry points: [`cogs/attendance.py`](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/attendance.py) (Attendance tracking), [`cogs/gift_redemption.py`](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/gift_redemption.py) (Gift redemption), [`cogs/alliance_member_operations.py`](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/alliance_member_operations.py) (Member operations), [`cogs/alliance.py`](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/alliance.py) (Alliance management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_alliance["Alliance Operations"]
  node_alliance_admin["Alliance management<br/>[alliance.py]"]
  node_member_ops["Member operations"]
  node_member_edit["Member editing"]
  node_alliance_history["Alliance history"]
  node_power_history["Power history"]
end

subgraph group_events["Events and Tracking"]
  node_attendance["Attendance tracking<br/>[attendance.py]"]
  node_ocr_parsers["OCR parsing"]
  node_ocr_review["OCR review"]
  node_attendance_history["Attendance history"]
  node_no_shows["No-show tracking"]
  node_bear_tracking["Bear tracking<br/>[bear_track.py]"]
end

subgraph group_gifts["Gift Redemption"]
  node_gift_redemption["Gift redemption<br/>[gift_redemption.py]"]
  node_gift_state["Player state lookup"]
  node_gift_views["Gift interfaces<br/>[gift_views.py]"]
  node_game_service["Kingshot services"]
end

subgraph group_planning["Planning and Notifications"]
  node_minister_schedule["Minister scheduling"]
  node_minister_archive["Minister archive"]
  node_notification_system["Event notifications"]
  node_notification_schedule["Reminder scheduling"]
  node_notification_editor["Notification editor"]
  node_notification_wizard["Notification setup"]
  node_event_types["Event definitions"]
end

subgraph group_shared["Shared Bot Services"]
  node_process_queue["Process queue<br/>[process_queue.py]"]
  node_permissions["Permission handling"]
  node_theme["Theme customization<br/>[pimp_my_bot.py]"]
  node_onnx["OCR runtime lifecycle<br/>[onnx_lifecycle.py]"]
  node_member_store[("Bot data stores")]
end

node_discord_users(("Discord users"))

node_discord_users -->|"manage alliances"| node_alliance_admin
node_discord_users -->|"manage members"| node_member_ops
node_discord_users -->|"track attendance"| node_attendance
node_discord_users -->|"review uploads"| node_ocr_review
node_discord_users -->|"track bear damage"| node_bear_tracking
node_discord_users -->|"redeem codes"| node_gift_redemption
node_discord_users -->|"plan appointments"| node_minister_schedule
node_discord_users -->|"configure reminders"| node_notification_system
node_member_ops -->|"delegates edits"| node_member_edit
node_member_ops -->|"uses queue"| node_process_queue
node_attendance -->|"uses parsers"| node_ocr_parsers
node_attendance -->|"uses history"| node_attendance_history
node_attendance -->|"uses no-show tracking"| node_no_shows
node_ocr_parsers -->|"supports review"| node_ocr_review
node_ocr_parsers -->|"uses runtime"| node_onnx
node_ocr_review -->|"reads event slots"| node_ocr_parsers
node_bear_tracking -->|"uses attendance"| node_attendance
node_gift_views -->|"invokes redemption"| node_gift_redemption
node_gift_redemption -->|"checks queue"| node_process_queue
node_gift_redemption -->|"uses state lookup"| node_gift_state
node_gift_redemption -.->|"calls game API"| node_game_service
node_gift_state -->|"probes player state"| node_game_service
node_minister_schedule -->|"uses archive"| node_minister_archive
node_notification_editor -->|"uses event definitions"| node_event_types
node_notification_schedule -->|"uses event definitions"| node_event_types
node_notification_system -->|"uses event definitions"| node_event_types
node_notification_wizard -->|"uses event definitions"| node_event_types
node_alliance_admin -->|"uses permissions"| node_permissions
node_attendance -->|"uses permissions"| node_permissions
node_member_ops -->|"uses permissions"| node_permissions
node_alliance_admin -->|"uses theme"| node_theme
node_attendance -->|"uses theme"| node_theme
node_gift_redemption -->|"uses theme"| node_theme
node_member_edit -->|"records power changes"| node_power_history
node_alliance_admin -.->|"reads and writes"| node_member_store
node_member_ops -.->|"reads and writes"| node_member_store
node_attendance -.->|"stores attendance"| node_member_store
node_bear_tracking -.->|"stores tracking data"| node_member_store

click node_alliance_admin "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/alliance.py"
click node_member_ops "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/alliance_member_operations.py"
click node_member_edit "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/alliance_member_edit.py"
click node_alliance_history "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/alliance_history.py"
click node_power_history "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/alliance_power_changes.py"
click node_attendance "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/attendance.py"
click node_ocr_parsers "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/attendance_ocr_parsers.py"
click node_ocr_review "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/attendance_ocr_review.py"
click node_attendance_history "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/attendance_history.py"
click node_no_shows "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/attendance_no_shows.py"
click node_bear_tracking "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/bear_track.py"
click node_gift_redemption "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/gift_redemption.py"
click node_gift_state "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/gift_state_resolver.py"
click node_gift_views "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/gift_views.py"
click node_process_queue "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/process_queue.py"
click node_minister_schedule "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/minister_schedule.py"
click node_minister_archive "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/minister_archive.py"
click node_notification_system "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/notification_system.py"
click node_notification_schedule "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/notification_schedule.py"
click node_notification_editor "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/notification_editor.py"
click node_notification_wizard "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/notification_wizard.py"
click node_event_types "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/notification_event_types.py"
click node_permissions "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/permission_handler.py"
click node_theme "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/pimp_my_bot.py"
click node_onnx "https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/onnx_lifecycle.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_alliance_admin,node_member_ops,node_member_edit,node_alliance_history,node_power_history,node_discord_users toneBlue
class node_attendance,node_ocr_parsers,node_ocr_review,node_attendance_history,node_no_shows,node_bear_tracking toneAmber
class node_gift_redemption,node_gift_state,node_gift_views,node_game_service toneMint
class node_minister_schedule,node_minister_archive,node_notification_system,node_notification_schedule,node_notification_editor,node_notification_wizard,node_event_types toneRose
class node_process_queue,node_permissions,node_theme,node_onnx,node_member_store toneIndigo
```

## Components

### Alliance Operations

- [Alliance management](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/alliance.py): `cogs/alliance.py`
- [Member operations](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/alliance_member_operations.py): `cogs/alliance_member_operations.py`
- [Member editing](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/alliance_member_edit.py): `cogs/alliance_member_edit.py`
- [Alliance history](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/alliance_history.py): `cogs/alliance_history.py`
- [Power history](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/alliance_power_changes.py): `cogs/alliance_power_changes.py`

### Events and Tracking

- [Attendance tracking](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/attendance.py): `cogs/attendance.py`
- [OCR parsing](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/attendance_ocr_parsers.py): `cogs/attendance_ocr_parsers.py`
- [OCR review](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/attendance_ocr_review.py): `cogs/attendance_ocr_review.py`
- [Attendance history](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/attendance_history.py): `cogs/attendance_history.py`
- [No-show tracking](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/attendance_no_shows.py): `cogs/attendance_no_shows.py`
- [Bear tracking](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/bear_track.py): `cogs/bear_track.py`

### Gift Redemption

- [Gift redemption](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/gift_redemption.py): `cogs/gift_redemption.py`
- [Player state lookup](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/gift_state_resolver.py): `cogs/gift_state_resolver.py`
- [Gift interfaces](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/gift_views.py): `cogs/gift_views.py`
- **Kingshot services**

### Planning and Notifications

- [Minister scheduling](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/minister_schedule.py): `cogs/minister_schedule.py`
- [Minister archive](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/minister_archive.py): `cogs/minister_archive.py`
- [Event notifications](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/notification_system.py): `cogs/notification_system.py`
- [Reminder scheduling](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/notification_schedule.py): `cogs/notification_schedule.py`
- [Notification editor](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/notification_editor.py): `cogs/notification_editor.py`
- [Notification setup](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/notification_wizard.py): `cogs/notification_wizard.py`
- [Event definitions](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/notification_event_types.py): `cogs/notification_event_types.py`

### Shared Bot Services

- [Process queue](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/process_queue.py): `cogs/process_queue.py`
- [Permission handling](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/permission_handler.py): `cogs/permission_handler.py`
- [Theme customization](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/pimp_my_bot.py): `cogs/pimp_my_bot.py`
- [OCR runtime lifecycle](https://github.com/kingshot-project/kingshot-discord-bot/blob/main/cogs/onnx_lifecycle.py): `cogs/onnx_lifecycle.py`
- **Bot data stores**

### Other components

- **Discord users**

## Connections

- Discord users → Alliance management: manage alliances
- Discord users → Member operations: manage members
- Discord users → Attendance tracking: track attendance
- Discord users → OCR review: review uploads
- Discord users → Bear tracking: track bear damage
- Discord users → Gift redemption: redeem codes
- Discord users → Minister scheduling: plan appointments
- Discord users → Event notifications: configure reminders
- Member operations → Member editing: delegates edits (evidence: `cogs/alliance_member_operations.py`)
- Member operations → Process queue: uses queue (evidence: `cogs/alliance_member_operations.py`)
- Attendance tracking → OCR parsing: uses parsers (evidence: `cogs/attendance.py`)
- Attendance tracking → Attendance history: uses history (evidence: `cogs/attendance.py`)
- Attendance tracking → No-show tracking: uses no-show tracking (evidence: `cogs/attendance.py`)
- OCR parsing → OCR review: supports review (evidence: `cogs/attendance_ocr_parsers.py`)
- OCR parsing → OCR runtime lifecycle: uses runtime (evidence: `cogs/attendance_ocr_parsers.py`)
- OCR review → OCR parsing: reads event slots (evidence: `cogs/attendance_ocr_review.py`)
- Bear tracking → Attendance tracking: uses attendance (evidence: `cogs/bear_track.py`)
- Gift interfaces → Gift redemption: invokes redemption (evidence: `cogs/gift_views.py`)
- Gift redemption → Process queue: checks queue (evidence: `cogs/gift_redemption.py`)
- Gift redemption → Player state lookup: uses state lookup (evidence: `cogs/gift_redemption.py`)
- Gift redemption → Kingshot services: calls game API
- Player state lookup → Kingshot services: probes player state (evidence: `cogs/gift_state_resolver.py`)
- Minister scheduling → Minister archive: uses archive (evidence: `cogs/minister_schedule.py`)
- Notification editor → Event definitions: uses event definitions (evidence: `cogs/notification_editor.py`)
- Reminder scheduling → Event definitions: uses event definitions (evidence: `cogs/notification_schedule.py`)
- Event notifications → Event definitions: uses event definitions (evidence: `cogs/notification_system.py`)
- Notification setup → Event definitions: uses event definitions (evidence: `cogs/notification_wizard.py`)
- Alliance management → Permission handling: uses permissions (evidence: `cogs/alliance.py`)
- Attendance tracking → Permission handling: uses permissions (evidence: `cogs/attendance.py`)
- Member operations → Permission handling: uses permissions (evidence: `cogs/alliance_member_operations.py`)
- Alliance management → Theme customization: uses theme (evidence: `cogs/alliance.py`)
- Attendance tracking → Theme customization: uses theme (evidence: `cogs/attendance.py`)
- Gift redemption → Theme customization: uses theme (evidence: `cogs/gift_redemption.py`)
- Member editing → Power history: records power changes (evidence: `cogs/alliance_member_edit.py`)
- Alliance management → Bot data stores: reads and writes
- Member operations → Bot data stores: reads and writes
- Attendance tracking → Bot data stores: stores attendance
- Bear tracking → Bot data stores: stores tracking data