The Brief

Dr. Lucía Peña runs three community health clinics in the mountains north of Santiago, Dominican Republic. Her patients come from villages where the nearest hospital is two hours away.

Everything is paper. When a patient sees a doctor at the Jarabacoa clinic and then walks into the Santiago clinic, the nurse calls Jarabacoa and hopes someone finds the folder. Last month, a medication interaction was nearly missed because one doctor didn't know what another had already prescribed.

Lucía needs a digital patient records system. But this is medical data. Doctors should see clinical notes. Nurses should see care plans. Admin should see scheduling. Nobody should see everything. Her board approved $4,000 USD for development and has two requirements: patient data stays in-country, and they want monthly reporting on patient volumes per clinic.

Your Role

You build the patient portal -- a system where staff at any clinic can access patient records, with different access levels for different roles. Authentication, authorization, and role-based access control are the core of this project.

The planning pipeline continues from before. You still have templates and guides. What changes: the work you direct AI to do now has direct security consequences. An API route without authorization middleware is not just a missing feature -- it is an exposed endpoint serving medical data to anyone who can construct an HTTP request.

What's New

Last time you containerized Pemba's booking system -- wrapping an existing application in Docker so it runs the same everywhere. You wrote Dockerfiles, managed multi-container environments, and experienced how infrastructure decisions affect reliability.

Two things change.

You implement authentication and authorization. Every route, every component, every data query is affected by auth. It is not a feature you add -- it is a structural decision that runs through the entire application. Sessions, password hashing, role-based middleware, protected API routes.

You write E2E tests. Playwright enters. Instead of testing components in isolation, you test complete user flows through the full stack -- login, navigate, access data, verify permissions. The tests you write here catch failures that unit tests never will.

The hard part is AI's auth code. It looks complete. It passes the tests you think to write. And it enforces access on the wrong side -- hiding buttons in the frontend while leaving API routes wide open. You catch this by testing adversarially: log in as the wrong role, make a direct API request, and check whether the server actually denies it.

Tools

• Claude Code -- AI coding agent, VS Code extension. Primary tool.
• Git and GitHub -- version control, remote repo, issues, project board.
• VS Code with Claude Code extension.
• Next.js with App Router -- continuing.
• PostgreSQL -- continuing.
• Playwright -- E2E testing. New in this project.
• Clerk or NextAuth.js -- managed authentication. New in this project.
• Vitest and React Testing Library -- continuing.
• Tailwind CSS -- continuing.
• Chrome DevTools -- continuing.

Materials

• Lucía's forwarded email chain -- the board chair's budget approval and Lucía's original request. Enough to understand the problem, not enough to build the solution. You ask her the rest.
• Auth guide -- authentication vs authorization, sessions vs JWTs, password hashing, trust boundaries, RBAC patterns, secure cookie configuration, common AI pitfalls. Reference, not a tutorial.
• Planning templates -- PRD template with access control matrix, architecture decision template, test strategy template.
• CLAUDE.md -- project governance file with the ticket list, tech stack, and verification targets.