# hgleung/discord-squire architecture

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

## Overview

Squire is a self-hosted Discord bot with assistant, strength-training, music, and system modules; its training log also has a web UI and is stored in an Obsidian vault. The main user workflow is a Discord message or command routed by the bot to a module, which responds or updates state. The assistant also runs background tasks and offers research, calendar, and factory capabilities. Relationships for unsampled assistant features are included only where the README documents them; source excerpts and the index support the other shown links.

Main entry points: [`src/modules/assistant/index.ts`](https://github.com/hgleung/discord-squire/blob/main/src/modules/assistant/index.ts) (Chat module), [`src/modules/training/service.ts`](https://github.com/hgleung/discord-squire/blob/main/src/modules/training/service.ts) (Workout service), [`src/index.ts`](https://github.com/hgleung/discord-squire/blob/main/src/index.ts) (Bot startup), [`src/bot.ts`](https://github.com/hgleung/discord-squire/blob/main/src/bot.ts) (Command routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_entry["Bot startup<br/>[index.ts]"]
  node_router["Command routing<br/>[bot.ts]"]
  node_vault[("Obsidian vault<br/>[vault.ts]")]
  node_system_module["Update command<br/>[index.ts]"]
end

subgraph group_assistant["Assistant"]
  node_assistant_module["Chat module<br/>[index.ts]"]
  node_agent["Chat agent<br/>[agent.ts]"]
  node_llm["Tool protocol<br/>[llm.ts]"]
  node_background["Background tasks<br/>[tasks.ts]"]
  node_factory["Job factories<br/>[factory.ts]"]
  node_brief["Calendar brief<br/>[brief.ts]"]
  node_google["Google services<br/>[google.ts]"]
  node_assistant_state[("Reminders, memory")]
end

subgraph group_training["Training log"]
  node_training_module["Training commands<br/>[index.ts]"]
  node_training_service["Workout service<br/>[service.ts]"]
  node_plan_store[("Plan storage<br/>[store.ts]")]
  node_plan_ops["Plan operations<br/>[planOps.ts]"]
  node_scoring["Workout scoring<br/>[scoring.ts]"]
  node_week_summary["Weekly summary<br/>[weekSummary.ts]"]
  node_muscles["Muscle targets<br/>[muscles.ts]"]
  node_dates["Date utilities<br/>[dateUtils.ts]"]
  node_web_ui["Training web UI<br/>[App.tsx]"]
  node_web_hook["Plan sync hook<br/>[usePlan.ts]"]
  node_web_api["Plan API<br/>[api.ts]"]
end

subgraph group_music["Music"]
  node_music_module["Music commands<br/>[index.ts]"]
  node_music_player["Audio player<br/>[player.ts]"]
end

node_user(("Discord user"))
node_discord(("Discord"))
node_model(("Anthropic API"))
node_youtube(("YouTube audio"))

node_user -->|"sends command"| node_discord
node_discord -->|"delivers events"| node_router
node_entry -->|"starts"| node_router
node_entry -->|"registers"| node_assistant_module
node_entry -->|"registers"| node_training_module
node_entry -->|"registers"| node_music_module
node_entry -->|"registers"| node_system_module
node_router -->|"dispatches"| node_assistant_module
node_router -->|"dispatches"| node_training_module
node_router -->|"dispatches"| node_music_module
node_assistant_module -->|"invokes"| node_agent
node_agent -->|"uses tools"| node_llm
node_agent -.->|"requests completion"| node_model
node_assistant_module -->|"starts tasks"| node_background
node_background -->|"runs tools"| node_llm
node_background -->|"loads prompt"| node_factory
node_background -->|"reads and writes notes"| node_vault
node_assistant_module -->|"generates brief"| node_brief
node_brief -.->|"uses calendar"| node_google
node_assistant_module -->|"manages"| node_assistant_state
node_assistant_module -->|"answers gym queries"| node_training_service
node_training_module -->|"handles commands"| node_training_service
node_training_service -->|"reads and updates"| node_plan_store
node_training_service -->|"updates plan"| node_plan_ops
node_training_service -->|"calculates progress"| node_scoring
node_training_service -->|"builds weekly facts"| node_week_summary
node_week_summary -->|"computes statistics"| node_scoring
node_scoring -->|"uses targets"| node_muscles
node_training_service -->|"formats dates"| node_dates
node_plan_store -->|"persists plan"| node_vault
node_user -->|"logs workout"| node_web_ui
node_web_ui -->|"uses plan state"| node_web_hook
node_web_hook -->|"fetches and saves"| node_web_api
node_web_ui -->|"edits plan"| node_plan_ops
node_music_module -->|"controls playback"| node_music_player
node_music_player -.->|"streams audio"| node_youtube

click node_entry "https://github.com/hgleung/discord-squire/blob/main/src/index.ts"
click node_router "https://github.com/hgleung/discord-squire/blob/main/src/bot.ts"
click node_assistant_module "https://github.com/hgleung/discord-squire/blob/main/src/modules/assistant/index.ts"
click node_agent "https://github.com/hgleung/discord-squire/blob/main/src/modules/assistant/agent.ts"
click node_llm "https://github.com/hgleung/discord-squire/blob/main/src/modules/assistant/llm.ts"
click node_background "https://github.com/hgleung/discord-squire/blob/main/src/modules/assistant/tasks.ts"
click node_factory "https://github.com/hgleung/discord-squire/blob/main/src/modules/assistant/factory.ts"
click node_brief "https://github.com/hgleung/discord-squire/blob/main/src/modules/assistant/brief.ts"
click node_google "https://github.com/hgleung/discord-squire/blob/main/src/modules/assistant/google.ts"
click node_assistant_state "https://github.com/hgleung/discord-squire/tree/main/src/modules/assistant"
click node_vault "https://github.com/hgleung/discord-squire/blob/main/src/vault.ts"
click node_training_module "https://github.com/hgleung/discord-squire/blob/main/src/modules/training/index.ts"
click node_training_service "https://github.com/hgleung/discord-squire/blob/main/src/modules/training/service.ts"
click node_plan_store "https://github.com/hgleung/discord-squire/blob/main/src/modules/training/store.ts"
click node_plan_ops "https://github.com/hgleung/discord-squire/blob/main/lib/planOps.ts"
click node_scoring "https://github.com/hgleung/discord-squire/blob/main/lib/scoring.ts"
click node_week_summary "https://github.com/hgleung/discord-squire/blob/main/lib/weekSummary.ts"
click node_muscles "https://github.com/hgleung/discord-squire/blob/main/lib/muscles.ts"
click node_dates "https://github.com/hgleung/discord-squire/blob/main/lib/dateUtils.ts"
click node_web_ui "https://github.com/hgleung/discord-squire/blob/main/web/src/App.tsx"
click node_web_hook "https://github.com/hgleung/discord-squire/blob/main/web/src/hooks/usePlan.ts"
click node_web_api "https://github.com/hgleung/discord-squire/blob/main/web/src/lib/api.ts"
click node_music_module "https://github.com/hgleung/discord-squire/blob/main/src/modules/music/index.ts"
click node_music_player "https://github.com/hgleung/discord-squire/blob/main/src/modules/music/player.ts"
click node_system_module "https://github.com/hgleung/discord-squire/blob/main/src/modules/system/index.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_entry,node_router,node_vault,node_system_module,node_user toneBlue
class node_assistant_module,node_agent,node_llm,node_background,node_factory,node_brief,node_google,node_assistant_state toneAmber
class node_training_module,node_training_service,node_plan_store,node_plan_ops,node_scoring,node_week_summary,node_muscles,node_dates,node_web_ui,node_web_hook,node_web_api,node_model toneMint
class node_music_module,node_music_player toneRose
class node_discord,node_youtube toneIndigo
```

## Components

### Bot runtime

- [Bot startup](https://github.com/hgleung/discord-squire/blob/main/src/index.ts): `src/index.ts`
- [Command routing](https://github.com/hgleung/discord-squire/blob/main/src/bot.ts): `src/bot.ts`
- [Obsidian vault](https://github.com/hgleung/discord-squire/blob/main/src/vault.ts): `src/vault.ts`
- [Update command](https://github.com/hgleung/discord-squire/blob/main/src/modules/system/index.ts): `src/modules/system/index.ts`

### Assistant

- [Chat module](https://github.com/hgleung/discord-squire/blob/main/src/modules/assistant/index.ts): `src/modules/assistant/index.ts`
- [Chat agent](https://github.com/hgleung/discord-squire/blob/main/src/modules/assistant/agent.ts): `src/modules/assistant/agent.ts`
- [Tool protocol](https://github.com/hgleung/discord-squire/blob/main/src/modules/assistant/llm.ts): `src/modules/assistant/llm.ts`
- [Background tasks](https://github.com/hgleung/discord-squire/blob/main/src/modules/assistant/tasks.ts): `src/modules/assistant/tasks.ts`
- [Job factories](https://github.com/hgleung/discord-squire/blob/main/src/modules/assistant/factory.ts): `src/modules/assistant/factory.ts`
- [Calendar brief](https://github.com/hgleung/discord-squire/blob/main/src/modules/assistant/brief.ts): `src/modules/assistant/brief.ts`
- [Google services](https://github.com/hgleung/discord-squire/blob/main/src/modules/assistant/google.ts): `src/modules/assistant/google.ts`
- [Reminders, memory](https://github.com/hgleung/discord-squire/tree/main/src/modules/assistant): `src/modules/assistant`

### Training log

- [Training commands](https://github.com/hgleung/discord-squire/blob/main/src/modules/training/index.ts): `src/modules/training/index.ts`
- [Workout service](https://github.com/hgleung/discord-squire/blob/main/src/modules/training/service.ts): `src/modules/training/service.ts`
- [Plan storage](https://github.com/hgleung/discord-squire/blob/main/src/modules/training/store.ts): `src/modules/training/store.ts`
- [Plan operations](https://github.com/hgleung/discord-squire/blob/main/lib/planOps.ts): `lib/planOps.ts`
- [Workout scoring](https://github.com/hgleung/discord-squire/blob/main/lib/scoring.ts): `lib/scoring.ts`
- [Weekly summary](https://github.com/hgleung/discord-squire/blob/main/lib/weekSummary.ts): `lib/weekSummary.ts`
- [Muscle targets](https://github.com/hgleung/discord-squire/blob/main/lib/muscles.ts): `lib/muscles.ts`
- [Date utilities](https://github.com/hgleung/discord-squire/blob/main/lib/dateUtils.ts): `lib/dateUtils.ts`
- [Training web UI](https://github.com/hgleung/discord-squire/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Plan sync hook](https://github.com/hgleung/discord-squire/blob/main/web/src/hooks/usePlan.ts): `web/src/hooks/usePlan.ts`
- [Plan API](https://github.com/hgleung/discord-squire/blob/main/web/src/lib/api.ts): `web/src/lib/api.ts`

### Music

- [Music commands](https://github.com/hgleung/discord-squire/blob/main/src/modules/music/index.ts): `src/modules/music/index.ts`
- [Audio player](https://github.com/hgleung/discord-squire/blob/main/src/modules/music/player.ts): `src/modules/music/player.ts`

### Other components

- **Discord user**
- **Discord**
- **Anthropic API**
- **YouTube audio**

## Connections

- Discord user → Discord: sends command
- Discord → Command routing: delivers events
- Bot startup → Command routing: starts (evidence: `src/index.ts`)
- Bot startup → Chat module: registers (evidence: `src/index.ts`)
- Bot startup → Training commands: registers (evidence: `src/index.ts`)
- Bot startup → Music commands: registers (evidence: `src/index.ts`)
- Bot startup → Update command: registers (evidence: `src/index.ts`)
- Command routing → Chat module: dispatches
- Command routing → Training commands: dispatches
- Command routing → Music commands: dispatches
- Chat module → Chat agent: invokes (evidence: `src/modules/assistant/index.ts`)
- Chat agent → Tool protocol: uses tools (evidence: `src/modules/assistant/llm.ts`)
- Chat agent → Anthropic API: requests completion
- Chat module → Background tasks: starts tasks (evidence: `src/modules/assistant/index.ts`)
- Background tasks → Tool protocol: runs tools (evidence: `src/modules/assistant/tasks.ts`)
- Background tasks → Job factories: loads prompt (evidence: `src/modules/assistant/tasks.ts`)
- Background tasks → Obsidian vault: reads and writes notes (evidence: `src/modules/assistant/tasks.ts`)
- Chat module → Calendar brief: generates brief (evidence: `src/modules/assistant/index.ts`)
- Calendar brief → Google services: uses calendar
- Chat module → Reminders, memory: manages (evidence: `src/modules/assistant/index.ts`)
- Chat module → Workout service: answers gym queries (evidence: `src/modules/assistant/index.ts`)
- Training commands → Workout service: handles commands (evidence: `src/modules/training/index.ts`)
- Workout service → Plan storage: reads and updates (evidence: `src/modules/training/service.ts`)
- Workout service → Plan operations: updates plan (evidence: `src/modules/training/service.ts`)
- Workout service → Workout scoring: calculates progress (evidence: `src/modules/training/service.ts`)
- Workout service → Weekly summary: builds weekly facts (evidence: `src/modules/training/service.ts`)
- Weekly summary → Workout scoring: computes statistics (evidence: `lib/weekSummary.ts`)
- Workout scoring → Muscle targets: uses targets (evidence: `lib/scoring.ts`)
- Workout service → Date utilities: formats dates (evidence: `src/modules/training/service.ts`)
- Plan storage → Obsidian vault: persists plan (evidence: `src/modules/training/store.ts`)
- Discord user → Training web UI: logs workout
- Training web UI → Plan sync hook: uses plan state (evidence: `web/src/App.tsx`)
- Plan sync hook → Plan API: fetches and saves (evidence: `web/src/hooks/usePlan.ts`)
- Training web UI → Plan operations: edits plan (evidence: `web/src/App.tsx`)
- Music commands → Audio player: controls playback (evidence: `src/modules/music/index.ts`)
- Audio player → YouTube audio: streams audio
