03 / The Build Log / Portfolio Platform
HelsaGrace Portfolio
A Next.js portfolio with two records, a typed case study system and Markdown-authoritative documentation.
A Next.js 15 and React 19 portfolio built around two records: a registry-driven case study system with a shared block renderer, an optional Supabase admin, and project documentation generated from Markdown into typed entries.
- Role
- Frontend Development · Product Design
- Category
- Portfolio Platform
- Status
- Live
- Year
- 2026

[build: helsagrace-portfolio-build-log] — Live
01 / The brief
Build a portfolio that can grow without a redesign.
The portfolio needed to publish two kinds of evidence, keep them visually distinct, and add new projects without a bespoke page for each one. It also had to stay fast and readable without a backend connection.
The result is a Next.js App Router site with a typed case study registry, a shared block renderer, a welcome cover, two record hubs, archives and a combined overview.
The public site reads from a local content snapshot. Supabase powers the owner admin. Markdown is the authoritative source for the project documentation added in November 2026.
- Static public pages with optional Supabase admin
- Typed case study model shared by both records
- Registry-driven hubs, counts, next links and sitemap
- Markdown-to-TypeScript documentation sync
02 / System map
Local content for reading, Supabase for editing.
App Router
Welcome · records · overview
Content registry
Typed studies · block model
Study renderer
Shared shell · contents rail
Supabase admin
Owner allowlist · revisions
Vercel
Static output · metadata · sitemap
The public site does not require the admin backend to render. That separation is deliberate.
03 / The content model
One registry, two records.
`lib/case-studies.ts` defines the study type and two registries: build studies derived from featured projects, and design studies as a literal array. `allCaseStudies` concatenates both.
Helper functions expose studies by record, featured status, slug and next-study order. The hubs, archives, counts, study routes and sitemap all read from the same arrays.
The block model supports narrative, steps, quote, metrics, gallery, architecture, reflection, next and system. The renderer filters metrics out of displayed studies, so new studies do not rely on them for essential information.
04 / The documentation pipeline
Markdown stays authoritative.
The four new entries are generated, not hand-copied. The pipeline prevents the site and the documents from drifting silently.
- 01
Write PORTFOLIO_CONTENT.md
Each project gets one Casebook and one Build Log entry in a fenced JSON block, alongside editorial notes and a screenshot inventory.
- 02
Validate the block
The sync script checks for exactly two entries per project, one per record, and four unique slugs overall.
- 03
Generate the registry
`lib/documented-projects.ts` is written with typed CaseStudy objects and appended to the existing registries.
- 04
Check for drift
The `--check` mode fails if the generated file no longer matches the Markdown source.
05 / The study shell
One renderer, two temperatures.
`case-study-view.tsx` renders the back link, status pill, metadata, cover, contents rail, blocks and next-study link. The record determines the surrounding surface; the blocks determine the content.
The Casebook uses the off-white `--path-*` tokens. The Build Log overrides those tokens with a dark graphite palette. Components do not branch on theme.
A study can define its own accent inside the content, so a fintech case can carry its green without changing the portfolio shell.
06 / Selected screens
The public surface, at two widths.




07 / The hard parts
The hard parts are the seams between systems.
The admin is behind a server-side guard: unauthenticated users are redirected, authenticated non-owners see an unauthorized notice, and missing Supabase configuration shows a setup notice instead of a broken page.
Middleware handles both session refresh and subdomain rewrites for the private products. API routes skip host rewriting but still refresh cookies.
The documentation pipeline is the newest seam. It has to preserve existing studies, generate valid typed data and fail loudly when the Markdown and the registry diverge.
The remaining risk is drift in the older documentation. `CONCEPT.md` still describes routes and a typeface that the current layout no longer uses; the code is authoritative and the discrepancy is recorded.
08 / Reflection
Static reliability is a design decision.
The most important engineering choice was to keep the public portfolio readable without a backend. The site is an argument; it should not disappear because a database is unavailable.
The second was the block model. It makes new work additive and keeps the reading experience consistent, at the cost of some flexibility for unusual projects.
The third was the documentation sync. Writing the same content twice would eventually produce two different truths. Generating the entries makes the Markdown the source and the site the output.
The part I would improve next is verification breadth: the admin, contact delivery and accessibility have not been exercised to the same standard as the public pages.
Static public
No backend required to read the portfolio.
Registry-driven
Routes, counts and sitemap derive from one source.
Shared renderer
Two records, one block system.
Generated entries
Markdown stays authoritative; drift fails the check.
09 / What is next
Verify the parts that have not been exercised.
The next engineering milestone is validation: type check, tests, lint, production build and integrated browser capture for all four new studies and both hubs.
After that, the gaps are admin end-to-end coverage, contact delivery, registry tests, archive filtering and an accessibility audit focused on motion and the custom cursor.
The documentation will be updated with the real validation results, including any failure rather than only the pass.
- Run the full validation table and record real results
- Append the four generated studies without altering existing entries
- Verify all four study pages, both hubs and both archives
- Add registry and sitemap tests
- Update CONCEPT.md and the README to match the current code
Built with
Next in The Build Log
CareerCraft
A full-stack career platform with application tracking, a CV builder, AI cover letters, job discovery, analytics and subscription billing — designed and built solo.