Clínica Comunitaria Esperanza -- Patient Portal

Client

Dr. Lucía Peña, Medical Director at Clínica Comunitaria Esperanza. A network of three community health clinics in the Cibao region of the Dominican Republic (Santiago, Jarabacoa, Constanza) serving rural communities with limited hospital access. 15 employees across the three clinics.

What you're building

A patient records portal with authentication and role-based access control. Staff at any clinic can look up patient records, but different roles see different data: doctors see full clinical records, nurses see care plans and vitals, admin sees scheduling and contact information. The system must be secure -- this is medical data.

Tech stack

• Framework: Next.js with App Router
• Database: PostgreSQL
• Auth: Clerk or NextAuth.js (managed auth)
• Testing: Vitest (unit/component), Playwright (E2E)
• Styling: Tailwind CSS
• Error tracking: Sentry (or equivalent)
• Language: TypeScript

File structure

p6/
  materials/
    CLAUDE.md              (this file)
    first-contact.md       (Lucía's forwarded email chain)
    guides/
      auth-guide.md        (auth concepts and patterns reference)
    templates/
      prd-template.md      (PRD template to fill)
      architecture-template.md  (architecture decision template)
      test-strategy-template.md (test strategy template)
  src/                     (built during the project)
    app/                   (Next.js App Router pages)
    lib/                   (auth, database, middleware)
    components/            (React components)
  prisma/                  (or equivalent schema)
  tests/                   (Vitest + Playwright)

Tickets

• T1: PRD and project planning -- produce the PRD from the template, define roles and access model
• T2: Database schema and auth foundation -- users, roles, permissions tables; registration, login, logout with bcrypt and secure sessions
• T3: RBAC middleware and protected routes -- authorisation middleware on all patient record endpoints; adversarial testing
• T4: Patient portal frontend -- role-aware views, auth state management, loading/error states, cache invalidation
• T5: Test strategy and E2E tests -- integration tests for protected routes, Playwright setup, E2E auth flow tests
• T6: Error tracking and observability -- Sentry integration, auth event logging, audit trail
• T7: Deploy and close -- production deployment, security cross-review, README, final push

Verification targets

• Passwords stored as bcrypt hashes (starts with $2b$), never plaintext
• Session cookies have httpOnly and secure flags
• Wrong-role API requests return 403 Forbidden
• Unauthenticated API requests return 401 Unauthorized
• All Playwright E2E tests pass (login, invalid login, role-based access denial)
• All integration tests pass (adversarial role tests)
• Sentry captures auth errors with context
• Auth event logs include user_id, role, route, timestamp

Commit convention

Commit after each ticket is complete. Use conventional commit format: feat:, fix:, test:, docs:. Each commit should describe what changed and why.