# sun-flat-yamada/github-copilot-dashboard architecture

> Architecture diagram of the GitHub repository sun-flat-yamada/github-copilot-dashboard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sun-flat-yamada/github-copilot-dashboard
- Repository: https://github.com/sun-flat-yamada/github-copilot-dashboard

## Overview

This is a GitHub Copilot usage and cost analytics platform. Its principal workflow collects GitHub metrics, seat and cost-center data, enriches and aggregates them into date-scoped outputs, persists those outputs on an isolated data branch, then loads and filters them in a browser dashboard. Distinct product stages include CSV report import, billing reconciliation and month-close, data-quality and seat audits, and dashboard analysis such as budgets, trends, adoption, and idle-seat savings. The graph reflects README-documented capabilities where implementation files were not sampled; those links are cited to the README.

Main entry points: [`src/application/pipeline/PipelineOrchestrator.ts`](https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/application/pipeline/PipelineOrchestrator.ts) (Pipeline Orchestrator), [`dashboard/src/App.tsx`](https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/dashboard/src/App.tsx) (Dashboard App), [`dashboard/src/hooks/useDashboardData.ts`](https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/dashboard/src/hooks/useDashboardData.ts) (Dashboard Data Hook), [`src/storage/fork-safe-storage.ts`](https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/storage/fork-safe-storage.ts) (Fork-Safe Data Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Collection &amp; Enrichment"]
  node_api_adapter["GitHub API Adapter"]
  node_raw_fetch["Raw API Fetcher<br/>[RawApiFetcher.ts]"]
  node_attribute_resolution["Attribute Resolution"]
end

subgraph group_processing["Analytics &amp; Finance"]
  node_orchestration["Pipeline Orchestrator"]
  node_aggregation["Metrics Aggregation"]
  node_report_import["Report Import<br/>[report-parser.ts]"]
  node_finance_audits["Finance &amp; Audits"]
  node_report_generation["Report Generation<br/>[report-engine.ts]"]
end

subgraph group_persistence["Data Persistence"]
  node_storage_writer["Storage Writer"]
  node_fork_storage[("Fork-Safe Data Store")]
end

subgraph group_dashboard["Dashboard &amp; Analysis"]
  node_dashboard_app["Dashboard App<br/>[App.tsx]"]
  node_data_hook["Dashboard Data Hook"]
  node_dataset_loader["Dataset Loader<br/>[datasetLoader.ts]"]
  node_query_entry["Query Entry<br/>[queryEngine.ts]"]
  node_filter_engine["Filter Engine<br/>[filterEngine.ts]"]
  node_analysis_views["Analysis Views"]
end

subgraph group_domain["Domain Contracts"]
  node_domain_data["Usage Data Contracts<br/>[copilot.ts]"]
  node_pricing["Pricing Catalog<br/>[pricing-catalog.ts]"]
  node_metric_registry["Metric Registry<br/>[metric-registry.ts]"]
end

node_github{{"GitHub Copilot API"}}
node_actions(("Scheduled Collection"))
node_mapping[("Mapping Secrets")]
node_operator(("Dashboard User"))

node_github -->|"supplies API data"| node_actions
node_mapping -->|"injects mapping"| node_actions
node_actions -.->|"starts collection"| node_api_adapter
node_api_adapter -->|"fetches through"| node_raw_fetch
node_orchestration -->|"resolves attributes"| node_attribute_resolution
node_orchestration -->|"aggregates metrics"| node_aggregation
node_orchestration -->|"parses reports"| node_report_import
node_orchestration -->|"runs stages"| node_finance_audits
node_orchestration -->|"persists results"| node_storage_writer
node_report_generation -->|"qualifies metrics"| node_metric_registry
node_storage_writer -->|"delegates storage"| node_fork_storage
node_actions -->|"writes data branch"| node_fork_storage
node_fork_storage -->|"supplies dashboard data"| node_dashboard_app
node_operator -->|"uses dashboard"| node_dashboard_app
node_dashboard_app -->|"loads dashboard data"| node_data_hook
node_data_hook -->|"loads datasets"| node_dataset_loader
node_data_hook -->|"queries datasets"| node_query_entry
node_query_entry -->|"delegates filtering"| node_filter_engine
node_dashboard_app -->|"hosts analysis views"| node_analysis_views
node_orchestration -->|"processes usage data"| node_domain_data
node_report_generation -.->|"uses pricing rules"| node_pricing
node_operator -->|"reviews audits"| node_finance_audits
node_operator -->|"explores analytics"| node_analysis_views

click node_api_adapter "https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/adapters/github-api/GitHubApiCopilotDataSource.ts"
click node_raw_fetch "https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/adapters/github-api/RawApiFetcher.ts"
click node_attribute_resolution "https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/collector/attribute-resolver.ts"
click node_orchestration "https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/application/pipeline/PipelineOrchestrator.ts"
click node_aggregation "https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/processor/metrics-aggregator.ts"
click node_report_import "https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/processor/report-parser.ts"
click node_finance_audits "https://github.com/sun-flat-yamada/github-copilot-dashboard/tree/main/src/application/pipeline"
click node_report_generation "https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/processor/report-engine.ts"
click node_storage_writer "https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/adapters/storage/ForkSafeStorageWriter.ts"
click node_fork_storage "https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/storage/fork-safe-storage.ts"
click node_dashboard_app "https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/dashboard/src/App.tsx"
click node_data_hook "https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/dashboard/src/hooks/useDashboardData.ts"
click node_dataset_loader "https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/dashboard/src/dataset/datasetLoader.ts"
click node_query_entry "https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/dashboard/src/query/queryEngine.ts"
click node_filter_engine "https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/dashboard/src/query/filterEngine.ts"
click node_analysis_views "https://github.com/sun-flat-yamada/github-copilot-dashboard/tree/main/dashboard/src/views"
click node_domain_data "https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/domain/entities/copilot.ts"
click node_pricing "https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/domain/pricing/pricing-catalog.ts"
click node_metric_registry "https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/domain/metrics/metric-registry.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_api_adapter,node_raw_fetch,node_attribute_resolution,node_operator toneBlue
class node_orchestration,node_aggregation,node_report_import,node_finance_audits,node_report_generation,node_mapping toneAmber
class node_storage_writer,node_fork_storage,node_github toneMint
class node_dashboard_app,node_data_hook,node_dataset_loader,node_query_entry,node_filter_engine,node_analysis_views toneRose
class node_domain_data,node_pricing,node_metric_registry,node_actions toneIndigo
```

## Components

### Collection & Enrichment

- [GitHub API Adapter](https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/adapters/github-api/GitHubApiCopilotDataSource.ts): `src/adapters/github-api/GitHubApiCopilotDataSource.ts`
- [Raw API Fetcher](https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/adapters/github-api/RawApiFetcher.ts): `src/adapters/github-api/RawApiFetcher.ts`
- [Attribute Resolution](https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/collector/attribute-resolver.ts): `src/collector/attribute-resolver.ts`

### Analytics & Finance

- [Pipeline Orchestrator](https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/application/pipeline/PipelineOrchestrator.ts): `src/application/pipeline/PipelineOrchestrator.ts`
- [Metrics Aggregation](https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/processor/metrics-aggregator.ts): `src/processor/metrics-aggregator.ts`
- [Report Import](https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/processor/report-parser.ts): `src/processor/report-parser.ts`
- [Finance & Audits](https://github.com/sun-flat-yamada/github-copilot-dashboard/tree/main/src/application/pipeline): `src/application/pipeline`
- [Report Generation](https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/processor/report-engine.ts): `src/processor/report-engine.ts`

### Data Persistence

- [Storage Writer](https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/adapters/storage/ForkSafeStorageWriter.ts): `src/adapters/storage/ForkSafeStorageWriter.ts`
- [Fork-Safe Data Store](https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/storage/fork-safe-storage.ts): `src/storage/fork-safe-storage.ts`

### Dashboard & Analysis

- [Dashboard App](https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/dashboard/src/App.tsx): `dashboard/src/App.tsx`
- [Dashboard Data Hook](https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/dashboard/src/hooks/useDashboardData.ts): `dashboard/src/hooks/useDashboardData.ts`
- [Dataset Loader](https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/dashboard/src/dataset/datasetLoader.ts): `dashboard/src/dataset/datasetLoader.ts`
- [Query Entry](https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/dashboard/src/query/queryEngine.ts): `dashboard/src/query/queryEngine.ts`
- [Filter Engine](https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/dashboard/src/query/filterEngine.ts): `dashboard/src/query/filterEngine.ts`
- [Analysis Views](https://github.com/sun-flat-yamada/github-copilot-dashboard/tree/main/dashboard/src/views): `dashboard/src/views`

### Domain Contracts

- [Usage Data Contracts](https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/domain/entities/copilot.ts): `src/domain/entities/copilot.ts`
- [Pricing Catalog](https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/domain/pricing/pricing-catalog.ts): `src/domain/pricing/pricing-catalog.ts`
- [Metric Registry](https://github.com/sun-flat-yamada/github-copilot-dashboard/blob/main/src/domain/metrics/metric-registry.ts): `src/domain/metrics/metric-registry.ts`

### Other components

- **GitHub Copilot API**
- **Scheduled Collection**
- **Mapping Secrets**
- **Dashboard User**

## Connections

- GitHub Copilot API → Scheduled Collection: supplies API data (evidence: `README.md`)
- Mapping Secrets → Scheduled Collection: injects mapping (evidence: `README.md`)
- Scheduled Collection → GitHub API Adapter: starts collection
- GitHub API Adapter → Raw API Fetcher: fetches through
- Pipeline Orchestrator → Attribute Resolution: resolves attributes (evidence: `src/application/pipeline/PipelineOrchestrator.ts`)
- Pipeline Orchestrator → Metrics Aggregation: aggregates metrics (evidence: `src/application/pipeline/PipelineOrchestrator.ts`)
- Pipeline Orchestrator → Report Import: parses reports (evidence: `src/application/pipeline/PipelineOrchestrator.ts`)
- Pipeline Orchestrator → Finance & Audits: runs stages (evidence: `src/application/pipeline/PipelineOrchestrator.ts`)
- Pipeline Orchestrator → Storage Writer: persists results (evidence: `src/application/pipeline/PipelineOrchestrator.ts`)
- Report Generation → Metric Registry: qualifies metrics (evidence: `src/processor/report-engine.ts`)
- Storage Writer → Fork-Safe Data Store: delegates storage (evidence: `src/adapters/storage/ForkSafeStorageWriter.ts`)
- Scheduled Collection → Fork-Safe Data Store: writes data branch (evidence: `README.md`)
- Fork-Safe Data Store → Dashboard App: supplies dashboard data (evidence: `README.md`)
- Dashboard User → Dashboard App: uses dashboard (evidence: `README.md`)
- Dashboard App → Dashboard Data Hook: loads dashboard data (evidence: `dashboard/src/App.tsx`)
- Dashboard Data Hook → Dataset Loader: loads datasets (evidence: `dashboard/src/hooks/useDashboardData.ts`)
- Dashboard Data Hook → Query Entry: queries datasets (evidence: `dashboard/src/hooks/useDashboardData.ts`)
- Query Entry → Filter Engine: delegates filtering (evidence: `dashboard/src/query/queryEngine.ts`)
- Dashboard App → Analysis Views: hosts analysis views (evidence: `dashboard/src/App.tsx`)
- Pipeline Orchestrator → Usage Data Contracts: processes usage data (evidence: `src/application/pipeline/PipelineOrchestrator.ts`)
- Report Generation → Pricing Catalog: uses pricing rules
- Dashboard User → Finance & Audits: reviews audits (evidence: `README.md`)
- Dashboard User → Analysis Views: explores analytics (evidence: `README.md`)
