Ripping Out the GitHub API: A Local-First Architecture Decision

The incident

Personal portal v1 had a very “hacker” design: at build time it requested the GitHub API and synced the user’s repositories and star counts straight into the page. Data always fresh, zero manual maintenance.

Until one day api.github.com/users/min09577 started returning 404 — the account had been flagged by platform risk control. The builds kept running, the data source was gone, and the works list on the page fell back to sample data.

Retrospective: the three hidden assumptions

1. Assumed the account would always be reachable — wrong. Risk control, false positives, regional issues: any one of them can drop a 404 out of the sky.
2. Assumed the build machine’s network was reliable — fragile. A build artifact that depends on the success of a network request is engineering-unacceptable.
3. Assumed the data volume justified real-time sync — wrong. A works list changes once every few months; introducing a runtime dependency for it is a risk-reward mismatch.

The decision: localize the data

Tear out the data source. Repositories and stats moved into a locally maintained config.ts, and builds now make zero external requests. Three immediate wins:

• Determinism: what npm run build produces depends only on the repo, not on GitHub’s mood
• Speed: no network round-trip in the build — faster and steadier on CI
• Auditability: every number on the page can be traced to a line in the codebase

But leave a clean socket

Localizing doesn’t mean giving up automation forever. The original getGitHubData() signature is preserved exactly; when the account is restored, dropping the fetch logic back in won’t require touching a single component above it.

That’s the most important lesson of this retrospective: when you tear out a dependency, leave the interface in place. Data sources can be swapped; contracts shouldn’t be.

One test to apply

From now on, any idea of “call an external service at build time” goes through this sieve first:

Does this data change frequently enough to justify the failure risk it introduces?

Content that changes by the month — no. Put it in the codebase like an honest citizen, and let git manage its history for you.