# nawaz-builds/gitcord-githubdiscordbot architecture

> Architecture diagram of the GitHub repository nawaz-builds/gitcord-githubdiscordbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nawaz-builds/gitcord-githubdiscordbot
- Repository: https://github.com/nawaz-builds/gitcord-githubdiscordbot

## Overview

Gitcord is an offline-first GitHub–Discord automation bot. Its documented run-once workflow loads configuration, ingests activity, plans changes, produces audit reports, and optionally applies permitted writes; Discord slash commands provide a separate interactive path for identity linking, profiles, metrics, and notifications. The graph preserves those product areas and the SQLite state layer. Several subsystem links follow the README’s documented workflow; unsampled implementation details are not asserted as verified calls.

Main entry points: [`src/ghdcbot/engine/orchestrator.py`](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/engine/orchestrator.py) (Sync orchestration), [`src/ghdcbot/bot.py`](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/bot.py) (Discord bot), [`src/ghdcbot/cli.py`](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/cli.py) (CLI), [`src/ghdcbot/adapters/storage/sqlite.py`](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/adapters/storage/sqlite.py) (SQLite state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI<br/>[cli.py]"]
  node_bot["Discord bot<br/>[bot.py]"]
end

subgraph group_workflow["Sync workflow"]
  node_orchestrator["Sync orchestration<br/>[orchestrator.py]"]
  node_planning["Deterministic planning<br/>[planning.py]"]
  node_assignment["Assignment strategy<br/>[assignment.py]"]
  node_audit["Audit reports<br/>[audit_export.py]"]
  node_reporting["Sync reporting<br/>[reporting.py]"]
  node_snapshots["Sync snapshots<br/>[snapshots.py]"]
  node_notifications["Notifications<br/>[notifications.py]"]
end

subgraph group_adapters["Platform adapters"]
  node_ingestion["Activity readers<br/>[rest.py]"]
  node_github_write["GitHub writes<br/>[writer.py]"]
  node_discord_api["Discord API<br/>[api.py]"]
  node_discord_write["Discord writes<br/>[writer.py]"]
end

subgraph group_social["Discord features"]
  node_identity["Identity linking"]
  node_social_profiles["Contributor profiles<br/>[social_profiles.py]"]
  node_social_commands["Social commands<br/>[social_commands.py]"]
  node_metrics["Metrics<br/>[metrics.py]"]
end

subgraph group_foundation["Configuration and state"]
  node_config["Config loading<br/>[loader.py]"]
  node_config_models["Config models<br/>[models.py]"]
  node_storage[("SQLite state<br/>[sqlite.py]")]
end

node_operator(("Operator"))
node_github(("GitHub"))
node_discord(("Discord users"))

node_operator -->|"runs"| node_cli
node_operator -->|"uses commands"| node_bot
node_cli -->|"loads"| node_config
node_config -->|"validates"| node_config_models
node_cli -->|"runs sync"| node_orchestrator
node_orchestrator -->|"ingests activity"| node_ingestion
node_github -->|"provides activity"| node_ingestion
node_orchestrator -->|"plans changes"| node_planning
node_planning -.->|"uses strategy"| node_assignment
node_orchestrator -->|"exports audit"| node_audit
node_orchestrator -.->|"generates reports"| node_reporting
node_orchestrator -.->|"records snapshots"| node_snapshots
node_orchestrator -->|"optionally applies"| node_github_write
node_orchestrator -->|"optionally applies"| node_discord_write
node_github_write -->|"mutates"| node_github
node_discord_write -->|"mutates"| node_discord
node_bot -.->|"serves commands"| node_discord_api
node_bot -->|"handles linking"| node_identity
node_bot -->|"registers commands"| node_social_commands
node_social_commands -->|"uses profiles"| node_social_profiles
node_bot -->|"offers metrics"| node_metrics
node_bot -.->|"offers notifications"| node_notifications
node_identity -->|"persists links"| node_storage
node_social_profiles -->|"reads and writes"| node_storage
node_orchestrator -.->|"uses state"| node_storage

click node_cli "https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/cli.py"
click node_bot "https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/bot.py"
click node_config "https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/config/loader.py"
click node_config_models "https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/config/models.py"
click node_orchestrator "https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/engine/orchestrator.py"
click node_ingestion "https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/adapters/github/rest.py"
click node_planning "https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/engine/planning.py"
click node_assignment "https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/engine/assignment.py"
click node_audit "https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/engine/audit_export.py"
click node_reporting "https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/engine/reporting.py"
click node_snapshots "https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/engine/snapshots.py"
click node_github_write "https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/adapters/github/writer.py"
click node_discord_api "https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/adapters/discord/api.py"
click node_discord_write "https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/adapters/discord/writer.py"
click node_identity "https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/engine/identity_linking.py"
click node_social_profiles "https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/engine/social_profiles.py"
click node_social_commands "https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/adapters/discord/social_commands.py"
click node_metrics "https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/engine/metrics.py"
click node_notifications "https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/engine/notifications.py"
click node_storage "https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/adapters/storage/sqlite.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_cli,node_bot,node_discord toneBlue
class node_orchestrator,node_planning,node_assignment,node_audit,node_reporting,node_snapshots,node_notifications toneAmber
class node_ingestion,node_github_write,node_discord_api,node_discord_write toneMint
class node_identity,node_social_profiles,node_social_commands,node_metrics toneRose
class node_config,node_config_models,node_storage,node_operator,node_github toneIndigo
```

## Components

### Entry points

- [CLI](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/cli.py): `src/ghdcbot/cli.py`
- [Discord bot](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/bot.py): `src/ghdcbot/bot.py`

### Sync workflow

- [Sync orchestration](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/engine/orchestrator.py): `src/ghdcbot/engine/orchestrator.py`
- [Deterministic planning](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/engine/planning.py): `src/ghdcbot/engine/planning.py`
- [Assignment strategy](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/engine/assignment.py): `src/ghdcbot/engine/assignment.py`
- [Audit reports](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/engine/audit_export.py): `src/ghdcbot/engine/audit_export.py`
- [Sync reporting](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/engine/reporting.py): `src/ghdcbot/engine/reporting.py`
- [Sync snapshots](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/engine/snapshots.py): `src/ghdcbot/engine/snapshots.py`
- [Notifications](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/engine/notifications.py): `src/ghdcbot/engine/notifications.py`

### Platform adapters

- [Activity readers](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/adapters/github/rest.py): `src/ghdcbot/adapters/github/rest.py`
- [GitHub writes](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/adapters/github/writer.py): `src/ghdcbot/adapters/github/writer.py`
- [Discord API](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/adapters/discord/api.py): `src/ghdcbot/adapters/discord/api.py`
- [Discord writes](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/adapters/discord/writer.py): `src/ghdcbot/adapters/discord/writer.py`

### Discord features

- [Identity linking](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/engine/identity_linking.py): `src/ghdcbot/engine/identity_linking.py`
- [Contributor profiles](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/engine/social_profiles.py): `src/ghdcbot/engine/social_profiles.py`
- [Social commands](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/adapters/discord/social_commands.py): `src/ghdcbot/adapters/discord/social_commands.py`
- [Metrics](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/engine/metrics.py): `src/ghdcbot/engine/metrics.py`

### Configuration and state

- [Config loading](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/config/loader.py): `src/ghdcbot/config/loader.py`
- [Config models](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/config/models.py): `src/ghdcbot/config/models.py`
- [SQLite state](https://github.com/nawaz-builds/gitcord-githubdiscordbot/blob/main/src/ghdcbot/adapters/storage/sqlite.py): `src/ghdcbot/adapters/storage/sqlite.py`

### Other components

- **Operator**
- **GitHub**
- **Discord users**

## Connections

- Operator → CLI: runs
- Operator → Discord bot: uses commands
- CLI → Config loading: loads (evidence: `src/ghdcbot/cli.py`)
- Config loading → Config models: validates (evidence: `src/ghdcbot/config/loader.py`)
- CLI → Sync orchestration: runs sync (evidence: `src/ghdcbot/cli.py`)
- Sync orchestration → Activity readers: ingests activity
- GitHub → Activity readers: provides activity
- Sync orchestration → Deterministic planning: plans changes (evidence: `src/ghdcbot/engine/orchestrator.py`)
- Deterministic planning → Assignment strategy: uses strategy
- Sync orchestration → Audit reports: exports audit (evidence: `src/ghdcbot/cli.py`)
- Sync orchestration → Sync reporting: generates reports (evidence: `src/ghdcbot/engine/orchestrator.py`)
- Sync orchestration → Sync snapshots: records snapshots (evidence: `src/ghdcbot/engine/orchestrator.py`)
- Sync orchestration → GitHub writes: optionally applies
- Sync orchestration → Discord writes: optionally applies
- GitHub writes → GitHub: mutates
- Discord writes → Discord users: mutates
- Discord bot → Discord API: serves commands
- Discord bot → Identity linking: handles linking (evidence: `src/ghdcbot/bot.py`)
- Discord bot → Social commands: registers commands (evidence: `src/ghdcbot/bot.py`)
- Social commands → Contributor profiles: uses profiles (evidence: `src/ghdcbot/adapters/discord/social_commands.py`)
- Discord bot → Metrics: offers metrics (evidence: `src/ghdcbot/bot.py`)
- Discord bot → Notifications: offers notifications
- Identity linking → SQLite state: persists links (evidence: `src/ghdcbot/engine/identity_linking.py`)
- Contributor profiles → SQLite state: reads and writes (evidence: `src/ghdcbot/engine/social_profiles.py`)
- Sync orchestration → SQLite state: uses state
