cannamanage/docs/sprint-4/cannamanage-sprint4-walkthrough.md

CannaManage Frontend — Walkthrough

Sprint 4 Delivery | 2026-06-12 | Commit: fe6e96d

---

🚀 How to Run

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:

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

# 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