# joe-huber/github-developer-toolkit architecture

> Architecture diagram of the GitHub repository joe-huber/github-developer-toolkit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joe-huber/github-developer-toolkit
- Repository: https://github.com/joe-huber/github-developer-toolkit

## Overview

ghdtk analyzes a GitHub developer profile into provenance-backed metrics, scores, findings, and recommendations, then exposes the report through CLI/report outputs or an interactive dashboard. The main workflow is profile search → API collection → immutable raw snapshots → analysis → scoring and recommendations → report → visualization. The README documents the overall pipeline; sampled route and UI code confirms dashboard request ownership. Individual analyzer and report-assembly wiring was not sampled, so those connections are shown only at the documented subsystem level.

Main entry points: [`src/ghdtk/dashboard/routes.py`](https://github.com/joe-huber/github-developer-toolkit/blob/main/src/ghdtk/dashboard/routes.py) (Report routes), [`src/ghdtk/report/assemble.py`](https://github.com/joe-huber/github-developer-toolkit/blob/main/src/ghdtk/report/assemble.py) (Report assembler), [`src/ghdtk/analyzers`](https://github.com/joe-huber/github-developer-toolkit/tree/main/src/ghdtk/analyzers) (Profile analyzers), [`src/ghdtk/api/client.py`](https://github.com/joe-huber/github-developer-toolkit/blob/main/src/ghdtk/api/client.py) (GitHub client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI<br/>[__init__.py]"]
  node_ui["Dashboard UI<br/>[App.tsx]"]
  node_report_hook["Report hook<br/>[useReport.ts]"]
  node_ui_client["UI API client<br/>[client.ts]"]
end

subgraph group_acquisition["Data collection"]
  node_api_client["GitHub client<br/>[client.py]"]
  node_collector["Profile collector<br/>[orchestrator.py]"]
  node_readme_collector["README collector<br/>[collectors.py]"]
end

subgraph group_analysis["Profile analysis"]
  node_analyzers["Profile analyzers"]
  node_scoring["Dimension scoring"]
  node_recommendations["Recommendations"]
end

subgraph group_delivery["Reports and dashboard"]
  node_webapp["Dashboard app<br/>[app.py]"]
  node_routes["Report routes<br/>[routes.py]"]
  node_dashboard_views["Report visualizations<br/>[Dashboard.tsx]"]
  node_assembler["Report assembler<br/>[assemble.py]"]
  node_renderers["Report renderers"]
end

subgraph group_foundation["Models and configuration"]
  node_raw_models["Raw snapshots"]
  node_derived_models["Derived analysis"]
  node_settings["Settings<br/>[settings.py]"]
end

node_developer(("Developer"))
node_github["GitHub API"]

node_developer -->|"searches profile"| node_ui
node_developer -->|"analyzes profile"| node_cli
node_ui -->|"requests report"| node_report_hook
node_report_hook -->|"fetches report"| node_ui_client
node_ui_client -->|"HTTP request"| node_routes
node_webapp -->|"mounts routes"| node_routes
node_routes -->|"loads settings"| node_settings
node_routes -->|"creates client"| node_api_client
node_routes -->|"collects profile"| node_collector
node_routes -->|"collects README"| node_readme_collector
node_collector -->|"requests GitHub data"| node_api_client
node_readme_collector -->|"requests README"| node_api_client
node_api_client -->|"reads API"| node_github
node_collector -->|"builds snapshots"| node_raw_models
node_readme_collector -->|"builds README data"| node_raw_models
node_raw_models -->|"analyzes snapshots"| node_analyzers
node_analyzers -->|"produces metrics and findings"| node_derived_models
node_derived_models -->|"scores metrics"| node_scoring
node_analyzers -->|"supplies findings"| node_recommendations
node_scoring -->|"supplies scores"| node_recommendations
node_analyzers -->|"provides analysis"| node_assembler
node_scoring -->|"provides scores"| node_assembler
node_recommendations -->|"provides actions"| node_assembler
node_assembler -->|"returns report"| node_routes
node_assembler -->|"formats report"| node_renderers
node_routes -->|"returns report data"| node_dashboard_views
node_ui -->|"renders report"| node_dashboard_views

click node_cli "https://github.com/joe-huber/github-developer-toolkit/blob/main/src/ghdtk/cli/__init__.py"
click node_webapp "https://github.com/joe-huber/github-developer-toolkit/blob/main/src/ghdtk/dashboard/app.py"
click node_ui "https://github.com/joe-huber/github-developer-toolkit/blob/main/dashboard-ui/src/App.tsx"
click node_report_hook "https://github.com/joe-huber/github-developer-toolkit/blob/main/dashboard-ui/src/hooks/useReport.ts"
click node_ui_client "https://github.com/joe-huber/github-developer-toolkit/blob/main/dashboard-ui/src/api/client.ts"
click node_routes "https://github.com/joe-huber/github-developer-toolkit/blob/main/src/ghdtk/dashboard/routes.py"
click node_dashboard_views "https://github.com/joe-huber/github-developer-toolkit/blob/main/dashboard-ui/src/components/Dashboard.tsx"
click node_api_client "https://github.com/joe-huber/github-developer-toolkit/blob/main/src/ghdtk/api/client.py"
click node_collector "https://github.com/joe-huber/github-developer-toolkit/blob/main/src/ghdtk/collectors/orchestrator.py"
click node_readme_collector "https://github.com/joe-huber/github-developer-toolkit/blob/main/src/ghdtk/collectors/collectors.py"
click node_raw_models "https://github.com/joe-huber/github-developer-toolkit/tree/main/src/ghdtk/models/raw"
click node_analyzers "https://github.com/joe-huber/github-developer-toolkit/tree/main/src/ghdtk/analyzers"
click node_derived_models "https://github.com/joe-huber/github-developer-toolkit/tree/main/src/ghdtk/models/derived"
click node_scoring "https://github.com/joe-huber/github-developer-toolkit/tree/main/src/ghdtk/scoring"
click node_recommendations "https://github.com/joe-huber/github-developer-toolkit/tree/main/src/ghdtk/recommendations"
click node_assembler "https://github.com/joe-huber/github-developer-toolkit/blob/main/src/ghdtk/report/assemble.py"
click node_renderers "https://github.com/joe-huber/github-developer-toolkit/tree/main/src/ghdtk/report"
click node_settings "https://github.com/joe-huber/github-developer-toolkit/blob/main/src/ghdtk/config/settings.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_ui,node_report_hook,node_ui_client toneBlue
class node_api_client,node_collector,node_readme_collector toneAmber
class node_analyzers,node_scoring,node_recommendations,node_github toneMint
class node_webapp,node_routes,node_dashboard_views,node_assembler,node_renderers toneRose
class node_raw_models,node_derived_models,node_settings,node_developer toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/joe-huber/github-developer-toolkit/blob/main/src/ghdtk/cli/__init__.py): `src/ghdtk/cli/__init__.py`
- [Dashboard UI](https://github.com/joe-huber/github-developer-toolkit/blob/main/dashboard-ui/src/App.tsx): `dashboard-ui/src/App.tsx`
- [Report hook](https://github.com/joe-huber/github-developer-toolkit/blob/main/dashboard-ui/src/hooks/useReport.ts): `dashboard-ui/src/hooks/useReport.ts`
- [UI API client](https://github.com/joe-huber/github-developer-toolkit/blob/main/dashboard-ui/src/api/client.ts): `dashboard-ui/src/api/client.ts`

### Data collection

- [GitHub client](https://github.com/joe-huber/github-developer-toolkit/blob/main/src/ghdtk/api/client.py): `src/ghdtk/api/client.py`
- [Profile collector](https://github.com/joe-huber/github-developer-toolkit/blob/main/src/ghdtk/collectors/orchestrator.py): `src/ghdtk/collectors/orchestrator.py`
- [README collector](https://github.com/joe-huber/github-developer-toolkit/blob/main/src/ghdtk/collectors/collectors.py): `src/ghdtk/collectors/collectors.py`

### Profile analysis

- [Profile analyzers](https://github.com/joe-huber/github-developer-toolkit/tree/main/src/ghdtk/analyzers): `src/ghdtk/analyzers`
- [Dimension scoring](https://github.com/joe-huber/github-developer-toolkit/tree/main/src/ghdtk/scoring): `src/ghdtk/scoring`
- [Recommendations](https://github.com/joe-huber/github-developer-toolkit/tree/main/src/ghdtk/recommendations): `src/ghdtk/recommendations`

### Reports and dashboard

- [Dashboard app](https://github.com/joe-huber/github-developer-toolkit/blob/main/src/ghdtk/dashboard/app.py): `src/ghdtk/dashboard/app.py`
- [Report routes](https://github.com/joe-huber/github-developer-toolkit/blob/main/src/ghdtk/dashboard/routes.py): `src/ghdtk/dashboard/routes.py`
- [Report visualizations](https://github.com/joe-huber/github-developer-toolkit/blob/main/dashboard-ui/src/components/Dashboard.tsx): `dashboard-ui/src/components/Dashboard.tsx`
- [Report assembler](https://github.com/joe-huber/github-developer-toolkit/blob/main/src/ghdtk/report/assemble.py): `src/ghdtk/report/assemble.py`
- [Report renderers](https://github.com/joe-huber/github-developer-toolkit/tree/main/src/ghdtk/report): `src/ghdtk/report`

### Models and configuration

- [Raw snapshots](https://github.com/joe-huber/github-developer-toolkit/tree/main/src/ghdtk/models/raw): `src/ghdtk/models/raw`
- [Derived analysis](https://github.com/joe-huber/github-developer-toolkit/tree/main/src/ghdtk/models/derived): `src/ghdtk/models/derived`
- [Settings](https://github.com/joe-huber/github-developer-toolkit/blob/main/src/ghdtk/config/settings.py): `src/ghdtk/config/settings.py`

### Other components

- **Developer**
- **GitHub API**

## Connections

- Developer → Dashboard UI: searches profile
- Developer → CLI: analyzes profile
- Dashboard UI → Report hook: requests report
- Report hook → UI API client: fetches report
- UI API client → Report routes: HTTP request
- Dashboard app → Report routes: mounts routes
- Report routes → Settings: loads settings
- Report routes → GitHub client: creates client
- Report routes → Profile collector: collects profile
- Report routes → README collector: collects README
- Profile collector → GitHub client: requests GitHub data
- README collector → GitHub client: requests README
- GitHub client → GitHub API: reads API
- Profile collector → Raw snapshots: builds snapshots
- README collector → Raw snapshots: builds README data
- Raw snapshots → Profile analyzers: analyzes snapshots
- Profile analyzers → Derived analysis: produces metrics and findings
- Derived analysis → Dimension scoring: scores metrics
- Profile analyzers → Recommendations: supplies findings
- Dimension scoring → Recommendations: supplies scores
- Profile analyzers → Report assembler: provides analysis
- Dimension scoring → Report assembler: provides scores
- Recommendations → Report assembler: provides actions
- Report assembler → Report routes: returns report
- Report assembler → Report renderers: formats report
- Report routes → Report visualizations: returns report data
- Dashboard UI → Report visualizations: renders report