Projects - Simplifying a portfolio platform and making releases verifiable

Problem

This portfolio depended on same-URL HTML and Markdown negotiation and a version-specific Next.js patch. The public career navigation led to a PDF, and current technical positioning had limited supporting career and service pages.

Constraints

Preserve the existing Next.js, React, Contentful and Vercel stack, the existing resume PDF, article and project URLs, and normal framework caching behavior. Avoid unsupported professional outcomes and prevent incomplete required CMS content from reaching production.

Architecture

Canonical page routes serve HTML. Explicit /api/agent-content routes serve Markdown with noindex. Contentful supplies navigation, site settings, core Page entries, articles and work details through a server-only GraphQL client. Shared section components and rich-text renderers consume the validated CMS data. GitHub checks validate changes; the production workflow verifies the staged deployment before promotion and verifies the canonical domain afterward.

Data flow

Published Contentful content flows through bounded paginated queries, response validation, section transformation, shared components and detail metadata into canonical HTML. Draft Mode uses the preview credential and uncached preview-enabled queries. Source markers tie rendered pages to CMS entry identities. Structured intake goes through bounded request parsing and Zod validation before the delivery provider accepts an inquiry. CSP reports are normalized to directive and origin fields before logs and monitoring.

Trade-offs

Separating representations removes transparent Markdown negotiation and the custom patch dependency. Pages use the existing Contentful Page and section models through shared rendering components. The six Experience and Services landing pages were published and verified on September 9, 2026. Release checks now require their published CMS identities, alongside the original core pages, rather than accepting repository fallbacks as a completed rollout.

Safeguards

Promotion fails on missing required CMS content, incorrect deployment identity or broken detail routes. The content-health gate and deployment verifier require published CMS identities for Experience and Services as well as the core pages. Authoring scripts require explicit space and environment targets and do not publish drafts. Preview and revalidation routes enforce separate credential boundaries. API payloads are bounded. CSP reporting is report-only and omits paths, query strings and script samples. The AI brief generator remains gated pending approved provider configuration, shared quota and real-model evaluation; generation and inquiry submission are separate actions.

Testing

Required repository checks cover unit behavior, type safety, formatting, accessibility, mobile overflow, routing and cache representation. Production verification checks real content and canonical detail metadata. Intake delivery is intercepted in browser tests, so tests do not send real inquiries. Implementation was developed with AI assistance and checked through the repository and deployment gates.

Accessibility

The intake uses visible labels, associated field errors, focus on the first invalid field, and live status and alert regions. Additional project details remain optional. Automated accessibility checks support review but do not replace human assistive-technology testing.

Performance

Negotiation-only dynamic rendering and unused import optimization configuration were removed. Existing Speed Insights remains in place. A bounded Work-page investigation found that critical hero text began transparent during its entrance animation. The correction preserved movement while keeping hero text opaque. Three subsequent mobile lab traces identified the hero as the only LCP candidate at first contentful paint; the median observed LCP was 1,963 milliseconds. Different runner speeds limit aggregate before-and-after attribution. These observations do not establish real-user performance, and a matching 28-day route/device field baseline is still needed.

Outcome

The production site exposes a canonical Experience page, four service details, structured detail metadata and structured intake. The September 9 publication record verifies the six Experience and Services landing pages, and the current read-only health audit resolves all twelve required CMS page queries, four articles, three legacy projects and the preview query. Earlier synthetic checks recorded a normalized CSP report and authenticated webhook cache invalidation. This review did not exercise a real Contentful publish event or send a real inquiry. These are engineering and release observations, not measured client-acquisition outcomes.

Evidence and limits

The engineering record includes repository release documentation, dated Contentful health audits and checks against exact deployments. The September 9 publication verification supersedes the earlier draft-only state. On October 18, the patched production build passed the twelve-page Contentful health audit; main CI passed, and the production candidate and canonical site passed twenty-three release checks plus desktop and mobile browser QA. The automatic promotion lookup was blocked by CI authorization; the reviewed release was verified and promoted through existing authenticated CLI access. No real email delivery, actual webhook publish-event delivery or field Core Web Vitals were measured in that October review. Historical performance observations are lab measurements tied to the September investigation and its retained diagnostic report; raw CI artifacts had fourteen-day retention. These observations establish engineering checks, not measured client-acquisition outcomes.

Related services and writing

Headless CMS architecture

Next.js performance and reliability

Content health and reliable releases

Discuss a platform project