# ieu-an/deathnote architecture

> Architecture diagram of the GitHub repository ieu-an/deathnote, 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/ieu-an/deathnote
- Repository: https://github.com/ieu-an/deathnote

## Overview

This is a Discord recruitment and onboarding bot. Members join and receive optional onboarding messages or roles, then submit a verification application; staff review it, route applicants through interview or accept/deny decisions, and the bot records outcomes and handles stale interviews. Administrators configure guild behavior, while separate role-panel features support reaction roles and staff-role panels. SQLite backs settings and application state. Edges follow excerpts, SOURCE INDEX references, or README descriptions; unsampled cogs are included as documented capabilities, with only documented or indexed relationships shown.

Main entry points: [`cogs/verification.py`](https://github.com/ieu-an/deathnote/blob/main/cogs/verification.py) (Application verification), [`utils/database.py`](https://github.com/ieu-an/deathnote/blob/main/utils/database.py) (SQLite persistence), [`cogs/onboarding.py`](https://github.com/ieu-an/deathnote/blob/main/cogs/onboarding.py) (Join onboarding), [`cogs/interview.py`](https://github.com/ieu-an/deathnote/blob/main/cogs/interview.py) (Interview controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_onboarding["Onboarding"]
  node_onboarding_cog["Join onboarding<br/>[onboarding.py]"]
end

subgraph group_recruitment["Recruitment workflow"]
  node_verification["Application verification<br/>[verification.py]"]
  node_interview["Interview controls<br/>[interview.py]"]
  node_timeout["Interview timeout<br/>[timeout_tasks.py]"]
end

subgraph group_configuration["Guild configuration"]
  node_admin_commands["Settings commands<br/>[admin.py]"]
  node_reaction_roles["Reaction role panels<br/>[reaction_roles.py]"]
  node_staff_panel["Staff role panel"]
end

subgraph group_shared["Shared services"]
  node_database[("SQLite persistence<br/>[database.py]")]
  node_checks["Permission checks<br/>[checks.py]"]
  node_embeds["Recruitment embeds"]
  node_ping["Staff ping selection<br/>[ping_helpers.py]"]
  node_time["Eastern time helpers<br/>[time_utils.py]"]
  node_branding["Member embed branding<br/>[branding.py]"]
end

node_member(("Server member"))
node_staff(("Recruiting staff"))
node_admin(("Server administrator"))
node_discord["Discord platform"]

node_member -->|"joins server"| node_onboarding_cog
node_onboarding_cog -->|"sends welcome DM"| node_member
node_onboarding_cog -->|"reads settings"| node_database
node_onboarding_cog -->|"uses branding"| node_branding
node_onboarding_cog -->|"uses embeds"| node_embeds
node_member -->|"submits application"| node_verification
node_verification -->|"posts review card"| node_staff
node_verification -->|"stores application"| node_database
node_verification -->|"checks staff access"| node_checks
node_verification -->|"formats staff mention"| node_ping
node_verification -->|"builds review card"| node_embeds
node_verification -->|"brands member embeds"| node_branding
node_staff -->|"reviews application"| node_verification
node_verification -->|"registers interview views"| node_interview
node_interview -->|"calls conclusion handlers"| node_verification
node_interview -->|"records recruiter"| node_database
node_interview -->|"checks staff access"| node_checks
node_interview -->|"formats audit log"| node_embeds
node_timeout -->|"finds and updates stale applications"| node_database
node_timeout -->|"removes interview role"| node_verification
node_timeout -->|"updates card and logs"| node_embeds
node_admin -->|"configures guild"| node_admin_commands
node_admin_commands -->|"updates settings"| node_database
node_admin_commands -->|"checks admin access"| node_checks
node_admin_commands -->|"validates ping times"| node_time
node_admin -->|"configures role panels"| node_reaction_roles
node_reaction_roles -->|"stores role bindings"| node_database
node_reaction_roles -->|"checks admin access"| node_checks
node_reaction_roles -->|"styles panel"| node_branding
node_staff_panel -->|"uses persistence"| node_database
node_staff_panel -->|"uses branding"| node_branding
node_ping -->|"checks ping window"| node_time
node_embeds -->|"formats timestamps"| node_time
node_verification -->|"uses interactions"| node_discord
node_timeout -->|"bans timed-out applicants"| node_discord

click node_onboarding_cog "https://github.com/ieu-an/deathnote/blob/main/cogs/onboarding.py"
click node_verification "https://github.com/ieu-an/deathnote/blob/main/cogs/verification.py"
click node_interview "https://github.com/ieu-an/deathnote/blob/main/cogs/interview.py"
click node_timeout "https://github.com/ieu-an/deathnote/blob/main/tasks/timeout_tasks.py"
click node_admin_commands "https://github.com/ieu-an/deathnote/blob/main/cogs/admin.py"
click node_reaction_roles "https://github.com/ieu-an/deathnote/blob/main/cogs/reaction_roles.py"
click node_staff_panel "https://github.com/ieu-an/deathnote/blob/main/cogs/staff_role_panel.py"
click node_database "https://github.com/ieu-an/deathnote/blob/main/utils/database.py"
click node_checks "https://github.com/ieu-an/deathnote/blob/main/utils/checks.py"
click node_embeds "https://github.com/ieu-an/deathnote/blob/main/utils/recruitment_embeds.py"
click node_ping "https://github.com/ieu-an/deathnote/blob/main/utils/ping_helpers.py"
click node_time "https://github.com/ieu-an/deathnote/blob/main/utils/time_utils.py"
click node_branding "https://github.com/ieu-an/deathnote/blob/main/utils/branding.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_onboarding_cog toneBlue
class node_verification,node_interview,node_timeout toneAmber
class node_admin_commands,node_reaction_roles,node_staff_panel,node_member,node_admin toneMint
class node_database,node_checks,node_embeds,node_ping,node_time,node_branding toneRose
class node_staff,node_discord toneIndigo
```

## Components

### Onboarding

- [Join onboarding](https://github.com/ieu-an/deathnote/blob/main/cogs/onboarding.py): `cogs/onboarding.py`

### Recruitment workflow

- [Application verification](https://github.com/ieu-an/deathnote/blob/main/cogs/verification.py): `cogs/verification.py`
- [Interview controls](https://github.com/ieu-an/deathnote/blob/main/cogs/interview.py): `cogs/interview.py`
- [Interview timeout](https://github.com/ieu-an/deathnote/blob/main/tasks/timeout_tasks.py): `tasks/timeout_tasks.py`

### Guild configuration

- [Settings commands](https://github.com/ieu-an/deathnote/blob/main/cogs/admin.py): `cogs/admin.py`
- [Reaction role panels](https://github.com/ieu-an/deathnote/blob/main/cogs/reaction_roles.py): `cogs/reaction_roles.py`
- [Staff role panel](https://github.com/ieu-an/deathnote/blob/main/cogs/staff_role_panel.py): `cogs/staff_role_panel.py`

### Shared services

- [SQLite persistence](https://github.com/ieu-an/deathnote/blob/main/utils/database.py): `utils/database.py`
- [Permission checks](https://github.com/ieu-an/deathnote/blob/main/utils/checks.py): `utils/checks.py`
- [Recruitment embeds](https://github.com/ieu-an/deathnote/blob/main/utils/recruitment_embeds.py): `utils/recruitment_embeds.py`
- [Staff ping selection](https://github.com/ieu-an/deathnote/blob/main/utils/ping_helpers.py): `utils/ping_helpers.py`
- [Eastern time helpers](https://github.com/ieu-an/deathnote/blob/main/utils/time_utils.py): `utils/time_utils.py`
- [Member embed branding](https://github.com/ieu-an/deathnote/blob/main/utils/branding.py): `utils/branding.py`

### Other components

- **Server member**
- **Recruiting staff**
- **Server administrator**
- **Discord platform**

## Connections

- Server member → Join onboarding: joins server (evidence: `README.md`)
- Join onboarding → Server member: sends welcome DM (evidence: `README.md`)
- Join onboarding → SQLite persistence: reads settings (evidence: `cogs/onboarding.py`)
- Join onboarding → Member embed branding: uses branding (evidence: `cogs/onboarding.py`)
- Join onboarding → Recruitment embeds: uses embeds (evidence: `cogs/onboarding.py`)
- Server member → Application verification: submits application (evidence: `README.md`)
- Application verification → Recruiting staff: posts review card (evidence: `README.md`)
- Application verification → SQLite persistence: stores application (evidence: `cogs/verification.py`)
- Application verification → Permission checks: checks staff access (evidence: `cogs/verification.py`)
- Application verification → Staff ping selection: formats staff mention (evidence: `cogs/verification.py`)
- Application verification → Recruitment embeds: builds review card (evidence: `cogs/verification.py`)
- Application verification → Member embed branding: brands member embeds (evidence: `cogs/verification.py`)
- Recruiting staff → Application verification: reviews application (evidence: `README.md`)
- Application verification → Interview controls: registers interview views (evidence: `cogs/verification.py`)
- Interview controls → Application verification: calls conclusion handlers (evidence: `cogs/interview.py`)
- Interview controls → SQLite persistence: records recruiter (evidence: `cogs/interview.py`)
- Interview controls → Permission checks: checks staff access (evidence: `cogs/interview.py`)
- Interview controls → Recruitment embeds: formats audit log (evidence: `cogs/interview.py`)
- Interview timeout → SQLite persistence: finds and updates stale applications (evidence: `tasks/timeout_tasks.py`)
- Interview timeout → Application verification: removes interview role (evidence: `tasks/timeout_tasks.py`)
- Interview timeout → Recruitment embeds: updates card and logs (evidence: `tasks/timeout_tasks.py`)
- Server administrator → Settings commands: configures guild (evidence: `README.md`)
- Settings commands → SQLite persistence: updates settings (evidence: `cogs/admin.py`)
- Settings commands → Permission checks: checks admin access (evidence: `cogs/admin.py`)
- Settings commands → Eastern time helpers: validates ping times (evidence: `cogs/admin.py`)
- Server administrator → Reaction role panels: configures role panels (evidence: `README.md`)
- Reaction role panels → SQLite persistence: stores role bindings (evidence: `cogs/reaction_roles.py`)
- Reaction role panels → Permission checks: checks admin access (evidence: `cogs/reaction_roles.py`)
- Reaction role panels → Member embed branding: styles panel (evidence: `cogs/reaction_roles.py`)
- Staff role panel → SQLite persistence: uses persistence (evidence: `cogs/staff_role_panel.py`)
- Staff role panel → Member embed branding: uses branding (evidence: `cogs/staff_role_panel.py`)
- Staff ping selection → Eastern time helpers: checks ping window (evidence: `utils/ping_helpers.py`)
- Recruitment embeds → Eastern time helpers: formats timestamps (evidence: `utils/recruitment_embeds.py`)
- Application verification → Discord platform: uses interactions (evidence: `README.md`)
- Interview timeout → Discord platform: bans timed-out applicants (evidence: `tasks/timeout_tasks.py`)