# lam5943/cse-hq-bot-2026 architecture

> Architecture diagram of the GitHub repository lam5943/cse-hq-bot-2026, 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/lam5943/cse-hq-bot-2026
- Repository: https://github.com/lam5943/cse-hq-bot-2026

## Overview

CSE-HQ is a Discord-native project coordination bot. Users interact through Discord commands and views; those reach project operations, collaboration records, reporting, and grounded AI features, with SQLite persistence. Optional GitHub synchronization and webhook-driven Forum publishing form a separate integration branch. The README documents capabilities such as welcomes and scheduled dashboard snapshots whose implementation wiring is not established by the excerpts, so those are represented only where the tree supports a component; edges rely on README statements or SOURCE INDEX references, not unsampled call-flow assumptions.

Main entry points: [`cse_hq_bot/repositories`](https://github.com/lam5943/cse-hq-bot-2026/tree/main/cse_hq_bot/repositories) (Domain repositories), [`cse_hq_bot/ui.py`](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/ui.py) (Commands and views), [`cse_hq_bot/services/ai_session_service.py`](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/ai_session_service.py) (Assistant sessions), [`cse_hq_bot/services/ai_service.py`](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/ai_service.py) (Grounded AI answers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discord["Discord interface"]
  node_bot["Bot runtime<br/>[bot.py]"]
  node_views["Commands and views<br/>[ui.py]"]
end

subgraph group_coordination["Project coordination"]
  node_permissions["Role permissions<br/>[permissions.py]"]
  node_project["Project settings<br/>[project_service.py]"]
  node_tasks["Task operations<br/>[task_service.py]"]
  node_bugs["Bug operations<br/>[bug_service.py]"]
  node_collaboration["Meetings and decisions<br/>[meeting_service.py]"]
  node_standups["Standup tracking<br/>[standup_service.py]"]
  node_reports["Progress reports<br/>[report_service.py]"]
  node_dashboard["Weekly dashboard"]
end

subgraph group_assistant["Grounded assistant"]
  node_ai_sessions["Assistant sessions"]
  node_ai["Grounded AI answers<br/>[ai_service.py]"]
  node_context["Project context retrieval"]
  node_actions["Confirmed AI actions"]
  node_providers["AI providers<br/>[provider_router.py]"]
  node_web_research["Read-only web research"]
end

subgraph group_persistence["Persistence"]
  node_database[("SQLite database<br/>[db.py]")]
  node_repositories["Domain repositories"]
end

subgraph group_integrations["External integrations"]
  node_github["GitHub integration<br/>[github_service.py]"]
  node_github_api["GitHub API provider<br/>[github_provider.py]"]
  node_webhook["GitHub webhook<br/>[github_webhook.py]"]
  node_forum["Forum publishing"]
  node_discord_forum["Discord Forum gateway"]
end

node_user(("Discord users"))
node_github_external(("GitHub"))
node_tavily(("Tavily search"))

node_user -->|"uses Discord"| node_bot
node_bot -->|"registers interface"| node_views
node_views -->|"invokes operations"| node_project
node_views -->|"invokes operations"| node_tasks
node_views -->|"invokes operations"| node_bugs
node_views -->|"invokes operations"| node_collaboration
node_views -->|"invokes operations"| node_standups
node_views -->|"invokes operations"| node_github
node_tasks -->|"checks access"| node_permissions
node_bugs -->|"checks access"| node_permissions
node_collaboration -->|"checks access"| node_permissions
node_project -->|"uses repository"| node_repositories
node_tasks -->|"uses repository"| node_repositories
node_bugs -->|"uses repository"| node_repositories
node_collaboration -->|"uses repository"| node_repositories
node_repositories -->|"reads and writes"| node_database
node_views -.->|"starts sessions"| node_ai_sessions
node_ai_sessions -->|"requests answers"| node_ai
node_ai -->|"retrieves project context"| node_context
node_ai -.->|"generates response"| node_providers
node_ai -->|"requests research"| node_web_research
node_web_research -.->|"searches web"| node_tavily
node_ai_sessions -->|"persists sessions"| node_repositories
node_ai_sessions -->|"handles proposals"| node_actions
node_actions -->|"persists proposals"| node_repositories
node_github -->|"fetches repository data"| node_github_api
node_github -->|"caches records"| node_repositories
node_github_external -.->|"provides repository data"| node_github_api
node_github_external -->|"sends events"| node_webhook
node_webhook -->|"routes events"| node_forum
node_forum -->|"deduplicates publications"| node_repositories
node_forum -.->|"publishes posts"| node_discord_forum
node_reports -.->|"reads project records"| node_repositories
node_dashboard -.->|"stores snapshots"| node_repositories

click node_bot "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/bot.py"
click node_views "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/ui.py"
click node_permissions "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/permissions.py"
click node_project "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/project_service.py"
click node_tasks "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/task_service.py"
click node_bugs "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/bug_service.py"
click node_collaboration "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/meeting_service.py"
click node_standups "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/standup_service.py"
click node_reports "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/report_service.py"
click node_dashboard "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/weekly_dashboard_service.py"
click node_ai_sessions "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/ai_session_service.py"
click node_ai "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/ai_service.py"
click node_context "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/project_context_service.py"
click node_actions "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/ai_action_service.py"
click node_providers "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/ai/provider_router.py"
click node_web_research "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/web_research_service.py"
click node_database "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/db.py"
click node_repositories "https://github.com/lam5943/cse-hq-bot-2026/tree/main/cse_hq_bot/repositories"
click node_github "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/github_service.py"
click node_github_api "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/github_provider.py"
click node_webhook "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/github_webhook.py"
click node_forum "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/forum_publishing_service.py"
click node_discord_forum "https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/discord_forum_gateway.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_bot,node_views,node_user toneBlue
class node_permissions,node_project,node_tasks,node_bugs,node_collaboration,node_standups,node_reports,node_dashboard toneAmber
class node_ai_sessions,node_ai,node_context,node_actions,node_providers,node_web_research toneMint
class node_database,node_repositories toneRose
class node_github,node_github_api,node_webhook,node_forum,node_discord_forum,node_github_external,node_tavily toneIndigo
```

## Components

### Discord interface

- [Bot runtime](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/bot.py): `cse_hq_bot/bot.py`
- [Commands and views](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/ui.py): `cse_hq_bot/ui.py`

### Project coordination

- [Role permissions](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/permissions.py): `cse_hq_bot/permissions.py`
- [Project settings](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/project_service.py): `cse_hq_bot/services/project_service.py`
- [Task operations](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/task_service.py): `cse_hq_bot/services/task_service.py`
- [Bug operations](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/bug_service.py): `cse_hq_bot/services/bug_service.py`
- [Meetings and decisions](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/meeting_service.py): `cse_hq_bot/services/meeting_service.py`
- [Standup tracking](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/standup_service.py): `cse_hq_bot/services/standup_service.py`
- [Progress reports](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/report_service.py): `cse_hq_bot/services/report_service.py`
- [Weekly dashboard](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/weekly_dashboard_service.py): `cse_hq_bot/services/weekly_dashboard_service.py`

### Grounded assistant

- [Assistant sessions](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/ai_session_service.py): `cse_hq_bot/services/ai_session_service.py`
- [Grounded AI answers](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/ai_service.py): `cse_hq_bot/services/ai_service.py`
- [Project context retrieval](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/project_context_service.py): `cse_hq_bot/services/project_context_service.py`
- [Confirmed AI actions](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/ai_action_service.py): `cse_hq_bot/services/ai_action_service.py`
- [AI providers](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/ai/provider_router.py): `cse_hq_bot/ai/provider_router.py`
- [Read-only web research](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/web_research_service.py): `cse_hq_bot/services/web_research_service.py`

### Persistence

- [SQLite database](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/db.py): `cse_hq_bot/db.py`
- [Domain repositories](https://github.com/lam5943/cse-hq-bot-2026/tree/main/cse_hq_bot/repositories): `cse_hq_bot/repositories`

### External integrations

- [GitHub integration](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/github_service.py): `cse_hq_bot/services/github_service.py`
- [GitHub API provider](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/github_provider.py): `cse_hq_bot/github_provider.py`
- [GitHub webhook](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/github_webhook.py): `cse_hq_bot/github_webhook.py`
- [Forum publishing](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/services/forum_publishing_service.py): `cse_hq_bot/services/forum_publishing_service.py`
- [Discord Forum gateway](https://github.com/lam5943/cse-hq-bot-2026/blob/main/cse_hq_bot/discord_forum_gateway.py): `cse_hq_bot/discord_forum_gateway.py`

### Other components

- **Discord users**
- **GitHub**
- **Tavily search**

## Connections

- Discord users → Bot runtime: uses Discord
- Bot runtime → Commands and views: registers interface (evidence: `cse_hq_bot/bot.py`)
- Commands and views → Project settings: invokes operations (evidence: `cse_hq_bot/ui.py`)
- Commands and views → Task operations: invokes operations (evidence: `cse_hq_bot/ui.py`)
- Commands and views → Bug operations: invokes operations (evidence: `cse_hq_bot/ui.py`)
- Commands and views → Meetings and decisions: invokes operations (evidence: `cse_hq_bot/ui.py`)
- Commands and views → Standup tracking: invokes operations (evidence: `cse_hq_bot/ui.py`)
- Commands and views → GitHub integration: invokes operations (evidence: `cse_hq_bot/ui.py`)
- Task operations → Role permissions: checks access (evidence: `cse_hq_bot/services/task_service.py`)
- Bug operations → Role permissions: checks access (evidence: `cse_hq_bot/services/bug_service.py`)
- Meetings and decisions → Role permissions: checks access (evidence: `cse_hq_bot/services/meeting_service.py`)
- Project settings → Domain repositories: uses repository (evidence: `cse_hq_bot/services/project_service.py`)
- Task operations → Domain repositories: uses repository (evidence: `cse_hq_bot/services/task_service.py`)
- Bug operations → Domain repositories: uses repository (evidence: `cse_hq_bot/services/bug_service.py`)
- Meetings and decisions → Domain repositories: uses repository (evidence: `cse_hq_bot/services/meeting_service.py`)
- Domain repositories → SQLite database: reads and writes (evidence: `cse_hq_bot/repositories/collab_repository.py`)
- Commands and views → Assistant sessions: starts sessions
- Assistant sessions → Grounded AI answers: requests answers (evidence: `cse_hq_bot/services/ai_session_service.py`)
- Grounded AI answers → Project context retrieval: retrieves project context (evidence: `cse_hq_bot/services/ai_service.py`)
- Grounded AI answers → AI providers: generates response
- Grounded AI answers → Read-only web research: requests research (evidence: `cse_hq_bot/services/ai_service.py`)
- Read-only web research → Tavily search: searches web
- Assistant sessions → Domain repositories: persists sessions (evidence: `cse_hq_bot/services/ai_session_service.py`)
- Assistant sessions → Confirmed AI actions: handles proposals (evidence: `cse_hq_bot/services/ai_session_service.py`)
- Confirmed AI actions → Domain repositories: persists proposals (evidence: `cse_hq_bot/services/ai_action_service.py`)
- GitHub integration → GitHub API provider: fetches repository data (evidence: `cse_hq_bot/services/github_service.py`)
- GitHub integration → Domain repositories: caches records (evidence: `cse_hq_bot/services/github_service.py`)
- GitHub → GitHub API provider: provides repository data
- GitHub → GitHub webhook: sends events (evidence: `cse_hq_bot/github_webhook.py`)
- GitHub webhook → Forum publishing: routes events (evidence: `cse_hq_bot/github_webhook.py`)
- Forum publishing → Domain repositories: deduplicates publications (evidence: `cse_hq_bot/services/forum_publishing_service.py`)
- Forum publishing → Discord Forum gateway: publishes posts
- Progress reports → Domain repositories: reads project records
- Weekly dashboard → Domain repositories: stores snapshots