Context
The portfolio presents claims backed by evidence from several repositories. The Next.js site, the Go API, the HTML résumé and the PDF all need the same data. If each one reads the sources on its own, they can disagree, and a claim could be shown differently in different places, or shown in one place after it was withdrawn in another.
Options
- Each consumer reads the sources itself. Simple at first, but validation gets duplicated and the consumers drift apart.
- A database populated by a sync job. Gives runtime queries, but adds state, backups and a failure mode that a read-only site does not need.
- One immutable snapshot built and audited at build time. Deterministic and reviewable. Changing it requires a rebuild.
Decision
scripts/evidence.ts build loads every input, validates it against the JSON Schemas in /schemas, and
runs the cross-reference audit. Only if the audit is clean does it write data/snapshot/snapshot.json,
identified by the SHA-256 of its canonical content. Next.js imports that file at build time. The Go API
image ships the same file and refuses to start unless the file matches its .sha256 sidecar.
Consequences
- The website, résumé and API cannot disagree within a release: they ship the same
snapshot_id. - An invalid claim fails CI instead of reaching production.
- Every content change needs a build and deploy. For a portfolio that is a feature: each change gets reviewed.