Case study

How this website was built

A portfolio treated as high caliber software: PRD before architecture, architecture before code, and transparent documentation of decisions, including those that were revised along the way.

27risks recorded and mitigated

5ADRs with evaluated trade-offs

13numbered & tested business rules

4contradictions detected and resolved

The Spec Driven & Harness Flow

01Idea & FramingReference document defining scope, intent, and objectives

02Product PRDProblem framing, personas, success metrics, and out of scope boundaries via prd development skill

03Architecture & ContractsTechnical source of truth with ADRs, data models, and contracts via architecture design skill

04Spec Kit (.specify)Functional specification (spec.md), technical plan (plan.md), and task breakdown (tasks.md)

05Harness & AI ExecutionGuided implementation using MCPs (Context7, Serena, TestSprite) under durable governance rules

06Deploy & VerificationTen blocking CI gates, automated test suites, and production verification

AI did not write this system alone, nor was code generated from loose prompts ("vibe coding"). What is showcased is harness engineering: specification as single source of truth (SDD), hierarchical authority (PRD → Architecture → Spec → Plan → Tasks → Code), MCP servers for real time grounding, and automated test loops, with a human engineer accountable for every architectural decision.

Decisions that warranted an ADR

ADR-001

Modular monolith in serverless deploymentMicroservices rejected: a single engineer without dedicated SRE or on-call cannot sustain distributed operations.

Trade-off:no fault isolation between modules.

ADR-002

Hexagonal architecture with deliberate overheadOver engineering for a typical blog CMS. The justification is educational: extreme testability is part of what is being demonstrated.

Trade-off:more files and layer indirection per feature.

ADR-003

Dual primary adapters: HTTP and in-processPublic RSC pages call the use cases directly without HTTP loopback. This keeps the website responsive even during API spikes.

Trade-off:two paths to data with risk of rule divergence.

ADR-004

Isolated monorepo with pnpm workspacesPhysical boundary separation into decoupled packages (domain, application, infrastructure, http). Domain holds zero external dependencies (DEP-1).

Trade-off:monorepo workspace tooling and orchestration overhead.

ADR-005

In-process domain events without message brokerPublishing triggers page revalidation directly. Allows publishing in seconds without infrastructure messaging overhead.

Trade-off:best effort delivery without automated retries.

What I got wrong along the way

The most valuable part of documenting decisions is discovering when two of them contradict each other. Four critical contradictions emerged during phase review, each would have become an outage in production.

Instant rollback versus irreversible migrations

Reverting code does not revert the database. An instant rollback button would crash the app. Resolved by mandating backward compatible database migrations.

Audit log lasting only 3 days

Platform log retention is short. Calling it an audit trail was a comfortable lie. Renamed to what it actually is: recent operational visibility.

Integration tests on shared database

Parallel CI executions would collide, causing flaky tests, which is worse than no tests because it teaches developers to ignore red builds.

Accessibility required without verification

WCAG AA was mentioned three times in specs, but had zero pipeline gates. A requirement without automated verification is merely good intentions.

Open documentation & evidence

PRD, comprehensive architecture spec, OpenAPI contracts, and process evidence, presented as they were written, without cosmetic cleaning.

Interactive API Documentation (/api/docs)Go Live Readiness & Audit Report Complete PRD (docs/prd.md)Architecture Decisions (docs/architecture.md)Repository on GitHub