NextChair/docs/phase-2-summary.md

NextChair — Phase 2 Summary

Project scaffold, design system, database schema, authentication foundation

Status: Complete and verified. Typecheck, lint, and next build are all clean. The full schema was migrated against a real Postgres instance and the entire auth flow (register → sign-in → sign-out → permission-gated routing) was exercised end-to-end in a browser, not just eyeballed. See §7 for exactly what was verified and how.

Per your instructions, this phase stops here: no booking, appointments, loyalty, or staff/owner functionality has been implemented. Where those areas needed a route to exist for the layout/nav/auth architecture to be provable, the route renders a labeled "Coming in Phase N" placeholder — see §3.

---

1. What was built

1. Project scaffold — Next.js 16 (App Router, Turbopack), React 19, TypeScript 6 (strict), Tailwind CSS v4, ESLint 9 (flat config), Prettier.
2. Architecture — src/ layout, five route groups ((public) reserved, (auth), (customer), (staff), (owner)), a proxy.ts (Next 16's renamed middleware.ts) gating protected paths, and a features//lib//services//components/ separation matching the structure proposed in docs/implementation-plan.md §11.
3. Design system — 20 reusable components under components/ui, components/navigation, and components/feedback, all built from the visual language in /templates, plus a /style-guide reference page showing every one with placeholder content.
4. Database schema — a complete prisma/schema.prisma covering every entity your brief listed (and a few more identified in the Phase 1 domain model), migrated and seeded successfully against a real Postgres database.
5. Authentication foundation — email/password (Credentials) and Google OAuth via Auth.js (NextAuth v5), a working register → auto-sign-in flow, sign-out, and real role/permission-based route gating (not just "is logged in").

---

2. Folder structure

NextChair/
  docs/
    implementation-plan.md      # Phase 1 output
    phase-2-summary.md          # this file
  prisma/
    schema.prisma
    seed.ts
    migrations/20260802161213_init/migration.sql
  templates/                     # untouched — 35 UX Pilot exports + prototypes
  src/
    app/
      (auth)/                    # sign-in, register — shared centered-card layout
      (customer)/                # home, appointments, settings — light bottom nav, session-gated
      (staff)/staff/              # calendar, current, clients, settings — dark bottom nav, StaffProfile-gated
      (owner)/owner/               # dashboard, team — same shell as (staff), MANAGE_STAFF-gated
      api/auth/[...nextauth]/route.ts
      style-guide/                # design-system showcase (reference only)
      page.tsx                    # Welcome/splash
      layout.tsx, globals.css
    auth.ts                       # full NextAuth config (adapter + real providers)
    auth.config.ts                # DB-free subset, used by proxy.ts
    proxy.ts                      # Next 16's middleware convention — see §6
    components/
      ui/                         # Button, Card, Input, Textarea, Select, Checkbox, Switch,
                                   # Modal, BottomSheet, Tabs, MonthCalendar, AppointmentCard,
                                   # ServiceCard, BarberCard, ProfileCard, LoyaltyCard, StatusPill
      navigation/                 # BottomNav, TopNav
      feedback/                   # EmptyState, ErrorState, LoadingState, Skeleton, ComingSoon
    features/auth/                # schemas, register server action, sign-in/up/out components
    lib/
      auth/permissions.ts         # StaffProfile → Role → RolePermission lookup
      db/prisma.ts                # the one file that imports the Postgres driver adapter
      navigation/staff-nav-items.ts
      utils/cn.ts
    types/
      domain.ts                   # UI-facing types, deliberately independent of the ORM
      next-auth.d.ts              # session.user.id module augmentation

---

3. What each route actually does right now

Route	Renders	Gate
/	Welcome/splash (matches template 20, minus "Continue as Guest" — see §8)	redirects to /home if already signed in
/sign-in, /register	Real, working forms	none
/home, /appointments, /settings	/home and /settings show real session data + a working sign-out; /appointments is a labeled placeholder	any authenticated session
/staff, /staff/current, /staff/clients	Labeled placeholders	authenticated and has a StaffProfile
/staff/settings	Real profile card + conditional "Switch to Owner Admin" link (only if the signed-in staff member's Role grants MANAGE_STAFF) + sign-out	same as above
/owner, /owner/team	Labeled placeholders	authenticated, has a StaffProfile, and MANAGE_STAFF permission

Every placeholder exists only to prove the layout/nav/auth architecture around it works — none contain business logic. This was a deliberate choice to satisfy "Create the architecture: Route groups, Shared layouts" (Phase 2 scope §3) without drifting into "Staff functionality, Owner functionality" (explicitly excluded).

---

4. Design system

All 20 components are in components/ui, components/navigation, components/feedback. Highlights and the judgment calls behind them:

• Tokens (globals.css) — Tailwind v4's CSS-based @theme, carrying forward the ink/stone/surface/muted/line/accent palette that dominated the templates (Phase 1 plan §8), not the salon-red or blue variants found on two outlier templates. Added a --color-accent-loyalty token for the gold loyalty-card accent instead of letting it leak into the base palette.
• Button — cva-based variants (primary/accent/secondary/ghost/destructive), asChild via Radix Slot so it can wrap a Next Link and still look like a button.
• Switch, Tabs — Radix primitives. These are the two places a hand-rolled implementation is genuinely easy to get subtly wrong (roving tabindex, aria-checked); the templates' own switchTab() DOM-manipulation script is exactly the kind of thing this replaces.
• Modal, BottomSheet — built on the native <dialog> element rather than Radix Dialog or a hand-rolled focus trap. showModal() gives focus containment, Escape-to-close, and top-layer stacking from the browser for free. No template had a modal/sheet pattern at all (Phase 1 §8 flagged this as a gap); these are new.
• Select, Checkbox — deliberately native <select>/<input type="checkbox">, not Radix — native select gets the OS picker on mobile for free, which no custom listbox matches.
• MonthCalendar — real date math (no external date library), matches the templates' booking/reschedule calendar. The staff day/agenda calendar is not built — Phase 1 §14 found the templates disagree on its layout (grid-columns vs. vertical agenda) and it depends on the booking engine's availability model, which doesn't exist yet.
• LoyaltyCard — ports the 3D flip card from template 11 faithfully, but fixes a real gap: the original had no actual flip trigger wired up (presentational only). Here it's a real <button aria-pressed>, and the flip transition respects prefers-reduced-motion.
• BottomNav — one component serves both the customer (light) and staff/owner (dark) variants, replacing the four inconsistent nav markups found across the templates. It resolves its own "active" tab from usePathname() rather than requiring every layout to compute and pass it — see the RSC lesson in §6 for why its icon prop is a string key, not a component reference.
• EmptyState, ErrorState, LoadingState, Skeleton — none of these existed in any template; every list screen needs one for the zero-items/failure/loading case.

---

5. Database schema

Full schema in prisma/schema.prisma, migrated cleanly (prisma/migrations/20260802161213_init/migration.sql) and seeded (prisma/seed.ts) against a real Postgres instance. Covers every entity from your brief:

Business, BusinessLocation, BusinessHours, BusinessSettings, BookingRule · User, Account, Session, VerificationToken (Auth.js standard shape) · CustomerProfile, StaffProfile, Role, RolePermission · ServiceCategory, Service, StaffService · WorkingHours, Break, BreakDay, TimeOff · Appointment, AppointmentService · LoyaltyProgramme, LoyaltyEligibleService, LoyaltyEligibleStaff, LoyaltyAccount, LoyaltyTransaction, LoyaltyReward · Notification, NotificationPreference · CustomerNote, AuditLog.

Key decisions (each is a comment in the schema itself, not just here):

• Multi-service appointments. AppointmentService is a proper join table with priceAtBooking/durationAtBookingMinutes snapshots — a later price change to a Service never rewrites historical bookings. Directly required by your "support multiple services within a single appointment" instruction, and matches the "add another service" step visible in the booking templates.
• Loyalty is a ledger, not a counter. LoyaltyAccount.currentStamps is a cached total; LoyaltyTransaction is the append-only source of truth (STAMP_ADDED/STAMP_REMOVED/STAMP_EXPIRED/REWARD_REDEEMED), and LoyaltyReward records a completed redemption before the account's count resets — per your explicit instruction.
• Roles/Permissions. Role is a real per-business table (seeded with "Owner" and "Barber"); Permission is a code-defined enum joined via RolePermission. A barber who is also an owner is one User with one StaffProfile, whose Role happens to grant more permissions — never two accounts. This directly resolves the role-conflict the Phase 1 review found in the templates (a "Switch to Admin View" button with no real permission model behind it).
• Guest-friendly by design. CustomerProfile.userId is nullable and email/phone are not unique-constrained — a hard constraint would force guests to either collide with each other or be blocked from repeat bookings under a shared household email/phone. Guest deduplication stays an explicit open question (Phase 1 plan §15, Question 4), not something silently decided by a DB constraint.
• Portability (Postgres → MySQL). No scalar-list columns anywhere — Break's applicable days are a BreakDay join table, not a Weekday[] array, because MySQL has no native array type. Money fields use Decimal, long text uses @db.Text, dates use @db.Date, and AuditLog.metadata uses Json — all four map to native equivalent types on both providers. Recurring wall-clock times (working hours, breaks, business hours) are stored as Int minutes-from-midnight rather than a DB TIME type, so scheduling math lives in application code, not provider-specific SQL.
• AuditLog exists in the schema but nothing writes to it yet — added now so Phase 4/6 features that need it don't require a migration to start.

A real, current-generation Prisma detail worth flagging

Prisma 7 (what npm install prisma currently resolves to) changed two things that aren't yet reflected in most tutorials/training data, and I hit both empirically rather than assuming:

1. The client generates to a custom folder (generated/prisma, via the new prisma-client generator), not node_modules/@prisma/client. Connection config moved out of schema.prisma into prisma.config.ts.
2. PrismaClient now requires an explicit driver adapter (@prisma/adapter-pg for Postgres, @prisma/adapter-mariadb for MySQL) instead of a bare connection string. src/lib/db/prisma.ts is the only file in the app that imports the adapter — switching providers later means changing that one file, datasource.provider in the schema, and re-running prisma migrate dev, not touching application code.

---

6. Architecture decisions worth knowing about (found by actually building and running this, not by inspection)

• Next.js 16 renamed middleware.ts to proxy.ts, and — significantly — proxy files now run on the Node.js runtime by default, not Edge. That alone would have resolved the "Prisma isn't Edge-compatible" warning I initially hit, but I still split a DB-free auth.config.ts from the full auth.ts (§ below) because spinning up a Postgres connection pool just to check "is there a valid session JWT" on every request is wasteful regardless of which runtime it's allowed to run on.
• RSC serialization boundary bit me twice, in the same way, and I want to flag the pattern rather than bury it in a diff. A Server Component cannot pass a live function (an inline handler, or a React component reference like a Lucide icon) as a prop to a Client Component — both fail with slightly different error messages ("Event handlers cannot be passed to Client Component props" / "Only plain objects can be passed to Client Components from Server Components"). This hit ErrorState/ProfileCard demo handlers in the style guide (fixed by moving the interactive-with-real-handlers instances into an already-"use client" wrapper) and BottomNav's icon prop (fixed by passing a string key, resolved to a component inside the Client Component itself, instead of the component reference). Both fixes are the general-purpose pattern for this class of bug, not one-off patches — worth knowing before Phase 3 adds more Server-Component pages that render interactive children.
• Auth split: auth.config.ts (pages, providers: [], session strategy — no DB) vs. auth.ts (the full thing: Prisma adapter, Credentials authorize(), Google). proxy.ts builds its own lightweight NextAuth(authConfig) instance from the former; everything else (route handlers, Server Components, Server Actions) uses the latter.
• Permission enforcement happens in two places on purpose: proxy.ts does a cheap "is there a session at all" check (Edge/Node-safe, no DB), and each protected layout does the real DB-backed check (StaffProfile exists? does the Role grant MANAGE_STAFF?). This matches the Phase 1 plan's explicit instruction not to trust route-group gating alone.
• Icons: swapped the templates' Font Awesome CDN script for lucide-react tree-shaken imports, as recommended in the Phase 1 plan.

---

7. What was actually verified (not just built)

I don't consider "it compiles" sufficient proof for an auth system, so:

1. Ran prisma migrate dev against a real, throwaway local Postgres (Docker, torn down afterward — did not touch the two unrelated Postgres containers already running on this machine) — the full schema applies as real SQL, not just Prisma-schema-valid.
2. Ran the seed script against that database — business, roles + permissions, services, two staff users (an Owner and a plain Barber), and a customer all created successfully.
3. In an actual browser: registered a brand-new customer account end-to-end (form → server action → DB write → auto sign-in → redirect to /home).
4. Signed in as the seeded Owner (marcus@blakeheritage.co.uk / password123) and confirmed /owner renders for them.
5. Signed in as the seeded plain Barber (leo@blakeheritage.co.uk / password123) and confirmed /owner redirects him to /staff — the negative case, which is the one that actually matters for a permission system.
6. Confirmed a customer with no StaffProfile is bounced from /staff to /home.
7. Confirmed an unauthenticated request to any protected path (/settings while logged out) is redirected to /sign-in by proxy.ts.
8. Confirmed sign-out actually clears the session (not just a UI state change).

npm run typecheck, npm run lint, and npm run build are all clean with zero warnings.

---

8. Assumptions made this phase

• Password reset ("Forgot Password", template 8) was not wired up, even as a dead link — it needs the Notifications system (real email delivery) to do anything honest, and that's out of scope. I'd rather have no link than a link that silently does nothing, which is exactly the kind of broken-link issue the Phase 1 review flagged in the original templates.
• The Welcome/splash page's "Continue as Guest" button (template 20) isn't shown, for the same reason — it leads into the booking flow, which doesn't exist yet.
• Registration auto-signs the user in immediately, with no email-verification gate (emailVerified is modeled on User but not enforced) — consistent with the "auto-confirm" default recommended in the Phase 1 plan (§15, Question 5) and with every template's own instant-success flow.
• Seeded demo accounts (marcus@blakeheritage.co.uk, leo@blakeheritage.co.uk, alex.chen@example.com, all password password123) exist only for this verification — delete or change them before any real deployment.
• Google OAuth is wired in code but untested end-to-end (needs real AUTH_GOOGLE_ID/AUTH_GOOGLE_SECRET from a Google Cloud project, which I don't have). The Credentials path is fully verified; the Google path follows the same, standard Auth.js provider pattern and should work once real credentials are supplied — flagging this as the one piece of Phase 2 I couldn't verify firsthand.

9. What should be reviewed before moving on

• The Role/Permission seed set (prisma/seed.ts) — I picked a reasonable permission split between "Owner" and "Barber" based on the Phase 1 domain model, but you may want different defaults before this becomes load-bearing.
• Whether email verification should gate anything before Phase 2's account-creation flow is considered "final" — right now it's purely decorative on the User model.
• The route/URL naming (/staff, /owner, /home — no /customer prefix) — chosen to match the Phase 1 route map, worth confirming before more pages accumulate under it.

10. Getting a real database running

docker run -d --name nextchair-pg -e POSTGRES_USER=nextchair \
  -e POSTGRES_PASSWORD=nextchair -e POSTGRES_DB=nextchair \
  -p 5432:5432 postgres:16-alpine

npm run prisma:migrate   # applies prisma/migrations/
npm run prisma:seed      # creates the demo business/staff/customer
npm run dev

.env already has a matching DATABASE_URL and a real AUTH_SECRET; only AUTH_GOOGLE_ID/AUTH_GOOGLE_SECRET need filling in to exercise Google sign-in.

---

Ready for direction on the next slice of work — per the phasing in docs/implementation-plan.md §13, that would be Phase 2: Customer Accounts (the real, data-backed home/appointments/loyalty pages, replacing the placeholders in §3 above). Note this is the implementation plan's own Phase 2, distinct from "Phase 2" as you've been using it in this conversation to mean the whole scaffold-and-foundation stage just completed. I won't start building it until you say so.