# xeravax/shield-bot architecture

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

- Interactive diagram: https://gitdiagram.com/xeravax/shield-bot
- Repository: https://github.com/xeravax/shield-bot
- Video tour (about a minute): https://gitdiagram.com/xeravax/shield-bot/video

## Overview

Shield Bot is a Discord community-management bot with a VRChat integration and a web dashboard. Discord members use commands and interactions for attendance, planned events, patrols, leave requests, verification, and whitelist administration; managers implement those domain workflows, while event handlers and schedules support ongoing activity. The dashboard provides an additional authenticated interface for event planning. The README documents broader capabilities than the sampled excerpts; unsampled subsystems are represented at their exact source directories, and edges are limited to documented behavior or indexed references.

Main entry points: [`src/main.ts`](https://github.com/xeravax/shield-bot/blob/main/src/main.ts) (Bot runtime), [`src/commands`](https://github.com/xeravax/shield-bot/tree/main/src/commands) (Slash commands), [`src/events/discord`](https://github.com/xeravax/shield-bot/tree/main/src/events/discord) (Discord interactions), [`src/managers/whitelist/whitelistManager.ts`](https://github.com/xeravax/shield-bot/blob/main/src/managers/whitelist/whitelistManager.ts) (Whitelist control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and interfaces"]
  node_app["Bot runtime<br/>[main.ts]"]
  node_commands["Slash commands"]
  node_discord_events["Discord interactions"]
  node_schedules["Scheduled jobs"]
  node_event_store[("Persistent records")]
end

subgraph group_community["Community workflows"]
  node_attendance["Attendance tracking"]
  node_event_planning["Event planning"]
  node_patrol["Patrol tracking"]
  node_loa["Leave management<br/>[loaManager.ts]"]
  node_role_tracking["Role tracking"]
end

subgraph group_vrchat["VRChat integration"]
  node_verification["Account verification"]
  node_vrchat_events["VRChat events"]
  node_group_sync["Group role sync"]
end

subgraph group_admin["Administration"]
  node_whitelist["Whitelist control"]
  node_logging["Audit logging<br/>[index.ts]"]
  node_api["REST API"]
end

subgraph group_dashboard["Web dashboard"]
  node_dashboard_ui["Dashboard interface<br/>[App.tsx]"]
  node_dashboard_api["Dashboard endpoints<br/>[dashboard.ts]"]
end

node_members(("Discord members"))
node_discord(("Discord platform"))
node_vrchat_service(("VRChat API"))
node_github(("GitHub"))

node_members -->|"use bot"| node_discord
node_discord -->|"delivers events"| node_app
node_app -->|"loads modules"| node_commands
node_app -->|"loads modules"| node_discord_events
node_app -->|"loads modules"| node_api
node_app -->|"starts schedules"| node_schedules
node_commands -.->|"manage attendance"| node_attendance
node_commands -.->|"manage events"| node_event_planning
node_commands -.->|"manage patrols"| node_patrol
node_commands -.->|"manage leave"| node_loa
node_discord_events -.->|"handle verification"| node_verification
node_discord_events -->|"manage whitelist"| node_whitelist
node_app -->|"starts listener"| node_vrchat_events
node_vrchat_events -.->|"receive events"| node_vrchat_service
node_group_sync -.->|"sync group roles"| node_vrchat_service
node_whitelist -.->|"publish backup"| node_github
node_discord_events -->|"send audit events"| node_logging
node_dashboard_ui -->|"request data"| node_dashboard_api
node_dashboard_api -->|"uses planning logic"| node_event_planning
node_event_planning -->|"persist events"| node_event_store
node_loa -->|"persist leave"| node_event_store
node_whitelist -->|"read whitelist data"| node_event_store

click node_app "https://github.com/xeravax/shield-bot/blob/main/src/main.ts"
click node_commands "https://github.com/xeravax/shield-bot/tree/main/src/commands"
click node_discord_events "https://github.com/xeravax/shield-bot/tree/main/src/events/discord"
click node_schedules "https://github.com/xeravax/shield-bot/tree/main/src/schedules"
click node_attendance "https://github.com/xeravax/shield-bot/blob/main/src/managers/attendance/attendanceManager.ts"
click node_event_planning "https://github.com/xeravax/shield-bot/blob/main/src/managers/events/eventPlanningManager.ts"
click node_patrol "https://github.com/xeravax/shield-bot/blob/main/src/managers/patrol/patrolTimerManager.ts"
click node_loa "https://github.com/xeravax/shield-bot/blob/main/src/managers/loa/loaManager.ts"
click node_role_tracking "https://github.com/xeravax/shield-bot/blob/main/src/managers/roleTracking/roleTrackingManager.ts"
click node_verification "https://github.com/xeravax/shield-bot/tree/main/src/managers/verification"
click node_vrchat_events "https://github.com/xeravax/shield-bot/blob/main/src/events/vrchat/vrchat-websocket.ts"
click node_group_sync "https://github.com/xeravax/shield-bot/blob/main/src/managers/groupRoleSync/groupRoleSyncManager.ts"
click node_whitelist "https://github.com/xeravax/shield-bot/blob/main/src/managers/whitelist/whitelistManager.ts"
click node_logging "https://github.com/xeravax/shield-bot/blob/main/src/managers/logging/index.ts"
click node_api "https://github.com/xeravax/shield-bot/tree/main/src/api"
click node_dashboard_ui "https://github.com/xeravax/shield-bot/blob/main/dashboard/src/App.tsx"
click node_dashboard_api "https://github.com/xeravax/shield-bot/blob/main/src/api/dashboard/dashboard.ts"

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_app,node_commands,node_discord_events,node_schedules,node_event_store toneBlue
class node_attendance,node_event_planning,node_patrol,node_loa,node_role_tracking toneAmber
class node_verification,node_vrchat_events,node_group_sync,node_vrchat_service toneMint
class node_whitelist,node_logging,node_api toneRose
class node_dashboard_ui,node_dashboard_api,node_members,node_discord,node_github toneIndigo
```

## Components

### Runtime and interfaces

- [Bot runtime](https://github.com/xeravax/shield-bot/blob/main/src/main.ts): `src/main.ts`
- [Slash commands](https://github.com/xeravax/shield-bot/tree/main/src/commands): `src/commands`
- [Discord interactions](https://github.com/xeravax/shield-bot/tree/main/src/events/discord): `src/events/discord`
- [Scheduled jobs](https://github.com/xeravax/shield-bot/tree/main/src/schedules): `src/schedules`
- **Persistent records**

### Community workflows

- [Attendance tracking](https://github.com/xeravax/shield-bot/blob/main/src/managers/attendance/attendanceManager.ts): `src/managers/attendance/attendanceManager.ts`
- [Event planning](https://github.com/xeravax/shield-bot/blob/main/src/managers/events/eventPlanningManager.ts): `src/managers/events/eventPlanningManager.ts`
- [Patrol tracking](https://github.com/xeravax/shield-bot/blob/main/src/managers/patrol/patrolTimerManager.ts): `src/managers/patrol/patrolTimerManager.ts`
- [Leave management](https://github.com/xeravax/shield-bot/blob/main/src/managers/loa/loaManager.ts): `src/managers/loa/loaManager.ts`
- [Role tracking](https://github.com/xeravax/shield-bot/blob/main/src/managers/roleTracking/roleTrackingManager.ts): `src/managers/roleTracking/roleTrackingManager.ts`

### VRChat integration

- [Account verification](https://github.com/xeravax/shield-bot/tree/main/src/managers/verification): `src/managers/verification`
- [VRChat events](https://github.com/xeravax/shield-bot/blob/main/src/events/vrchat/vrchat-websocket.ts): `src/events/vrchat/vrchat-websocket.ts`
- [Group role sync](https://github.com/xeravax/shield-bot/blob/main/src/managers/groupRoleSync/groupRoleSyncManager.ts): `src/managers/groupRoleSync/groupRoleSyncManager.ts`

### Administration

- [Whitelist control](https://github.com/xeravax/shield-bot/blob/main/src/managers/whitelist/whitelistManager.ts): `src/managers/whitelist/whitelistManager.ts`
- [Audit logging](https://github.com/xeravax/shield-bot/blob/main/src/managers/logging/index.ts): `src/managers/logging/index.ts`
- [REST API](https://github.com/xeravax/shield-bot/tree/main/src/api): `src/api`

### Web dashboard

- [Dashboard interface](https://github.com/xeravax/shield-bot/blob/main/dashboard/src/App.tsx): `dashboard/src/App.tsx`
- [Dashboard endpoints](https://github.com/xeravax/shield-bot/blob/main/src/api/dashboard/dashboard.ts): `src/api/dashboard/dashboard.ts`

### Other components

- **Discord members**
- **Discord platform**
- **VRChat API**
- **GitHub**

## Connections

- Discord members → Discord platform: use bot
- Discord platform → Bot runtime: delivers events (evidence: `src/main.ts`)
- Bot runtime → Slash commands: loads modules (evidence: `src/main.ts`)
- Bot runtime → Discord interactions: loads modules (evidence: `src/main.ts`)
- Bot runtime → REST API: loads modules (evidence: `src/main.ts`)
- Bot runtime → Scheduled jobs: starts schedules (evidence: `src/main.ts`)
- Slash commands → Attendance tracking: manage attendance
- Slash commands → Event planning: manage events
- Slash commands → Patrol tracking: manage patrols
- Slash commands → Leave management: manage leave
- Discord interactions → Account verification: handle verification
- Discord interactions → Whitelist control: manage whitelist (evidence: `src/events/discord/button/accountmanagement/VRCAccountManagerButton.ts`)
- Bot runtime → VRChat events: starts listener (evidence: `src/main.ts`)
- VRChat events → VRChat API: receive events
- Group role sync → VRChat API: sync group roles
- Whitelist control → GitHub: publish backup
- Discord interactions → Audit logging: send audit events (evidence: `src/events/discord/logging/server.ts`)
- Dashboard interface → Dashboard endpoints: request data (evidence: `src/api/dashboard/dashboard.ts`)
- Dashboard endpoints → Event planning: uses planning logic (evidence: `src/api/dashboard/dashboard.ts`)
- Event planning → Persistent records: persist events (evidence: `src/managers/events/eventPlanningManager.ts`)
- Leave management → Persistent records: persist leave (evidence: `src/managers/loa/loaManager.ts`)
- Whitelist control → Persistent records: read whitelist data (evidence: `src/managers/whitelist/whitelistManager.ts`)
