From 154f79fe60c7dd2de7ab7264613575b5fa0c285a Mon Sep 17 00:00:00 2001
From: Patrick Plate <patrick.plate@adp.com>
Date: Fri, 12 Jun 2026 17:28:56 +0200
Subject: [PATCH] docs: Sprint 4 walkthrough guide

---
 .../cannamanage-sprint4-walkthrough.md        | 160 ++++++++++++++++++
 1 file changed, 160 insertions(+)
 create mode 100644 docs/sprint-4/cannamanage-sprint4-walkthrough.md

diff --git a/docs/sprint-4/cannamanage-sprint4-walkthrough.md b/docs/sprint-4/cannamanage-sprint4-walkthrough.md
new file mode 100644
index 0000000..e733d2d
--- /dev/null
+++ b/docs/sprint-4/cannamanage-sprint4-walkthrough.md
@@ -0,0 +1,160 @@
+# CannaManage Frontend — Walkthrough
+
+**Sprint 4 Delivery | 2026-06-12 | Commit: fe6e96d**
+
+---
+
+## 🚀 How to Run
+
+```bash
+cd cannamanage-frontend
+pnpm install       # first time only
+pnpm dev           # starts on http://localhost:3000
+```
+
+Note: A mock backend on port 8080 is needed for auth to not timeout. Quick mock:
+```bash
+node -e "require('http').createServer((req,res)=>{res.writeHead(401,{'Content-Type':'application/json'});res.end(JSON.stringify({error:'mock'}))}).listen(8080,()=>console.log('Mock on 8080'))"
+```
+
+Or run the real backend: `cd cannamanage-api && mvn spring-boot:run`
+
+---
+
+## 🗺️ Page Map
+
+### Admin Dashboard (requires login)
+
+| Route | Feature | Key Elements |
+|-------|---------|-------------|
+| `/login` | Admin login | Email + password, error states, i18n |
+| `/dashboard` | Club overview | 4 KPI cards, stock chart, recent distributions table, quick actions |
+| `/members` | Member list | TanStack Table with search, sort, pagination, status badges |
+| `/members/new` | Add member | Form with Zod validation, age ≥18 check |
+| `/members/[id]` | Edit member | Pre-filled form, under-21 warning |
+| `/distributions` | Distribution history | Filter by date/member, lock icons (immutable), today summary |
+| `/distributions/new` | Record distribution | 4-step form: member → quota check → batch+amount → confirm |
+| `/stock` | Batch management | Bar chart, summary cards, table with recall button |
+| `/stock/new` | Add batch | Strain selector, THC/CBD, supplier, harvest date |
+| `/reports` | Compliance reports | 3 report cards (monthly/member/recall), download + preview |
+
+### Member Portal (separate layout)
+
+| Route | Feature | Key Elements |
+|-------|---------|-------------|
+| `/portal-login` | Member login | Simplified login for members |
+| `/portal/dashboard` | Quota overview | Radial SVG progress rings (daily/monthly), color-coded |
+| `/portal/history` | My distributions | Table/cards with month filter, lock icons |
+| `/portal/profile` | Profile & settings | Personal info (read-only), password change, language/theme prefs |
+
+---
+
+## 🎨 Theme System
+
+- **Dark mode** (default): `#0D1117` bg, `#2ECC71` green accent
+- **Light mode**: `#FAFBFC` bg, `#1B7A3D` darker green accent
+- Toggle: click the sun/moon icon in the header
+- Persists via localStorage (next-themes)
+
+---
+
+## 🌐 Language (i18n)
+
+- Default: German (de)
+- Also available: English (en)
+- All UI strings come from `messages/de.json` / `messages/en.json`
+- Switching: planned for settings page (currently hardcoded to `de`)
+
+---
+
+## 🔒 Auth Flow
+
+1. User navigates to any protected route
+2. Middleware checks NextAuth session
+3. No session → redirect to `/login`
+4. Login form → POST to backend `/api/v1/auth/login`
+5. Success → NextAuth creates encrypted session cookie
+6. Client never sees the raw JWT (server-side only)
+7. Token refresh happens transparently in the `jwt` callback
+
+---
+
+## 📊 Key Business Features
+
+### Real-time Quota Check (Distribution Form)
+- Step 2 shows remaining daily (25g) and monthly (50g/30g) quota
+- Color-coded: green (<50%), amber (50-80%), red (>80%)
+- Blocks if member is suspended/expelled
+- Shows under-21 reduced limit (30g/month)
+
+### Immutable Audit Trail
+- Every distribution row shows a 🔒 lock icon
+- No edit/delete buttons on past distributions
+- Reports include "audit-trail compliant" badge
+
+### Batch Recall
+- One-click recall with confirmation dialog
+- Recalled batches disappear from distribution form
+- Recall report captures affected distributions
+
+---
+
+## 🧪 Testing
+
+```bash
+# Run E2E tests (requires dev server running)
+pnpm exec playwright test
+
+# Run type check
+pnpm exec tsc --noEmit
+
+# Run build (production validation)
+pnpm build
+```
+
+---
+
+## 📁 Project Structure
+
+```
+cannamanage-frontend/
+├── src/
+│   ├── app/
+│   │   ├── (auth)/login/           # Admin login
+│   │   ├── (dashboard-layout)/     # Admin pages (sidebar layout)
+│   │   │   ├── dashboard/
+│   │   │   ├── members/
+│   │   │   ├── distributions/
+│   │   │   ├── stock/
+│   │   │   └── reports/
+│   │   ├── (portal)/              # Member portal (top-nav layout)
+│   │   │   ├── portal-login/
+│   │   │   └── portal/
+│   │   │       ├── dashboard/
+│   │   │       ├── history/
+│   │   │       └── profile/
+│   │   └── api/auth/              # NextAuth route handler
+│   ├── components/
+│   │   ├── ui/                    # shadcn/ui components
+│   │   ├── portal/               # Portal-specific components
+│   │   └── auth/                 # Auth components
+│   ├── data/mock/                # Mock data (replace with API calls)
+│   ├── lib/auth.ts               # NextAuth configuration
+│   ├── hooks/                    # Custom React hooks
+│   └── types/                    # TypeScript interfaces
+├── messages/de.json              # German translations
+├── messages/en.json              # English translations
+├── e2e/                          # Playwright tests
+├── Dockerfile                    # Multi-stage production build
+└── docker-compose.yml            # Dev environment (in repo root)
+```
+
+---
+
+## ⏭️ What's Next (Sprint 5)
+
+1. Wire frontend to real backend API (replace mock data with fetch calls)
+2. Staff management UI (invite, permissions editor)
+3. DSGVO consent management
+4. WebSocket notifications (real-time quota updates)
+5. Full E2E test suite with backend running