# prosofproest/ipdc-bot architecture

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

- Interactive diagram: https://gitdiagram.com/prosofproest/ipdc-bot
- Repository: https://github.com/prosofproest/ipdc-bot

## Overview

IPDC is a Discord community-management bot. Members enter through Code-of-Conduct acceptance and an application; staff or PMs review requests, after which the bot assigns roles and provisions team workspaces. PMs configure monitored repositories, while GitHub activity, support tickets, admin controls, and scheduled emailed reports provide ongoing operations. The graph includes core routing, authorization, persistence, and reconciliation layers. Several feature implementations were not excerpted, so their documented capabilities are represented without speculative internal call chains.

Main entry points: [`src/core/router.js`](https://github.com/prosofproest/ipdc-bot/blob/main/src/core/router.js) (Interaction router), [`src/features/admin.js`](https://github.com/prosofproest/ipdc-bot/blob/main/src/features/admin.js) (Admin panel), [`src/github/monitoring.js`](https://github.com/prosofproest/ipdc-bot/blob/main/src/github/monitoring.js) (Activity monitoring), [`src/features/pm.js`](https://github.com/prosofproest/ipdc-bot/blob/main/src/features/pm.js) (PM control panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Member workflows"]
  node_onboarding["Onboarding<br/>[onboarding.js]"]
  node_applications["Applications and requests<br/>[requests.js]"]
  node_support["Support tickets<br/>[support.js]"]
end

subgraph group_operations["Staff operations"]
  node_admin_panel["Admin panel<br/>[admin.js]"]
  node_pm_panel["PM control panel<br/>[pm.js]"]
  node_panel_setup["Panel setup<br/>[panels.js]"]
  node_workspace["Workspace provisioning<br/>[workspace.js]"]
  node_reconcile["Structure reconciliation<br/>[reconcile.js]"]
  node_roles["Dynamic roles<br/>[dynamicRoles.js]"]
end

subgraph group_github["GitHub and reporting"]
  node_github_feature["GitHub identity linking<br/>[github.js]"]
  node_monitoring["Activity monitoring<br/>[monitoring.js]"]
  node_github_client["GitHub client<br/>[client.js]"]
  node_activity["Activity data<br/>[activity.js]"]
  node_reports["PDF reports<br/>[reports.js]"]
end

subgraph group_platform["Discord platform core"]
  node_router["Interaction router<br/>[router.js]"]
  node_authorization["Authorization<br/>[auth.js]"]
end

subgraph group_services["Persistence and services"]
  node_state["Domain state<br/>[state.js]"]
  node_firestore[("Firestore store<br/>[firestore.js]")]
  node_queue["Durable queue<br/>[queue.js]"]
  node_scheduler["Scheduler<br/>[scheduler.js]"]
  node_ai["AI failover<br/>[ai.js]"]
  node_mailer["SMTP mailer<br/>[mailer.js]"]
  node_webhook["GitHub webhook<br/>[webhook.js]"]
end

node_member(("Discord members"))
node_admin_actor(("IPDC GRID staff"))
node_discord{{"Discord"}}
node_github_service{{"GitHub"}}
node_smtp{{"SMTP provider"}}
node_firestore_service[("Cloud Firestore")]
node_ai_providers{{"Gemini and Groq"}}

node_member -->|"starts verification"| node_onboarding
node_onboarding -->|"submits application"| node_applications
node_applications -->|"routes PM applications"| node_admin_panel
node_applications -->|"routes member approvals"| node_pm_panel
node_member -->|"opens tickets"| node_support
node_admin_actor -->|"manages community"| node_admin_panel
node_admin_panel -->|"repairs structure"| node_reconcile
node_admin_panel -->|"provisions PM workspace"| node_workspace
node_workspace -->|"provisions team roles"| node_roles
node_pm_panel -->|"validates repository"| node_github_client
node_pm_panel -->|"requests refresh"| node_monitoring
node_github_feature -->|"links identity"| node_github_client
node_monitoring -->|"fetches activity"| node_github_client
node_monitoring -->|"uses contribution data"| node_activity
node_monitoring -->|"supports daily reports"| node_reports
node_reports -->|"emails PDF reports"| node_smtp
node_github_service -.->|"sends event"| node_webhook
node_webhook -.->|"triggers refresh"| node_monitoring
node_discord -->|"delivers interactions"| node_router
node_router -.->|"dispatches handlers"| node_onboarding
node_router -.->|"dispatches handlers"| node_applications
node_router -.->|"dispatches handlers"| node_support
node_router -->|"dispatches handlers"| node_admin_panel
node_router -.->|"dispatches handlers"| node_pm_panel
node_admin_panel -->|"checks access"| node_authorization
node_pm_panel -->|"checks access"| node_authorization
node_state -.->|"persists state"| node_firestore
node_firestore -->|"reads and writes"| node_firestore_service
node_onboarding -->|"schedules channel cleanup"| node_queue
node_scheduler -.->|"runs scheduled refreshes"| node_monitoring
node_ai -->|"falls back on error"| node_ai_providers

click node_onboarding "https://github.com/prosofproest/ipdc-bot/blob/main/src/features/onboarding.js"
click node_applications "https://github.com/prosofproest/ipdc-bot/blob/main/src/features/requests.js"
click node_support "https://github.com/prosofproest/ipdc-bot/blob/main/src/features/support.js"
click node_admin_panel "https://github.com/prosofproest/ipdc-bot/blob/main/src/features/admin.js"
click node_pm_panel "https://github.com/prosofproest/ipdc-bot/blob/main/src/features/pm.js"
click node_panel_setup "https://github.com/prosofproest/ipdc-bot/blob/main/src/features/panels.js"
click node_workspace "https://github.com/prosofproest/ipdc-bot/blob/main/src/core/workspace.js"
click node_reconcile "https://github.com/prosofproest/ipdc-bot/blob/main/src/core/reconcile.js"
click node_roles "https://github.com/prosofproest/ipdc-bot/blob/main/src/core/dynamicRoles.js"
click node_github_feature "https://github.com/prosofproest/ipdc-bot/blob/main/src/features/github.js"
click node_monitoring "https://github.com/prosofproest/ipdc-bot/blob/main/src/github/monitoring.js"
click node_github_client "https://github.com/prosofproest/ipdc-bot/blob/main/src/github/client.js"
click node_activity "https://github.com/prosofproest/ipdc-bot/blob/main/src/github/activity.js"
click node_reports "https://github.com/prosofproest/ipdc-bot/blob/main/src/github/reports.js"
click node_router "https://github.com/prosofproest/ipdc-bot/blob/main/src/core/router.js"
click node_authorization "https://github.com/prosofproest/ipdc-bot/blob/main/src/core/auth.js"
click node_state "https://github.com/prosofproest/ipdc-bot/blob/main/src/core/state.js"
click node_firestore "https://github.com/prosofproest/ipdc-bot/blob/main/src/storage/firestore.js"
click node_queue "https://github.com/prosofproest/ipdc-bot/blob/main/src/core/queue.js"
click node_scheduler "https://github.com/prosofproest/ipdc-bot/blob/main/src/scheduler.js"
click node_ai "https://github.com/prosofproest/ipdc-bot/blob/main/src/services/ai.js"
click node_mailer "https://github.com/prosofproest/ipdc-bot/blob/main/src/services/mailer.js"
click node_webhook "https://github.com/prosofproest/ipdc-bot/blob/main/src/webhook.js"

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,node_applications,node_support toneBlue
class node_admin_panel,node_pm_panel,node_panel_setup,node_workspace,node_reconcile,node_roles,node_firestore_service toneAmber
class node_github_feature,node_monitoring,node_github_client,node_activity,node_reports toneMint
class node_router,node_authorization toneRose
class node_state,node_firestore,node_queue,node_scheduler,node_ai,node_mailer,node_webhook,node_member,node_admin_actor,node_discord,node_github_service,node_smtp,node_ai_providers toneIndigo
```

## Components

### Member workflows

- [Onboarding](https://github.com/prosofproest/ipdc-bot/blob/main/src/features/onboarding.js): `src/features/onboarding.js`
- [Applications and requests](https://github.com/prosofproest/ipdc-bot/blob/main/src/features/requests.js): `src/features/requests.js`
- [Support tickets](https://github.com/prosofproest/ipdc-bot/blob/main/src/features/support.js): `src/features/support.js`

### Staff operations

- [Admin panel](https://github.com/prosofproest/ipdc-bot/blob/main/src/features/admin.js): `src/features/admin.js`
- [PM control panel](https://github.com/prosofproest/ipdc-bot/blob/main/src/features/pm.js): `src/features/pm.js`
- [Panel setup](https://github.com/prosofproest/ipdc-bot/blob/main/src/features/panels.js): `src/features/panels.js`
- [Workspace provisioning](https://github.com/prosofproest/ipdc-bot/blob/main/src/core/workspace.js): `src/core/workspace.js`
- [Structure reconciliation](https://github.com/prosofproest/ipdc-bot/blob/main/src/core/reconcile.js): `src/core/reconcile.js`
- [Dynamic roles](https://github.com/prosofproest/ipdc-bot/blob/main/src/core/dynamicRoles.js): `src/core/dynamicRoles.js`

### GitHub and reporting

- [GitHub identity linking](https://github.com/prosofproest/ipdc-bot/blob/main/src/features/github.js): `src/features/github.js`
- [Activity monitoring](https://github.com/prosofproest/ipdc-bot/blob/main/src/github/monitoring.js): `src/github/monitoring.js`
- [GitHub client](https://github.com/prosofproest/ipdc-bot/blob/main/src/github/client.js): `src/github/client.js`
- [Activity data](https://github.com/prosofproest/ipdc-bot/blob/main/src/github/activity.js): `src/github/activity.js`
- [PDF reports](https://github.com/prosofproest/ipdc-bot/blob/main/src/github/reports.js): `src/github/reports.js`

### Discord platform core

- [Interaction router](https://github.com/prosofproest/ipdc-bot/blob/main/src/core/router.js): `src/core/router.js`
- [Authorization](https://github.com/prosofproest/ipdc-bot/blob/main/src/core/auth.js): `src/core/auth.js`

### Persistence and services

- [Domain state](https://github.com/prosofproest/ipdc-bot/blob/main/src/core/state.js): `src/core/state.js`
- [Firestore store](https://github.com/prosofproest/ipdc-bot/blob/main/src/storage/firestore.js): `src/storage/firestore.js`
- [Durable queue](https://github.com/prosofproest/ipdc-bot/blob/main/src/core/queue.js): `src/core/queue.js`
- [Scheduler](https://github.com/prosofproest/ipdc-bot/blob/main/src/scheduler.js): `src/scheduler.js`
- [AI failover](https://github.com/prosofproest/ipdc-bot/blob/main/src/services/ai.js): `src/services/ai.js`
- [SMTP mailer](https://github.com/prosofproest/ipdc-bot/blob/main/src/services/mailer.js): `src/services/mailer.js`
- [GitHub webhook](https://github.com/prosofproest/ipdc-bot/blob/main/src/webhook.js): `src/webhook.js`

### Other components

- **Discord members**
- **IPDC GRID staff**
- **Discord**
- **GitHub**
- **SMTP provider**
- **Cloud Firestore**
- **Gemini and Groq**

## Connections

- Discord members → Onboarding: starts verification (evidence: `README.md`)
- Onboarding → Applications and requests: submits application (evidence: `README.md`)
- Applications and requests → Admin panel: routes PM applications (evidence: `README.md`)
- Applications and requests → PM control panel: routes member approvals (evidence: `README.md`)
- Discord members → Support tickets: opens tickets (evidence: `README.md`)
- IPDC GRID staff → Admin panel: manages community (evidence: `README.md`)
- Admin panel → Structure reconciliation: repairs structure (evidence: `src/features/admin.js`)
- Admin panel → Workspace provisioning: provisions PM workspace (evidence: `README.md`)
- Workspace provisioning → Dynamic roles: provisions team roles (evidence: `src/core/workspace.js`)
- PM control panel → GitHub client: validates repository (evidence: `src/features/pm.js`)
- PM control panel → Activity monitoring: requests refresh (evidence: `src/features/pm.js`)
- GitHub identity linking → GitHub client: links identity (evidence: `README.md`)
- Activity monitoring → GitHub client: fetches activity (evidence: `src/github/monitoring.js`)
- Activity monitoring → Activity data: uses contribution data (evidence: `src/github/monitoring.js`)
- Activity monitoring → PDF reports: supports daily reports (evidence: `README.md`)
- PDF reports → SMTP provider: emails PDF reports (evidence: `README.md`)
- GitHub → GitHub webhook: sends event (evidence: `README.md`)
- GitHub webhook → Activity monitoring: triggers refresh (evidence: `README.md`)
- Discord → Interaction router: delivers interactions (evidence: `README.md`)
- Interaction router → Onboarding: dispatches handlers (evidence: `src/features/onboarding.js`)
- Interaction router → Applications and requests: dispatches handlers (evidence: `src/features/requests.js`)
- Interaction router → Support tickets: dispatches handlers (evidence: `src/features/support.js`)
- Interaction router → Admin panel: dispatches handlers (evidence: `src/features/admin.js`)
- Interaction router → PM control panel: dispatches handlers (evidence: `src/features/pm.js`)
- Admin panel → Authorization: checks access (evidence: `src/features/admin.js`)
- PM control panel → Authorization: checks access (evidence: `src/features/pm.js`)
- Domain state → Firestore store: persists state
- Firestore store → Cloud Firestore: reads and writes (evidence: `README.md`)
- Onboarding → Durable queue: schedules channel cleanup (evidence: `README.md`)
- Scheduler → Activity monitoring: runs scheduled refreshes
- AI failover → Gemini and Groq: falls back on error (evidence: `README.md`)
