# 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