# Turn 3 — Next.js Frontend Skeleton

## What's new in this drop

```
apps/web/
├── package.json              Next 14 + Tailwind + shadcn-style components + React Query
├── next.config.js            PWA wrapper + dev API rewrites
├── tsconfig.json
├── next-env.d.ts
├── tailwind.config.js        Custom palette: paper / ink / saffron / moss + serif+sans pairing
├── postcss.config.js
├── .eslintrc.json
│
├── public/
│   ├── manifest.json         PWA manifest
│   ├── icon.svg              Placeholder wordmark (replace in design pass)
│   ├── ICONS.md              How to generate proper PNG icons
│   └── robots.txt            Blocks indexing (private app)
│
└── src/
    ├── app/
    │   ├── layout.tsx                  Root layout, fonts (Cormorant + Manrope)
    │   ├── globals.css                 Theme, paper texture, status pills
    │   ├── providers.tsx               React Query
    │   ├── page.tsx                    Home redirect by auth state
    │   │
    │   ├── login/page.tsx              FULL: working login form
    │   ├── role/page.tsx               FULL: dual-role chooser
    │   │
    │   ├── captain/
    │   │   ├── layout.tsx              Auth shell wrapper
    │   │   ├── page.tsx                Dashboard with live stat tiles + attention card
    │   │   ├── vihars/page.tsx         Stub (Claude Code task: vihar-list)
    │   │   ├── vihars/new/page.tsx     Stub (Claude Code task: vihar-create-form)
    │   │   ├── volunteers/page.tsx     Stub (Claude Code task: volunteer-master)
    │   │   ├── stats/page.tsx          Stub (Claude Code task: captain-dashboard-charts)
    │   │   └── profile/page.tsx        Read-only profile
    │   │
    │   ├── volunteer/
    │   │   ├── layout.tsx              Auth shell wrapper
    │   │   ├── page.tsx                Dashboard with live personal stats
    │   │   ├── history/page.tsx        Stub
    │   │   ├── leaderboard/page.tsx    Stub
    │   │   ├── stats/page.tsx          Stub
    │   │   └── profile/page.tsx        Read-only profile
    │   │
    │   └── v/[id]/page.tsx             Deep link from WhatsApp - routes to correct view
    │
    ├── components/
    │   ├── ui/
    │   │   ├── button.tsx              Variants: default, accent, outline, ghost, link, destructive
    │   │   ├── card.tsx                Card + Header + Title + Description + Content + Footer
    │   │   ├── input.tsx
    │   │   └── label.tsx
    │   └── layout/
    │       ├── app-header.tsx          Brand + role badge + profile + logout
    │       ├── auth-shell.tsx          Auth-gated wrapper used by both role layouts
    │       └── bottom-nav.tsx          Role-aware tabs with saffron active indicator
    │
    ├── lib/
    │   ├── api.ts                      Fetch wrapper (cookies, error unwrap)
    │   ├── auth.ts                     useMe / useLogin / useLogout / useRequireAuth hooks
    │   └── utils.ts                    cn() classname helper
    │
    └── hooks/                          (empty - filled in Claude Code tasks)
```

## Design language

Calm, dignified, slightly traditional. The opposite of generic SaaS.

- **Display font:** Cormorant Garamond — refined serif, classical character
- **Body font:** Manrope — humanist sans, modern but warm
- **Mono:** JetBrains Mono — for usernames, phone numbers, codes
- **Palette:**
  - `paper` — warm off-white background (#fbf8ef)
  - `ink` — warm near-black for text and primary buttons
  - `saffron` — single restrained accent gesturing at Jain culture (active states, key actions)
  - `moss` — secondary green for success / completed states
  - `rust` — destructive / error
- **Decoration:** A faint dotted paper texture, a recurring saffron rule (12px wide divider), saffron underline in active nav. Otherwise restrained.
- **No gradients** except the WhatsApp green button and the very subtle saffron-tint on the volunteer's "Next vihar" card. No purple. No blur effects beyond the sticky header backdrop.

## What's working end-to-end after `pnpm dev`

1. Open `http://localhost:3001` → redirects to `/login`
2. Log in with `captain1` / your seeded password → cookie set, redirect to `/role` (because seeded user is dual-role)
3. Pick Captain Mode → land on `/captain` with live stats from `/api/stats/city`
4. Bottom nav switches between Home, Vihars, Sevaks, Stats. All routes exist.
5. Tap profile icon in header → see your details. Tap logout → cookie cleared, back to login.
6. Pick Volunteer Mode from `/role` → `/volunteer` with personal stats from `/api/stats/me`
7. WhatsApp deep link `/v/123` resolves to either `/captain/vihars/123` or `/volunteer/vihars/123` based on role

## How to run after pulling Turn 3

```bash
cd vihar-sewa
pnpm install      # picks up the new web deps
pnpm dev          # web (3001) + api (4001) in parallel

# Open http://localhost:3001
```

## Known gaps to fill in Claude Code

Each placeholder page has a tag like `(Wired up in Claude Code task: vihar-create-form)` — those are the task IDs I'll generate detailed briefs for in Turn 4 / follow-up. Roughly:

| Task ID | Estimated complexity |
|---|---|
| vihar-create-form | M — Step 1 form with location autocomplete |
| vihar-allocate-step | M — multi-select volunteers |
| vihar-share-sheet | S — pull /whatsapp-message, render preview, wa.me link |
| vihar-list | S — list with status pills + filters |
| vihar-detail-captain | M — captain view + reassign + close |
| vihar-detail-volunteer | M — volunteer view + check-in/out CTAs |
| volunteer-checkin | S — geolocation prompt + submit |
| volunteer-checkout | M — start time + distance editor + tolerance UI |
| volunteer-master | M — list + add new |
| captain-dashboard-charts | M — recharts integration for top contributors, daily trend |
| volunteer-history | S — past vihars list |
| volunteer-stats | S — personal stats charts |
| leaderboard | S — table with you-row highlighted |
| profile-change-password | S — form + mutation |
| location-autocomplete-component | M — debounced Places Autocomplete with session token |

Total: ~15 Claude Code tasks, each fitting in one Claude Code session of 30-60 min on the laptop.

## Things to watch when you run it

1. **First `pnpm install` is heavy** — Next 14 + React 18 + Tailwind + Radix primitives + React Query. Allow 1-2 minutes.

2. **PWA only enabled in production builds.** `pnpm dev` skips service worker registration so HMR works cleanly. To test PWA: `pnpm build && pnpm start` (will warn about missing icon-192.png/icon-512.png — generate from icon.svg first).

3. **Login redirect loop guard** — if the API isn't running or returns 500 on `/api/auth/me`, the home page will still navigate to `/login`. Make sure both `pnpm dev:api` and `pnpm dev:web` are up.

4. **Cookie domain** — works fine on localhost. In production, the Nginx setup in Turn 4 will keep web and api on the same origin so the cookie is automatic.

5. **The cron in `auto-close.service.ts`** runs every 30 minutes via `@nestjs/schedule` — first run is silent if no in-progress vihars exist. Visible only in API logs.

## What Turn 4 will deliver

Deployment artifacts for kreonAI5:
- Nginx vhost (vihar.<your-domain>)
- PM2 ecosystem.config.js (web + api + cron)
- MySQL provisioning SQL for production
- Deploy script (pull, build, migrate, restart)
- Optional GitHub Actions CI for type-check + lint
- The 15 Claude Code task briefs as separate markdown files in `docs/tasks/`

After Turn 4 you have everything needed to: deploy on kreonAI5 with HTTPS, plug in Google Maps keys, and start filling in features one Claude Code task at a time on your laptop.