# charpeni/bilan architecture

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

- Interactive diagram: https://gitdiagram.com/charpeni/bilan
- Repository: https://github.com/charpeni/bilan

## Overview

bilan turns GitHub pull-request metadata into contributor, area, review-flow, latency, and workload analytics. The CLI syncs repository history into a local cache and exports a standalone HTML report; the web app authenticates viewers, admits sync jobs, stores shared snapshots, and serves dashboards. The graph preserves those two result paths and the documented web access, example, and retention capabilities. Some web routes and storage implementations were not excerpted, so their internal call links are omitted where evidence is unavailable.

Main entry points: [`packages/cli/src/cli.ts`](https://github.com/charpeni/bilan/blob/main/packages/cli/src/cli.ts) (CLI workflow), [`packages/core/src/github/client.ts`](https://github.com/charpeni/bilan/blob/main/packages/core/src/github/client.ts) (GitHub client), [`packages/ui/src/render.ts`](https://github.com/charpeni/bilan/blob/main/packages/ui/src/render.ts) (Dashboard renderer), [`packages/core/src/sync/engine.ts`](https://github.com/charpeni/bilan/blob/main/packages/core/src/sync/engine.ts) (Sync engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["GitHub ingestion"]
  node_sync_engine["Sync engine<br/>[engine.ts]"]
  node_github_client["GitHub client<br/>[client.ts]"]
  node_query_definitions["PR queries<br/>[query.ts]"]
  node_compact_prs["PR compaction<br/>[compact.ts]"]
  node_payload_builder["Payload builder<br/>[payload.ts]"]
end

subgraph group_analytics["Analytics"]
  node_metrics["Metric derivation<br/>[derive.ts]"]
  node_metric_scope["Filtering and windows<br/>[scope.ts]"]
  node_people_metrics["People and reviews<br/>[people.ts]"]
  node_brief_metrics["Summary brief<br/>[brief.ts]"]
end

subgraph group_cli["CLI reporting"]
  node_cli_app["CLI workflow<br/>[cli.ts]"]
  node_report_output["HTML report export<br/>[output.ts]"]
end

subgraph group_web["Web product"]
  node_web_workflow["Sync workflow<br/>[sync-repo.ts]"]
  node_web_api["Web API routes<br/>[sync.ts]"]
  node_auth["OAuth and sessions<br/>[oauth.ts]"]
  node_access["Viewer access<br/>[access.ts]"]
  node_dashboard_ui["Dashboard renderer<br/>[render.ts]"]
  node_charts["Charts and visuals<br/>[charts.ts]"]
  node_examples["Static examples<br/>[examples.ts]"]
  node_retention["Data retention<br/>[retention.ts]"]
  node_worker["Cloudflare worker<br/>[worker.ts]"]
end

subgraph group_persistence["Persistence"]
  node_sync_store["Sync store contract<br/>[store.ts]"]
  node_file_cache[("Local cache<br/>[index.ts]")]
  node_d1_store[("D1 repository store<br/>[store.ts]")]
  node_d1_schema["D1 schema<br/>[schema.ts]"]
  node_payload_store[("Shared payloads<br/>[sync-repo.ts]")]
end

node_cli_user(("CLI user"))
node_web_user(("Dashboard viewer"))
node_github{{"GitHub API"}}
node_github_login{{"GitHub login"}}

node_cli_user -->|"runs"| node_cli_app
node_cli_app -->|"creates"| node_github_client
node_github_client -->|"executes"| node_query_definitions
node_github_client -->|"requests metadata"| node_github
node_cli_app -->|"starts sync"| node_sync_engine
node_sync_engine -->|"fetches PRs"| node_github_client
node_sync_engine -->|"compacts results"| node_compact_prs
node_sync_engine -->|"persists checkpoints"| node_sync_store
node_cli_app -->|"loads cache"| node_file_cache
node_cli_app -->|"builds payload"| node_payload_builder
node_payload_builder -->|"derives fields"| node_metrics
node_cli_app -->|"writes report"| node_report_output
node_report_output -.->|"embeds dashboard"| node_dashboard_ui
node_metrics -->|"feeds windows"| node_metric_scope
node_metric_scope -->|"scopes people"| node_people_metrics
node_metric_scope -->|"scopes summary"| node_brief_metrics
node_dashboard_ui -->|"renders charts"| node_charts
node_dashboard_ui -->|"computes views"| node_metrics
node_web_user -.->|"signs in"| node_auth
node_auth -->|"authorizes"| node_github_login
node_web_user -.->|"requests sync"| node_web_api
node_web_api -.->|"admits job"| node_web_workflow
node_web_workflow -->|"syncs repository"| node_github_client
node_web_workflow -->|"stores metadata"| node_d1_store
node_d1_store -->|"uses schema"| node_d1_schema
node_web_workflow -->|"publishes snapshots"| node_payload_store
node_web_user -.->|"checks permission"| node_access
node_web_user -.->|"views dashboard"| node_dashboard_ui
node_examples -.->|"provides snapshots"| node_dashboard_ui
node_worker -->|"runs nightly"| node_retention

click node_sync_engine "https://github.com/charpeni/bilan/blob/main/packages/core/src/sync/engine.ts"
click node_github_client "https://github.com/charpeni/bilan/blob/main/packages/core/src/github/client.ts"
click node_query_definitions "https://github.com/charpeni/bilan/blob/main/packages/core/src/github/query.ts"
click node_compact_prs "https://github.com/charpeni/bilan/blob/main/packages/core/src/github/compact.ts"
click node_payload_builder "https://github.com/charpeni/bilan/blob/main/packages/core/src/derive/payload.ts"
click node_sync_store "https://github.com/charpeni/bilan/blob/main/packages/core/src/sync/store.ts"
click node_file_cache "https://github.com/charpeni/bilan/blob/main/packages/store-file/src/index.ts"
click node_d1_store "https://github.com/charpeni/bilan/blob/main/packages/store-d1/src/store.ts"
click node_d1_schema "https://github.com/charpeni/bilan/blob/main/packages/store-d1/src/schema.ts"
click node_payload_store "https://github.com/charpeni/bilan/blob/main/packages/web/src/workflows/sync-repo.ts"
click node_cli_app "https://github.com/charpeni/bilan/blob/main/packages/cli/src/cli.ts"
click node_report_output "https://github.com/charpeni/bilan/blob/main/packages/cli/src/output.ts"
click node_metrics "https://github.com/charpeni/bilan/blob/main/packages/core/src/metrics/derive.ts"
click node_metric_scope "https://github.com/charpeni/bilan/blob/main/packages/core/src/metrics/scope.ts"
click node_people_metrics "https://github.com/charpeni/bilan/blob/main/packages/core/src/metrics/people.ts"
click node_brief_metrics "https://github.com/charpeni/bilan/blob/main/packages/core/src/metrics/brief.ts"
click node_web_workflow "https://github.com/charpeni/bilan/blob/main/packages/web/src/workflows/sync-repo.ts"
click node_web_api "https://github.com/charpeni/bilan/blob/main/packages/web/src/pages/api/repos/%5Bowner%5D/%5Bname%5D/sync.ts"
click node_auth "https://github.com/charpeni/bilan/blob/main/packages/web/src/lib/oauth.ts"
click node_access "https://github.com/charpeni/bilan/blob/main/packages/web/src/lib/access.ts"
click node_dashboard_ui "https://github.com/charpeni/bilan/blob/main/packages/ui/src/render.ts"
click node_charts "https://github.com/charpeni/bilan/blob/main/packages/ui/src/charts.ts"
click node_examples "https://github.com/charpeni/bilan/blob/main/packages/web/src/lib/examples.ts"
click node_retention "https://github.com/charpeni/bilan/blob/main/packages/web/src/lib/retention.ts"
click node_worker "https://github.com/charpeni/bilan/blob/main/packages/web/src/worker.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_sync_engine,node_github_client,node_query_definitions,node_compact_prs,node_payload_builder,node_cli_user,node_web_user toneBlue
class node_metrics,node_metric_scope,node_people_metrics,node_brief_metrics toneAmber
class node_cli_app,node_report_output,node_github toneMint
class node_web_workflow,node_web_api,node_auth,node_access,node_dashboard_ui,node_charts,node_examples,node_retention,node_worker toneRose
class node_sync_store,node_file_cache,node_d1_store,node_d1_schema,node_payload_store,node_github_login toneIndigo
```

## Components

### GitHub ingestion

- [Sync engine](https://github.com/charpeni/bilan/blob/main/packages/core/src/sync/engine.ts): `packages/core/src/sync/engine.ts`
- [GitHub client](https://github.com/charpeni/bilan/blob/main/packages/core/src/github/client.ts): `packages/core/src/github/client.ts`
- [PR queries](https://github.com/charpeni/bilan/blob/main/packages/core/src/github/query.ts): `packages/core/src/github/query.ts`
- [PR compaction](https://github.com/charpeni/bilan/blob/main/packages/core/src/github/compact.ts): `packages/core/src/github/compact.ts`
- [Payload builder](https://github.com/charpeni/bilan/blob/main/packages/core/src/derive/payload.ts): `packages/core/src/derive/payload.ts`

### Analytics

- [Metric derivation](https://github.com/charpeni/bilan/blob/main/packages/core/src/metrics/derive.ts): `packages/core/src/metrics/derive.ts`
- [Filtering and windows](https://github.com/charpeni/bilan/blob/main/packages/core/src/metrics/scope.ts): `packages/core/src/metrics/scope.ts`
- [People and reviews](https://github.com/charpeni/bilan/blob/main/packages/core/src/metrics/people.ts): `packages/core/src/metrics/people.ts`
- [Summary brief](https://github.com/charpeni/bilan/blob/main/packages/core/src/metrics/brief.ts): `packages/core/src/metrics/brief.ts`

### CLI reporting

- [CLI workflow](https://github.com/charpeni/bilan/blob/main/packages/cli/src/cli.ts): `packages/cli/src/cli.ts`
- [HTML report export](https://github.com/charpeni/bilan/blob/main/packages/cli/src/output.ts): `packages/cli/src/output.ts`

### Web product

- [Sync workflow](https://github.com/charpeni/bilan/blob/main/packages/web/src/workflows/sync-repo.ts): `packages/web/src/workflows/sync-repo.ts`
- [Web API routes](https://github.com/charpeni/bilan/blob/main/packages/web/src/pages/api/repos/%5Bowner%5D/%5Bname%5D/sync.ts): `packages/web/src/pages/api/repos/[owner]/[name]/sync.ts`
- [OAuth and sessions](https://github.com/charpeni/bilan/blob/main/packages/web/src/lib/oauth.ts): `packages/web/src/lib/oauth.ts`
- [Viewer access](https://github.com/charpeni/bilan/blob/main/packages/web/src/lib/access.ts): `packages/web/src/lib/access.ts`
- [Dashboard renderer](https://github.com/charpeni/bilan/blob/main/packages/ui/src/render.ts): `packages/ui/src/render.ts`
- [Charts and visuals](https://github.com/charpeni/bilan/blob/main/packages/ui/src/charts.ts): `packages/ui/src/charts.ts`
- [Static examples](https://github.com/charpeni/bilan/blob/main/packages/web/src/lib/examples.ts): `packages/web/src/lib/examples.ts`
- [Data retention](https://github.com/charpeni/bilan/blob/main/packages/web/src/lib/retention.ts): `packages/web/src/lib/retention.ts`
- [Cloudflare worker](https://github.com/charpeni/bilan/blob/main/packages/web/src/worker.ts): `packages/web/src/worker.ts`

### Persistence

- [Sync store contract](https://github.com/charpeni/bilan/blob/main/packages/core/src/sync/store.ts): `packages/core/src/sync/store.ts`
- [Local cache](https://github.com/charpeni/bilan/blob/main/packages/store-file/src/index.ts): `packages/store-file/src/index.ts`
- [D1 repository store](https://github.com/charpeni/bilan/blob/main/packages/store-d1/src/store.ts): `packages/store-d1/src/store.ts`
- [D1 schema](https://github.com/charpeni/bilan/blob/main/packages/store-d1/src/schema.ts): `packages/store-d1/src/schema.ts`
- [Shared payloads](https://github.com/charpeni/bilan/blob/main/packages/web/src/workflows/sync-repo.ts): `packages/web/src/workflows/sync-repo.ts`

### Other components

- **CLI user**
- **Dashboard viewer**
- **GitHub API**
- **GitHub login**

## Connections

- CLI user → CLI workflow: runs (evidence: `packages/cli/src/cli.ts`)
- CLI workflow → GitHub client: creates (evidence: `packages/cli/src/cli.ts`)
- GitHub client → PR queries: executes (evidence: `packages/core/src/github/client.ts`)
- GitHub client → GitHub API: requests metadata
- CLI workflow → Sync engine: starts sync (evidence: `packages/cli/src/cli.ts`)
- Sync engine → GitHub client: fetches PRs (evidence: `packages/core/src/sync/engine.ts`)
- Sync engine → PR compaction: compacts results (evidence: `packages/core/src/sync/engine.ts`)
- Sync engine → Sync store contract: persists checkpoints (evidence: `packages/core/src/sync/engine.ts`)
- CLI workflow → Local cache: loads cache (evidence: `packages/cli/src/cli.ts`)
- CLI workflow → Payload builder: builds payload (evidence: `packages/cli/src/cli.ts`)
- Payload builder → Metric derivation: derives fields (evidence: `packages/core/src/derive/payload.ts`)
- CLI workflow → HTML report export: writes report (evidence: `packages/cli/src/cli.ts`)
- HTML report export → Dashboard renderer: embeds dashboard
- Metric derivation → Filtering and windows: feeds windows (evidence: `packages/core/src/metrics/scope.ts`)
- Filtering and windows → People and reviews: scopes people (evidence: `packages/core/src/metrics/people.ts`)
- Filtering and windows → Summary brief: scopes summary (evidence: `packages/core/src/metrics/brief.ts`)
- Dashboard renderer → Charts and visuals: renders charts (evidence: `packages/ui/src/render.ts`)
- Dashboard renderer → Metric derivation: computes views (evidence: `packages/ui/src/render.ts`)
- Dashboard viewer → OAuth and sessions: signs in
- OAuth and sessions → GitHub login: authorizes (evidence: `README.md`)
- Dashboard viewer → Web API routes: requests sync
- Web API routes → Sync workflow: admits job
- Sync workflow → GitHub client: syncs repository (evidence: `packages/web/src/workflows/sync-repo.ts`)
- Sync workflow → D1 repository store: stores metadata (evidence: `packages/web/src/workflows/sync-repo.ts`)
- D1 repository store → D1 schema: uses schema
- Sync workflow → Shared payloads: publishes snapshots (evidence: `packages/web/src/workflows/sync-repo.ts`)
- Dashboard viewer → Viewer access: checks permission
- Dashboard viewer → Dashboard renderer: views dashboard (evidence: `README.md`)
- Static examples → Dashboard renderer: provides snapshots (evidence: `README.md`)
- Cloudflare worker → Data retention: runs nightly (evidence: `packages/web/src/worker.ts`)
