The Brief

Marco Aju runs Cacao Ixchel, a small bean-to-bar chocolate maker in Coban, Guatemala. He sources cacao from six family farms, ferments and processes it himself, and sells single-origin bars to about thirty specialty shops in the US, Germany, and Japan.

His spreadsheet system is breaking down. Last month he promised a batch of 72% Lacandon bars to Portland and didn't realize he'd already allocated them to Tokyo. That kind of mistake damages relationships with buyers who depend on reliable supply.

Marco needs a system where he can see all inventory in one place -- what cacao from each farm, what stage it's at, what's available. He needs to allocate specific inventory to orders so nothing gets promised twice. And his staff are chocolate makers, not computer people -- it has to be simple enough to use between batches.

Your Role

You are building Marco's inventory and order management system. The full stack: database, API, and frontend.

The artifact creation pipeline is the same as last time -- PRD, design decisions, CLAUDE.md, ticket breakdown -- but the terrain it applies to is fundamentally harder. Instead of planning a frontend-only React app, you're planning a system where a database schema determines what the API can return, the API determines what the frontend can display, and a mistake in the schema propagates through every layer above it.

You direct Claude Code through the entire build. But directing a backend requires different precision. "Build me an API for managing orders" is not enough -- you specify data relationships, validation rules, and status codes before any code gets generated.

A second AI reviews your schema and API design. The work is complex enough that self-review has a systematic blind spot -- a fresh model with no context about your choices will catch things you've normalized.

What's New

Last time you built an interactive React showcase with components, state management, and automated tests. You created the planning artifacts yourself for the first time, deployed to Vercel, and handled a scope addition from the client.

Three things change.

You build a backend. PostgreSQL for the database, Prisma for the ORM, Next.js API routes for the endpoints. The schema is the most consequential decision you'll make -- it determines everything downstream. Get it wrong and you're undoing work across three layers.

The frontend becomes multi-page. Next.js App Router replaces the single-page React app. Server components and client components are a new architectural choice -- where code executes (server vs browser) matters for performance, data access, and hydration behavior. You'll need to specify these constraints to Claude Code before it generates pages.

Security becomes a system concern. CORS exists because your frontend and API may run on different origins. CSRF exists because your order form modifies data. CSP exists because you now have enough JavaScript surface area to matter. These protections interact.

The hard part is the contract between layers. When the API returns a different shape than the frontend expects, the page fails silently -- the server logs show nothing wrong. Testing the API against its contract is a different activity from testing the frontend against the design, and you need both.

Tools

• Claude Code -- AI coding agent, VS Code extension. Primary tool for planning and building.
• Git and GitHub -- version control, remote repo, issues, project board.
• VS Code with Claude Code extension and ESLint.
• Next.js with App Router -- multi-page framework with server-side rendering. New.
• PostgreSQL -- relational database. New.
• Prisma -- database ORM and migration tool. New.
• React Testing Library -- component testing with accessibility-first queries. New.
• Vitest -- test runner. Continuing.
• Tailwind CSS -- utility-first CSS framework. Continuing.
• Sentry -- error tracking and alerting. New.
• Chrome DevTools Performance profiler -- flame chart analysis. New.
• Vercel CLI -- deployment to production. Continuing.

Materials

• Marco's email -- his requirements in his own words. Five numbered items, no ambiguity about what he wants, some gaps in what he hasn't thought about.
• Pipeline templates -- PRD template, design decisions template (with a new Data Layer section), ticket breakdown template. Same structure as last time, applied to harder terrain.
• CLAUDE.md -- project governance file with the full ticket list, tech stack, and verification targets.
• Seed data -- six farms, twelve batches, fifteen products, five orders. Real data to populate the database so you can see the system working from the start.
• API contract -- endpoint documentation with request/response shapes, status codes, and error responses. The contract your implementation has to honor.