# HelsaGrace Portfolio — Project Build Log

**Document type:** Engineering build log  
**Project:** HelsaGrace Portfolio  
**Owner:** HelsaGrace Okporho  
**Documented:** 16 November 2026  
**Primary evidence:** source repository, build scripts, browser captures, local build and test runs  
**Companion document:** [PROJECT_CASEBOOK.md](./PROJECT_CASEBOOK.md)

> This log records how the portfolio is built, what was verified, and what remains incomplete. It does not repeat the design argument in the casebook.

---

## 1. Identity and scope

| Field | Detail |
|---|---|
| **Application** | HelsaGrace Portfolio |
| **Repository** | `C:\Users\HelsaGrace\Desktop\My Portfolio\helsagrace` |
| **Public address** | `https://helsagrace.site` |
| **Framework** | Next.js 15.5.27 App Router |
| **Runtime** | React 19.3, TypeScript 5.9 strict |
| **Styling** | Tailwind CSS 4.3 with CSS variables |
| **Backend** | Supabase (content, auth, RLS) and Resend (contact) |
| **Hosting** | Vercel / Orizon, per the README |
| **Records** | Casebook (product design), Build Log (frontend), Overview |
| **Content entries at documentation time** | 3 Casebook, 5 Build Log — before the new documentation entries |
| **Content entries after integration** | 5 Casebook, 7 Build Log |

The build log covers the public portfolio and the content/admin plumbing required to publish it. Private product surfaces (`/os`, `/devotional`, `/recovery`, `/vela`) are mentioned only where they affect shared infrastructure.

---

## 2. Stack and toolchain

### 2.1 Runtime dependencies

| Package | Version | Role |
|---|---|---|
| `next` | 15.5.27 | App Router, server components, static generation |
| `react` | 19.3.0 | UI runtime |
| `react-dom` | 19.3.0 | DOM renderer |
| `typescript` | 5.9.0 | Type checking (strict) |
| `tailwindcss` | 4.3.3 | Styling and tokens |
| `@tailwindcss/postcss` | 4.3.3 | Tailwind pipeline |
| `@supabase/ssr` | 0.12.7 | Server-side auth sessions |
| `@supabase/supabase-js` | 2.117.2 | Content, auth and storage client |
| `gsap` | 3.15.0 | Motion |
| `lenis` | 1.3.26 | Smooth scrolling |
| `lucide-react` | 1.52.0 | Icons |
| `date-fns` | 4.4.0 | Date formatting |
| `date-fns-tz` | 3.2.0 | Timezone handling |
| `web-push` | 3.6.7 | Push notifications for private products |

### 2.2 Quality dependencies

| Package | Version | Role |
|---|---|---|
| `vitest` | 5.1.0 | Test runner |
| `eslint` | 9.39.5 | Linting |
| `eslint-config-next` | 16.4.3 | Next.js lint rules |
| `tsx` | 4.23.15 | Script execution |
| `sharp` | 0.35.5 | Image processing for PWA icons |

### 2.3 Scripts

```json
{
  "dev": "next dev",
  "build": "next build",
  "start": "next start",
  "lint": "eslint .",
  "typecheck": "tsc --noEmit",
  "test": "vitest run",
  "test:watch": "vitest",
  "sql": "tsx scripts/sql.ts",
  "seed": "tsx scripts/seed.ts",
  "icons": "node scripts/pwa-icons.mjs"
}
```

### 2.4 Configuration behaviour

The public site works without Supabase or Resend configuration. The admin surfaces show a setup notice when Supabase is absent. The contact form requires Resend. This is a deliberate resilience choice: the portfolio's public argument should not depend on a backend being available.

Environment values are read on the server. None are reproduced in this document.

---

## 3. Repository map

```
helsagrace/
├── app/
│   ├── (welcome)/page.tsx          Welcome screen
│   ├── (records)/                  Casebook, Build Log, archives, study pages
│   ├── overview/                   Combined practice view
│   ├── work/[slug]/                Legacy project pages
│   ├── admin/                      Owner content administration
│   ├── api/                        Contact and other endpoints
│   ├── os/                         Private operating system
│   ├── devotional/                 Private devotional product
│   ├── recovery/                   Private recovery product
│   ├── vela/                       Private messaging product
│   ├── layout.tsx                  Fonts, metadata, global motion
│   ├── globals.css                 Tailwind v4 theme tokens
│   └── concept.css                 Record and study design system
├── components/
│   ├── concept/                    Record hubs, study renderer, images, navigation
│   ├── welcome/                    Welcome screen and destination cards
│   ├── admin/                      Editors, media library, messages, navigation
│   ├── motion/                     Cursor, magnetic, masked words, scroll progress
│   ├── sections/                   Legacy portfolio sections
│   └── work/                       Legacy project components
├── lib/
│   ├── case-studies.ts             Case study types and registry (1,743 lines)
│   ├── concept-content.ts          Snapshot parsing and path configuration
│   ├── content.ts                  Typed content model
│   ├── cms.ts                      Content merge and Supabase detection
│   ├── admin-data.ts               Admin read helpers
│   ├── documented-projects.ts      Generated from the Markdown sources
│   ├── supabase/                   Client, server and middleware helpers
│   └── time/                       Timezone utilities
├── content-snapshot.json           Public content fixture
├── middleware.ts                   Subdomain routing and session refresh
├── scripts/
│   ├── capture-project-evidence.mjs
│   └── sync-project-documentation.mjs
├── tests/                          Five Vitest files
└── public/
    ├── images/                     Screenshot and brand assets
    └── project-documentation/      Markdown casebooks, build logs and evidence
```

The repository contains both the public portfolio and several private products. The public case study system is deliberately isolated from those private surfaces.

---

## 4. Runtime architecture

### 4.1 App Router and route groups

- `app/(welcome)/page.tsx` is the entry cover.
- `app/(records)/layout.tsx` applies the concept stylesheet and the shared record shell.
- `app/(records)/casebook/page.tsx` and `build-log/page.tsx` render hubs.
- `app/(records)/casebook/[slug]/page.tsx` and `build-log/[slug]/page.tsx` render studies.
- `app/overview/page.tsx` renders the combined view.
- `app/admin/(dashboard)/layout.tsx` guards the admin.
- `app/work/[slug]/page.tsx` serves legacy project pages.

The public record pages are statically generated from the registry. `generateStaticParams()` enumerates existing studies; `dynamicParams = true` allows a new slug to render without a rebuild in a dynamic environment; `revalidate = 300` provides a short revalidation window.

### 4.2 Middleware

`middleware.ts` does two jobs:

1. **Session refresh.** It calls `refreshSession` from `lib/supabase/middleware.ts`, copies rotated cookies onto the forwarded request, and returns the response.
2. **Subdomain routing.** It classifies the host and rewrites `os.helsagrace.site`, `daily.helsagrace.site` and the Vela host onto their internal route prefixes. Canonical prefixes are stripped so the subdomain serves the same pages at its root.

API routes bypass host rewriting but still refresh the session. The matcher excludes Next internals and static assets.

### 4.3 Layouts and providers

The root layout loads three fonts through `next/font/google`: Instrument Serif (display), IBM Plex Mono (mono) and Manjari (body). It also mounts global motion components and metadata.

The record layout imports `concept.css` and wraps the content in `.concept-root`. The private products have their own layouts and design tokens.

### 4.4 Server and client boundaries

- Public pages are server components that read local content and render HTML.
- Interactive pieces (mobile menu, motion, galleries) are client components.
- Admin pages are server components guarded by `getCurrentUser()` and `isCurrentUserAdmin()`.
- The welcome screen is a server component composed of local content and a client navigation layer.

This split keeps the public reading experience fast and the admin dynamic.

---

## 5. Content architecture

### 5.1 Snapshot and merge

`lib/concept-content.ts` imports `content-snapshot.json`, normalises the shape (the snapshot can be an array of CMS rows or a single object with a `data` field), and passes it through `mergeContent()` in `lib/cms.ts`. The result is a typed `SiteContent` object.

This lets the public site render without a live Supabase connection while preserving the same shape the CMS would return.

### 5.2 Path configuration

`paths` in `lib/concept-content.ts` defines each record:

- identity, kicker, name and discipline;
- promise, subhead and proof line;
- ordered featured projects;
- contents and proof points;
- about copy and résumé link;
- contact heading and copy.

The hub, the welcome cards and the overview read from this configuration.

### 5.3 Case study registry

`lib/case-studies.ts` defines the model and the two registries:

- `buildCaseStudies` is derived from the featured build projects and their stories.
- `designCaseStudies` is a literal array of design case studies.
- `allCaseStudies` concatenates both.

Helper functions expose studies by record, featured status, slug and next-study order. Hubs, archives, sitemap and counts all derive from these arrays.

### 5.4 Documentation-generated entries

`scripts/sync-project-documentation.mjs`:

1. reads `public/project-documentation/<Project>/PORTFOLIO_CONTENT.md`;
2. extracts the fenced `json portfolio-entries` block;
3. validates exactly two entries per project, one per record, and four unique slugs overall;
4. writes `lib/documented-projects.ts` with typed `CaseStudy` objects;
5. supports `--check` to fail when the generated file does not match the Markdown.

The generated studies are appended to the registries after the existing entries, so existing content is preserved and the new work is additive.

### 5.5 Content status

The public pages read from the local snapshot and registry. The admin writes to Supabase. The long-term relationship between the snapshot and the database is a product decision that has not been finalised; the build log records it as an open question rather than assuming one.

---

## 6. Case study system

### 6.1 Block model

`CaseStudyBlock` supports:

- `narrative` — label, heading, paragraphs, bullets, optional image;
- `steps` — label, heading, intro, numbered steps;
- `quote` — quote and attribution;
- `metrics` — value/label pairs;
- `gallery` — labelled images, columns and grid or marquee layout;
- `architecture` — labelled nodes and a note;
- `reflection` — paragraphs and optional cards;
- `next` — paragraphs and bullets;
- `system` — colours, typography and components.

### 6.2 Renderer

`components/concept/case-study-view.tsx` renders the study shell:

- back link to the record;
- status pill;
- record/category kicker;
- title, subtitle and summary;
- role, category, status and year metadata;
- optional links and live product link;
- cover image;
- contents rail;
- block sections;
- reflection and next study;
- a link to the other record hub.

The renderer is shared by both records. The record determines the surrounding surface; the blocks determine the content.

### 6.3 Metrics filtering

The renderer filters `metrics` blocks out of the displayed study:

```ts
const blocks = study.blocks.filter((block) => block.kind !== "metrics");
```

Metrics are still used in the broader portfolio hero and footer, but they are not rendered inside a study. New studies must not rely on a metrics block to communicate essential information. This is a real implementation detail that the older CONCEPT notes do not reflect.

### 6.4 Images

`components/concept/study-images.tsx` wraps the image component with:

- landscape default ratio (16/10) and portrait default (3/4);
- optional explicit Tailwind ratio;
- `cover` or `contain` fit;
- caption and alt text;
- priority loading for images near the end of long pages;
- gallery overlay support.

The component is used for covers, galleries and inline images.

### 6.5 Theme accents

A study can define `theme.accent` and `theme.accentSoft`. These are applied inside the study content, allowing a product's own colour to appear without changing the record shell. The OPay case study uses this to bring its green into the Casebook content while the header and footer stay purple.

---

## 7. Routing, metadata and discovery

### 7.1 Routes

The record routes are generated by slug. `generateMetadata` reads the study and produces the title and description. `generateStaticParams` enumerates the registry.

The archive pages render the full record. The hubs render the featured set. The overview renders both.

### 7.2 Sitemap

`app/sitemap.ts` maps `buildCaseStudies` and `designCaseStudies` to their study URLs, adds the welcome, overview, both hubs and both archives, and includes the legacy `/work/[slug]` pages. Adding a study to either registry automatically adds it to the sitemap.

### 7.3 Redirects

`next.config.ts` redirects:

- `/explore` → `/` (the old choice screen is gone);
- `/casebook/opay` → `/casebook/opay-case-book`;
- legacy build URLs to their `-build-log` slugs.

These redirects preserve old links without keeping the old navigation model.

### 7.4 Metadata and fonts

The root layout defines the site metadata, the title template and the description. Fonts are self-hosted through `next/font`, which avoids a render-blocking third-party request.

---

## 8. Admin and CMS

### 8.1 Authentication

Supabase Auth provides email/password sessions. `lib/supabase/server.ts` exposes `getCurrentUser()` and `isCurrentUserAdmin()`. `lib/supabase/middleware.ts` refreshes cookies on every request.

### 8.2 Guard

`app/admin/(dashboard)/layout.tsx`:

1. shows a setup notice if Supabase is not configured;
2. redirects unauthenticated users to `/admin/login`;
3. shows an unauthorized notice for signed-in users who are not owners;
4. renders the admin shell only for owners.

The owner allowlist is enforced in the database (`admin_users` and `is_admin()`), not just in the layout.

### 8.3 Content model

The admin edits a single `site_content` JSON document with append-only `content_revisions`. Media is stored in a Supabase bucket. Contact submissions are stored in `contact_messages`.

### 8.4 Admin surfaces

`components/admin` includes editors for about, capabilities, disciplines, history, media, messages, process, profile, projects, résumé and stack. The dashboard shows the available collections and the publish state.

### 8.5 Verification status

The admin code is implemented, but it was not exercised in this documentation pass because it requires owner credentials. The setup notice, login route and guard are present in source. A live end-to-end admin pass remains a validation task.

---

## 9. Contact and email

The contact form posts to a server route that uses Resend. The implementation includes:

- a honeypot field;
- rate limiting;
- server-side validation;
- storage of the submission in `contact_messages`;
- a clear success or failure state.

The form requires a Resend key. Without it, the public site still renders, but a submission cannot be delivered. No live submission was sent during documentation.

---

## 10. Design system implementation

### 10.1 Global tokens

`app/globals.css` declares Tailwind v4 theme tokens:

```
--color-base: #f9f9fb
--color-surface: #ffffff
--color-ink: #0f0f14
--color-ink-mid: #3a3a45
--color-muted: #6b6b7a
--color-border: #e4e4e9
--color-accent: #5b4fe8
--color-accent-light: #eeecff
--color-accent-dark: #3d33c4
--font-sans: Manjari, Noto Sans, system-ui
--font-serif: Instrument Serif, Georgia, serif
```

Private products add their own token families (OS, devotional, recovery, Vela) in the same file.

### 10.2 Record tokens

`app/concept.css` defines the record surfaces with `--path-*` variables, including light and dark variants. The dark Build Log uses the same variable names with different values, so components do not branch on theme.

### 10.3 Typography

- Display: Instrument Serif.
- Body: Manjari.
- Mono: IBM Plex Mono.

Italic display emphasis is used for the second clause of key statements. Mono labels are uppercase with wide tracking.

### 10.4 Components

The concept components cover the shared shell, hubs, cards, study blocks, images, contents rail, mobile menu and social links. The welcome screen has its own cover layout. The admin uses a separate, utilitarian component set.

### 10.5 Motion

`components/motion` includes:

- a custom cursor;
- magnetic hover;
- masked word reveals;
- scroll progress;
- smooth scrolling with Lenis;
- a click burst.

Motion is global but restrained. The site respects reduced motion, and content is readable without animation.

### 10.6 Trade-offs

The custom cursor and smooth scroll add personality but also risk. They must not interfere with keyboard use, touch scrolling or reduced-motion preferences. The implementation includes guards, but a formal accessibility audit is still outstanding.

---

## 11. Performance and accessibility

### 11.1 Performance choices

- Public pages are statically rendered.
- Fonts are self-hosted through `next/font`.
- Images use explicit aspect ratios to avoid layout shift.
- Motion is client-side and does not block first paint.
- The public site does not require a backend connection.

### 11.2 Accessibility choices

- Skip link to the main content.
- Semantic landmarks and heading order.
- Visible focus states.
- Keyboard-operable mobile menu with focus trap and Escape handling.
- Alt text and captions on study images.
- Reduced-motion handling.
- Labels on form controls.

### 11.3 Outstanding

- No axe or screen-reader audit is recorded.
- No performance budget or Lighthouse record is stored.
- The custom cursor and smooth scroll need explicit keyboard and reduced-motion verification.
- Some legacy components and newer concept components coexist; consistency should be audited over time.

---

## 12. Testing and quality assurance

### 12.1 Automated tests

Five Vitest files:

| File | Area |
|---|---|
| `tests/time/wat.test.ts` | West Africa Time handling |
| `tests/email/weekly-review.test.ts` | Weekly review email composition |
| `tests/os/profile.test.ts` | OS profile logic |
| `tests/os/review.test.ts` | OS review logic |
| `tests/os/tasks.test.ts` | OS task logic |

The tests cover shared logic and private product behaviour. The public case study registry, block renderer and documentation sync are not covered by unit tests.

### 12.2 Type checking and lint

`npm run typecheck` runs `tsc --noEmit` with strict settings. `npm run lint` runs ESLint. The validation run for this documentation session is recorded in section 14.

### 12.3 Build

`npm run build` runs the Next.js production build, including static generation of record pages. The build must succeed after the four new entries are added.

### 12.4 Browser verification

The base evidence run captured ten screenshots (five desktop, five mobile). A second integration run captured twenty more (ten desktop, ten mobile), covering both hubs, both archives, the four new studies and two existing studies kept as regression evidence. The harness verified:

- page readiness;
- loaded fonts and images;
- finite animations;
- two animation frames;
- zero runtime errors;
- no horizontal overflow.

The base run covers the welcome screen, both hubs, the overview and one Build Log study. The integration run covers the updated hubs and archives, `/casebook/craftcode-academy-casebook`, `/build-log/craftcode-academy-build-log`, `/casebook/helsagrace-portfolio-casebook`, `/build-log/helsagrace-portfolio-build-log`, and the existing CareerCraft and OPay studies. Both runs used a production build served by `next start`, so no development overlay appears in the captures.

### 12.5 Documentation validation

The sync script validates:

- both documentation files contain a parseable entry block;
- each project has exactly two entries, one per record;
- the four slugs are unique;
- `--check` passes after generation.

This is the strongest automated guarantee that the published entries match the authoritative Markdown.

### 12.6 Gaps

- No authenticated admin test.
- No contact delivery test.
- No accessibility audit.
- No visual regression baseline.
- No test for the case study registry counts or sitemap inclusion.
- `next/image` requests quality 92, which is not declared in `images.qualities`; Next.js logs a warning and will require the setting in version 16.
- The integration capture verifies rendering, links and overflow, but it does not submit the contact form, sign into the admin or edit content.

---

## 13. Build, deployment and operations

### 13.1 Local development

`npm run dev` starts the Next.js dev server. The public site works without environment configuration; the admin shows a setup notice and the contact form cannot deliver without Resend.

### 13.2 Production build

`npm run build` produces the App Router output. Record pages are generated from the registry. The build is the release gate used in this documentation pass.

### 13.3 Hosting

The README states deployment to Vercel / Orizon. Environment values are set in the host and in `.env.local` for local admin work. There is no `vercel.json` in the repository; configuration is handled by the platform defaults and the Next.js config.

### 13.4 Releases

Adding content is a code release because the studies live in the registry or in generated data. This is a deliberate trade-off: static reliability in exchange for a rebuild when content changes.

### 13.5 Operations

- Content admin requires Supabase.
- Contact requires Resend.
- Media is stored in Supabase storage.
- The sitemap is generated at build time.
- Documentation is synchronised before building.

### 13.6 Privacy

The public site does not expose private product routes in navigation or the sitemap. The admin is owner-gated. Documentation does not reproduce environment values, credentials or private user data.

---

## 14. Validation record

This section records the checks run for the documentation and integration work on 16 November 2026.

| Check | Command | Result |
|---|---|---|
| Documentation sync | `node scripts/sync-project-documentation.mjs` | Pass — four entries written |
| Sync integrity | `node scripts/sync-project-documentation.mjs --check` | Pass — "Four portfolio entries match their authoritative Markdown." |
| Type check | `npm run typecheck` | Pass — no errors |
| Tests | `npm run test` | Pass — 56 of 56 tests across 5 files |
| Lint | `npm run lint` | Pass with warnings — 0 errors, 27 warnings (pre-existing) |
| Production build | `npm run build` | Pass — all four new routes prerendered |
| Base browser capture | `node scripts/capture-project-evidence.mjs portfolio` | Pass — 10 of 10, zero runtime errors, zero horizontal overflow |
| Browser integration capture | `node scripts/capture-project-evidence.mjs portfolio --integration` | Pass — 20 of 20, zero runtime errors, zero horizontal overflow |
| Documentation link audit | Relative links and entry image paths resolved on disk | Pass — 48 links and 26 image paths, none missing |
| Route presence | `.next/prerender-manifest.json` inspected | Pass — the four documented study routes are present |

One code defect surfaced during the capture pass and was fixed: the `system` block rendered colour swatches keyed by hex value, and the portfolio palette uses `#0F0F14` for two named tokens, producing a duplicate React key. The key is now `name + hex` (`components/concept/case-study-view.tsx`). Nothing else in the application was changed.

> A pending result is not a pass. Every result above was produced by running the command named in the row.

---

## 15. Status, gaps and next engineering steps

### 15.1 Complete

- Next.js App Router site with welcome, two records, overview, archives and study pages.
- Typed case study model and shared block renderer.
- Registry-driven hubs, counts, next-study links and sitemap.
- Documentation sync from Markdown to generated TypeScript.
- Public site that works without backend configuration.
- Owner-gated Supabase admin and content revisions.
- Five automated test files for shared and private-product logic.
- Responsive browser verification at 1440 × 1000 and 390 × 844.

### 15.2 Incomplete

| Item | State | Impact |
|---|---|---|
| Four new entries | Integrated and captured | Visible on both records, hubs and archives |
| Validation run | Complete — see section 14 | Results recorded with command output |
| Admin end-to-end pass | Not run | Admin is implemented but unverified live |
| Contact delivery | Not tested | Depends on Resend configuration |
| Accessibility audit | Not run | Risk on motion and custom cursor |
| Registry tests | Not written | Regressions rely on type checking and browser checks |

### 15.3 Documentation discrepancies

1. `CONCEPT.md` describes `/explore` as the choice screen; `/explore` now redirects to `/`.
2. The README names Instrument Serif + Inter; the current layout uses Instrument Serif + Manjari + IBM Plex Mono.
3. `CONCEPT.md` lists metrics as part of the study flow; the renderer filters them out.
4. The README's test count and the current suite differ because they describe different moments.
5. The older CONCEPT template names do not mention the `system` block, which the current renderer supports.

### 15.4 Recommended next steps

1. Add tests for the registry counts, sitemap inclusion and sync check.
2. Exercise the admin end to end with an owner session.
3. Run an accessibility audit focused on motion, cursor and mobile menu.
4. Update `CONCEPT.md` and the README to match the current routes and typography.
5. Declare the quality value used by `next/image` in `images.qualities` before moving to Next.js 16.
6. Extend browser verification to the contact form and admin submission paths.

### 15.5 Maintenance rules

- Keep Markdown authoritative for project documentation.
- Run the sync script before every build that includes documentation.
- Do not hand-edit generated entries.
- Preserve existing studies when appending new ones.
- Keep private products out of the public case study system.
- Update status labels when a product changes state.

---

### Evidence index

| Evidence | Location |
|---|---|
| Case study model and registry | `lib/case-studies.ts` |
| Content snapshot and paths | `lib/concept-content.ts`, `content-snapshot.json` |
| Study renderer | `components/concept/case-study-view.tsx` |
| Image system | `components/concept/study-images.tsx` |
| Hubs and cards | `components/concept/path-hub.tsx`, `work-section.tsx` |
| Welcome screen | `components/welcome/welcome-screen.tsx` |
| Global tokens | `app/globals.css` |
| Record tokens | `app/concept.css` |
| Middleware | `middleware.ts`, `lib/supabase/middleware.ts` |
| Admin guard | `app/admin/(dashboard)/layout.tsx` |
| Sitemap | `app/sitemap.ts` |
| Documentation sync | `scripts/sync-project-documentation.mjs` |
| Screenshots and manifest | [`PROJECT_ASSETS`](./PROJECT_ASSETS) |
| Product rationale | [PROJECT_CASEBOOK.md](./PROJECT_CASEBOOK.md) |
