# jiahong-guan/ticket-bot architecture

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

- Interactive diagram: https://gitdiagram.com/jiahong-guan/ticket-bot
- Repository: https://github.com/jiahong-guan/ticket-bot

## Overview

Ticket Bot is a Discord support-ticket application. Server administrators configure panels through a five-step wizard; members use panel buttons to open tickets, while owners and support staff manage ticket access and lifecycle through slash commands or persistent controls. TicketService coordinates channel and permission changes, storage, rate-limit handling, and transcript creation; TinyDB persists guild, panel, ticket, and member state. The README documents these capabilities, but several command and service implementations were not sampled, so their internal links are omitted unless the available evidence supports them.

Main entry points: [`bot.py`](https://github.com/jiahong-guan/ticket-bot/blob/main/bot.py) (Bot runtime), [`utils/ticket_service.py`](https://github.com/jiahong-guan/ticket-bot/blob/main/utils/ticket_service.py) (Ticket lifecycle), [`utils/database.py`](https://github.com/jiahong-guan/ticket-bot/blob/main/utils/database.py) (Database access), [`utils/views/ticket_controls.py`](https://github.com/jiahong-guan/ticket-bot/blob/main/utils/views/ticket_controls.py) (Ticket controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Discord entry points"]
  node_startup["Application startup<br/>[main.py]"]
  node_bot["Bot runtime<br/>[bot.py]"]
  node_admin["Panel administration<br/>[admin.py]"]
  node_general["General commands<br/>[general.py]"]
  node_panel_commands["Setup command<br/>[panels.py]"]
  node_ticket_commands["Ticket commands<br/>[tickets.py]"]
  node_base_command["Command base<br/>[base_command.py]"]
end

subgraph group_ticket["Ticket workflows"]
  node_wizard["Panel wizard<br/>[panel_wizard.py]"]
  node_controls["Ticket controls<br/>[ticket_controls.py]"]
  node_ticket_service["Ticket lifecycle<br/>[ticket_service.py]"]
  node_transcript["Transcript renderer<br/>[transcript.py]"]
end

subgraph group_core["Shared services"]
  node_checks["Access checks<br/>[checks.py]"]
  node_rate_limit["Edit rate limiter<br/>[rate_limit.py]"]
  node_embeds["Discord embeds<br/>[embeds.py]"]
  node_errors["Error handling<br/>[error_handler.py]"]
  node_exceptions["Domain errors<br/>[exceptions.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_logger["Logging<br/>[logger.py]"]
end

subgraph group_state["Persistence and output"]
  node_database["Database access<br/>[database.py]"]
  node_tinydb[("Atomic TinyDB files")]
  node_transcript_files["HTML transcript files"]
end

node_member(("Server members"))
node_discord{{"Discord API"}}

node_member -->|"uses commands"| node_discord
node_discord -->|"delivers interactions"| node_bot
node_startup -->|"starts"| node_bot
node_bot -->|"opens"| node_database
node_bot -->|"creates"| node_ticket_service
node_bot -->|"loads cogs"| node_admin
node_bot -->|"loads cogs"| node_general
node_bot -->|"loads cogs"| node_panel_commands
node_bot -->|"loads cogs"| node_ticket_commands
node_panel_commands -->|"launches"| node_wizard
node_wizard -->|"saves panel"| node_database
node_wizard -->|"posts panel"| node_discord
node_ticket_commands -->|"uses base"| node_base_command
node_admin -->|"uses base"| node_base_command
node_general -->|"uses base"| node_base_command
node_ticket_commands -.->|"manages tickets"| node_ticket_service
node_discord -->|"invokes buttons"| node_controls
node_controls -->|"delegates actions"| node_ticket_service
node_controls -->|"checks access"| node_checks
node_ticket_service -->|"reads and writes"| node_database
node_ticket_service -->|"changes channels"| node_discord
node_ticket_service -->|"renders transcript"| node_transcript
node_ticket_service -->|"uses budget"| node_rate_limit
node_ticket_service -->|"uses access checks"| node_checks
node_transcript -.->|"writes HTML"| node_transcript_files
node_database -->|"stores tables"| node_tinydb
node_checks -->|"reads guild roles"| node_database
node_errors -->|"formats replies"| node_embeds
node_base_command -->|"handles command errors"| node_errors
node_controls -->|"handles view errors"| node_errors
node_bot -->|"uses settings"| node_config
node_bot -->|"registers persistent views"| node_controls
node_database -->|"raises failures"| node_exceptions
node_ticket_service -.->|"raises domain errors"| node_exceptions

click node_startup "https://github.com/jiahong-guan/ticket-bot/blob/main/main.py"
click node_bot "https://github.com/jiahong-guan/ticket-bot/blob/main/bot.py"
click node_admin "https://github.com/jiahong-guan/ticket-bot/blob/main/cogs/admin.py"
click node_general "https://github.com/jiahong-guan/ticket-bot/blob/main/cogs/general.py"
click node_panel_commands "https://github.com/jiahong-guan/ticket-bot/blob/main/cogs/panels.py"
click node_ticket_commands "https://github.com/jiahong-guan/ticket-bot/blob/main/cogs/tickets.py"
click node_base_command "https://github.com/jiahong-guan/ticket-bot/blob/main/cogs/base_command.py"
click node_wizard "https://github.com/jiahong-guan/ticket-bot/blob/main/utils/views/panel_wizard.py"
click node_controls "https://github.com/jiahong-guan/ticket-bot/blob/main/utils/views/ticket_controls.py"
click node_ticket_service "https://github.com/jiahong-guan/ticket-bot/blob/main/utils/ticket_service.py"
click node_transcript "https://github.com/jiahong-guan/ticket-bot/blob/main/utils/transcript.py"
click node_checks "https://github.com/jiahong-guan/ticket-bot/blob/main/utils/checks.py"
click node_rate_limit "https://github.com/jiahong-guan/ticket-bot/blob/main/utils/rate_limit.py"
click node_embeds "https://github.com/jiahong-guan/ticket-bot/blob/main/utils/embeds.py"
click node_errors "https://github.com/jiahong-guan/ticket-bot/blob/main/utils/error_handler.py"
click node_exceptions "https://github.com/jiahong-guan/ticket-bot/blob/main/utils/exceptions.py"
click node_config "https://github.com/jiahong-guan/ticket-bot/blob/main/utils/config.py"
click node_logger "https://github.com/jiahong-guan/ticket-bot/blob/main/utils/logger.py"
click node_database "https://github.com/jiahong-guan/ticket-bot/blob/main/utils/database.py"
click node_tinydb "https://github.com/jiahong-guan/ticket-bot/tree/main/db"
click node_transcript_files "https://github.com/jiahong-guan/ticket-bot/tree/main/transcripts"

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_startup,node_bot,node_admin,node_general,node_panel_commands,node_ticket_commands,node_base_command toneBlue
class node_wizard,node_controls,node_ticket_service,node_transcript toneAmber
class node_checks,node_rate_limit,node_embeds,node_errors,node_exceptions,node_config,node_logger,node_member,node_discord toneMint
class node_database,node_tinydb,node_transcript_files toneRose
```

## Components

### Discord entry points

- [Application startup](https://github.com/jiahong-guan/ticket-bot/blob/main/main.py): `main.py`
- [Bot runtime](https://github.com/jiahong-guan/ticket-bot/blob/main/bot.py): `bot.py`
- [Panel administration](https://github.com/jiahong-guan/ticket-bot/blob/main/cogs/admin.py): `cogs/admin.py`
- [General commands](https://github.com/jiahong-guan/ticket-bot/blob/main/cogs/general.py): `cogs/general.py`
- [Setup command](https://github.com/jiahong-guan/ticket-bot/blob/main/cogs/panels.py): `cogs/panels.py`
- [Ticket commands](https://github.com/jiahong-guan/ticket-bot/blob/main/cogs/tickets.py): `cogs/tickets.py`
- [Command base](https://github.com/jiahong-guan/ticket-bot/blob/main/cogs/base_command.py): `cogs/base_command.py`

### Ticket workflows

- [Panel wizard](https://github.com/jiahong-guan/ticket-bot/blob/main/utils/views/panel_wizard.py): `utils/views/panel_wizard.py`
- [Ticket controls](https://github.com/jiahong-guan/ticket-bot/blob/main/utils/views/ticket_controls.py): `utils/views/ticket_controls.py`
- [Ticket lifecycle](https://github.com/jiahong-guan/ticket-bot/blob/main/utils/ticket_service.py): `utils/ticket_service.py`
- [Transcript renderer](https://github.com/jiahong-guan/ticket-bot/blob/main/utils/transcript.py): `utils/transcript.py`

### Shared services

- [Access checks](https://github.com/jiahong-guan/ticket-bot/blob/main/utils/checks.py): `utils/checks.py`
- [Edit rate limiter](https://github.com/jiahong-guan/ticket-bot/blob/main/utils/rate_limit.py): `utils/rate_limit.py`
- [Discord embeds](https://github.com/jiahong-guan/ticket-bot/blob/main/utils/embeds.py): `utils/embeds.py`
- [Error handling](https://github.com/jiahong-guan/ticket-bot/blob/main/utils/error_handler.py): `utils/error_handler.py`
- [Domain errors](https://github.com/jiahong-guan/ticket-bot/blob/main/utils/exceptions.py): `utils/exceptions.py`
- [Configuration](https://github.com/jiahong-guan/ticket-bot/blob/main/utils/config.py): `utils/config.py`
- [Logging](https://github.com/jiahong-guan/ticket-bot/blob/main/utils/logger.py): `utils/logger.py`

### Persistence and output

- [Database access](https://github.com/jiahong-guan/ticket-bot/blob/main/utils/database.py): `utils/database.py`
- [Atomic TinyDB files](https://github.com/jiahong-guan/ticket-bot/tree/main/db): `db`
- [HTML transcript files](https://github.com/jiahong-guan/ticket-bot/tree/main/transcripts): `transcripts`

### Other components

- **Server members**
- **Discord API**

## Connections

- Server members → Discord API: uses commands (evidence: `README.md`)
- Discord API → Bot runtime: delivers interactions (evidence: `README.md`)
- Application startup → Bot runtime: starts (evidence: `main.py`)
- Bot runtime → Database access: opens (evidence: `bot.py`)
- Bot runtime → Ticket lifecycle: creates (evidence: `bot.py`)
- Bot runtime → Panel administration: loads cogs (evidence: `bot.py`)
- Bot runtime → General commands: loads cogs (evidence: `bot.py`)
- Bot runtime → Setup command: loads cogs (evidence: `bot.py`)
- Bot runtime → Ticket commands: loads cogs (evidence: `bot.py`)
- Setup command → Panel wizard: launches (evidence: `cogs/panels.py`)
- Panel wizard → Database access: saves panel (evidence: `utils/views/panel_wizard.py`)
- Panel wizard → Discord API: posts panel (evidence: `utils/views/panel_wizard.py`)
- Ticket commands → Command base: uses base (evidence: `cogs/tickets.py`)
- Panel administration → Command base: uses base (evidence: `cogs/admin.py`)
- General commands → Command base: uses base (evidence: `cogs/general.py`)
- Ticket commands → Ticket lifecycle: manages tickets
- Discord API → Ticket controls: invokes buttons (evidence: `README.md`)
- Ticket controls → Ticket lifecycle: delegates actions (evidence: `utils/views/ticket_controls.py`)
- Ticket controls → Access checks: checks access (evidence: `utils/views/ticket_controls.py`)
- Ticket lifecycle → Database access: reads and writes (evidence: `utils/ticket_service.py`)
- Ticket lifecycle → Discord API: changes channels (evidence: `README.md`)
- Ticket lifecycle → Transcript renderer: renders transcript (evidence: `utils/ticket_service.py`)
- Ticket lifecycle → Edit rate limiter: uses budget (evidence: `utils/ticket_service.py`)
- Ticket lifecycle → Access checks: uses access checks (evidence: `utils/ticket_service.py`)
- Transcript renderer → HTML transcript files: writes HTML
- Database access → Atomic TinyDB files: stores tables (evidence: `README.md`)
- Access checks → Database access: reads guild roles (evidence: `utils/checks.py`)
- Error handling → Discord embeds: formats replies (evidence: `utils/error_handler.py`)
- Command base → Error handling: handles command errors (evidence: `cogs/base_command.py`)
- Ticket controls → Error handling: handles view errors
- Bot runtime → Configuration: uses settings (evidence: `bot.py`)
- Bot runtime → Ticket controls: registers persistent views (evidence: `bot.py`)
- Database access → Domain errors: raises failures (evidence: `utils/database.py`)
- Ticket lifecycle → Domain errors: raises domain errors (evidence: `utils/ticket_service.py`)
