Decisions

ADR-001: Target public OSS repos first

Status: Accepted

Decision

V1 targets public open-source repositories and organizations first.

Why

• GitHub Pages is naturally public.
• Public repos avoid auth and visibility complexity.
• The OSS visibility story is the clearest user value for an easy add-on.

Consequence

Private-repo analytics are explicitly deferred until the public-pack pattern is proven.

---

ADR-002: Use a hybrid GitHub data model

Status: Accepted

Decision

Use GraphQL for contributor-centric contribution history and REST for repo traffic and selected repo-level endpoints.

Why

• ContributionsCollection is the best source for contributor detail.
• REST traffic endpoints expose views, clones, referrers, and paths.
• Neither API alone covers the needed surface well.

Consequence

The extraction pipeline must normalize data from multiple API families into one static-friendly contract.

---

ADR-003: Contributor detail is the canonical drill-through surface

Status: Accepted

Decision

Every dashboard that names a contributor should link to a shared contributor detail board keyed by:

• contributor=<github_login>

Why

• This creates a coherent small-site topology.
• It is the highest-value missing capability versus GitHub's native repo views.
• It avoids building separate custom detail pages per dashboard.

Consequence

The metric contract and link model must keep contributor identity stable and explicit.

---

ADR-004: Preserve history in git, not an external store

Status: Accepted

Decision

Use a machine-managed history branch or equivalent git-backed snapshot store for durable metrics such as traffic history.

Why

• GitHub traffic APIs only expose the last 14 days.
• A git-backed store keeps the architecture fully GitHub-native.
• It avoids adding hosted infra for a static site product.

Consequence

The workflow must support reading previous snapshots and writing new ones on schedule.

---

ADR-005: Start with a starter pack plus workflow, not a hosted service

Status: Accepted

Decision

V1 ships as a starter dashboard pack + workflow/config pattern, not as a Dataface-hosted analytics service.

Why

• Easier adoption for OSS maintainers
• Lower operational burden
• Better fit for dashboard-factory and M4

Consequence

The initiative must prioritize docs, packaging, and repeatability over platform complexity.