Add auto-generated API client and update authStore tests

- Integrated OpenAPI-generated TypeScript SDK (`sdk.gen.ts`, `types.gen.ts`, `client.gen.ts`) for API interactions. - Refactored `authStore` tests to include storage mock reset logic with default implementations.
2025-10-31 23:24:19 +01:00
parent b4866f9100
commit 31e2109278
19 changed files with 5383 additions and 11 deletions
--- a/frontend/IMPLEMENTATION_PLAN.md
+++ b/frontend/IMPLEMENTATION_PLAN.md
@@ -0,0 +1,839 @@
+# Frontend Implementation Plan: Next.js + FastAPI Template
+
+**Last Updated:** October 31, 2025
+**Current Phase:** Phase 1 COMPLETE ✅ | Ready for Phase 2
+**Overall Progress:** 1 of 12 phases complete
+
+---
+
+## Summary
+
+Build a production-ready Next.js 15 frontend with full authentication, admin dashboard, user/organization management, and session tracking. The frontend integrates with the existing FastAPI backend using OpenAPI-generated clients, TanStack Query for state, Zustand for auth, and shadcn/ui components.
+
+**Target:** 90%+ test coverage, comprehensive documentation, and robust foundations for enterprise projects.
+
+**Current State:** Phase 1 infrastructure complete with 81.6% test coverage, 66 passing tests, zero TypeScript errors
+**Target State:** Complete template matching `frontend-requirements.md` with all 12 phases
+
+---
+
+## Implementation Directives (MUST FOLLOW)
+
+### Documentation-First Approach
+- Phase 0 created `/docs` folder with all architecture, standards, and guides ✅
+- ALL subsequent phases MUST reference and follow patterns in `/docs`
+- **If context is lost, `/docs` + this file + `frontend-requirements.md` are sufficient to resume**
+
+### Quality Assurance Protocol
+
+**1. After Each Task:** Launch self-review to check:
+- Code quality issues
+- Security vulnerabilities
+- Performance problems
+- Accessibility issues
+- Standard violations (check against `/docs/CODING_STANDARDS.md`)
+
+**2. After Each Phase:** Launch multi-agent deep review to:
+- Verify phase objectives met
+- Check integration with previous phases
+- Identify critical issues requiring immediate fixes
+- Recommend improvements before proceeding
+- Update documentation if patterns evolved
+
+**3. Testing Requirements:**
+- Write tests alongside feature code (not after)
+- Unit tests: All hooks, utilities, services
+- Component tests: All reusable components
+- Integration tests: All pages and flows
+- E2E tests: Critical user journeys (auth, admin CRUD)
+- Target: 90%+ coverage for template robustness
+- Use Jest + React Testing Library + Playwright
+
+**4. Context Preservation:**
+- Update `/docs` with implementation decisions
+- Document deviations from requirements in `ARCHITECTURE.md`
+- Keep `frontend-requirements.md` updated if backend changes
+- Update THIS FILE after each phase with actual progress
+
+---
+
+## Current System State (Phase 1 Complete)
+
+### ✅ What's Implemented
+
+**Project Infrastructure:**
+- Next.js 15 with App Router
+- TypeScript strict mode enabled
+- Tailwind CSS 4 configured
+- shadcn/ui components installed (15+ components)
+- Path aliases configured (@/)
+
+**Authentication System:**
+- `src/lib/auth/crypto.ts` - AES-GCM encryption (82% coverage)
+- `src/lib/auth/storage.ts` - Secure token storage (72.85% coverage)
+- `src/stores/authStore.ts` - Zustand auth store (92.59% coverage)
+- `src/config/app.config.ts` - Centralized configuration (81% coverage)
+- SSR-safe implementations throughout
+
+**API Integration:**
+- `src/lib/api/client.ts` - Axios wrapper with interceptors (to be replaced)
+- `src/lib/api/errors.ts` - Error parsing utilities (to be replaced)
+- `scripts/generate-api-client.sh` - OpenAPI generation script
+- **NOTE:** Manual client files marked for replacement with generated client
+
+**Testing Infrastructure:**
+- Jest configured with Next.js integration
+- 66 tests passing (100%)
+- 81.6% code coverage (exceeds 70% target)
+- Real crypto testing (@peculiar/webcrypto)
+- No mocks for security-critical code
+
+**Documentation:**
+- `/docs/ARCHITECTURE.md` - System design ✅
+- `/docs/CODING_STANDARDS.md` - Code standards ✅
+- `/docs/COMPONENT_GUIDE.md` - Component patterns ✅
+- `/docs/FEATURE_EXAMPLES.md` - Implementation examples ✅
+- `/docs/API_INTEGRATION.md` - API integration guide ✅
+
+### 📊 Test Coverage Details
+
+```
+File            | Statements | Branches | Functions | Lines
+----------------|------------|----------|-----------|-------
+All files       | 81.60%     | 84.09%   | 93.10%    | 82.08%
+config          | 81.08%     | 81.25%   | 80.00%    | 84.37%
+lib/auth        | 76.85%     | 73.07%   | 92.30%    | 76.66%
+stores          | 92.59%     | 97.91%   | 100.00%   | 93.87%
+```
+
+**Coverage Exclusions (Properly Configured):**
+- Auto-generated API client (`src/lib/api/generated/**`)
+- Manual API client (to be replaced)
+- Third-party UI components (`src/components/ui/**`)
+- Next.js app directory (`src/app/**` - test with E2E)
+- Re-export index files
+- Old implementation files (`.old.ts`)
+
+### 🎯 Quality Metrics
+
+- ✅ TypeScript: 0 compilation errors
+- ✅ ESLint: 0 warnings
+- ✅ Tests: 66/66 passing
+- ✅ Coverage: 81.6% (target: 70%)
+- ✅ Security: No vulnerabilities
+- ✅ SSR: All browser APIs properly guarded
+
+### 📁 Current Folder Structure
+
+```
+frontend/
+├── docs/                              ✅ Phase 0 complete
+│   ├── ARCHITECTURE.md
+│   ├── CODING_STANDARDS.md
+│   ├── COMPONENT_GUIDE.md
+│   ├── FEATURE_EXAMPLES.md
+│   └── API_INTEGRATION.md
+├── src/
+│   ├── app/                           # Next.js app directory
+│   ├── components/
+│   │   └── ui/                        # shadcn/ui components ✅
+│   ├── lib/
+│   │   ├── api/
+│   │   │   ├── generated/             # OpenAPI client (empty, needs generation)
+│   │   │   ├── client.ts              # ✅ Axios wrapper (to replace)
+│   │   │   └── errors.ts              # ✅ Error parsing (to replace)
+│   │   ├── auth/
+│   │   │   ├── crypto.ts              # ✅ 82% coverage
+│   │   │   └── storage.ts             # ✅ 72.85% coverage
+│   │   └── utils/
+│   ├── stores/
+│   │   └── authStore.ts               # ✅ 92.59% coverage
+│   └── config/
+│       └── app.config.ts              # ✅ 81% coverage
+├── tests/                             # ✅ 66 tests
+│   ├── lib/auth/                      # Crypto & storage tests
+│   ├── stores/                        # Auth store tests
+│   └── config/                        # Config tests
+├── scripts/
+│   └── generate-api-client.sh         # ✅ OpenAPI generation
+├── jest.config.js                     # ✅ Configured
+├── jest.setup.js                      # ✅ Global mocks
+├── frontend-requirements.md           # ✅ Updated
+└── IMPLEMENTATION_PLAN.md             # ✅ This file
+
+```
+
+### ⚠️ Known Technical Debt
+
+1. **Manual API Client Files** - Need replacement when backend ready:
+   - Delete: `src/lib/api/client.ts`
+   - Delete: `src/lib/api/errors.ts`
+   - Run: `npm run generate:api`
+   - Create: Thin interceptor wrapper if needed
+
+2. **Old Implementation Files** - Need cleanup:
+   - Delete: `src/stores/authStore.old.ts`
+
+3. **API Client Generation** - Needs backend running:
+   - Backend must be at `http://localhost:8000`
+   - OpenAPI spec at `/api/v1/openapi.json`
+   - Run `npm run generate:api` to create client
+
+---
+
+## Phase 0: Foundation Documents & Requirements Alignment ✅
+
+**Status:** COMPLETE
+**Duration:** 1 day
+**Completed:** October 31, 2025
+
+### Task 0.1: Update Requirements Document ✅
+- ✅ Updated `frontend-requirements.md` with API corrections
+- ✅ Added Section 4.5 (Session Management UI)
+- ✅ Added Section 15 (API Endpoint Reference)
+- ✅ Updated auth flow with token rotation details
+- ✅ Added missing User/Organization model fields
+
+### Task 0.2: Create Architecture Documentation ✅
+- ✅ Created `docs/ARCHITECTURE.md`
+- ✅ System overview (Next.js App Router, TanStack Query, Zustand)
+- ✅ Technology stack rationale
+- ✅ Data flow diagrams
+- ✅ Folder structure explanation
+- ✅ Design patterns documented
+
+### Task 0.3: Create Coding Standards Documentation ✅
+- ✅ Created `docs/CODING_STANDARDS.md`
+- ✅ TypeScript standards (strict mode, no any)
+- ✅ React component patterns
+- ✅ Naming conventions
+- ✅ State management rules
+- ✅ Form patterns
+- ✅ Error handling patterns
+- ✅ Testing standards
+
+### Task 0.4: Create Component & Feature Guides ✅
+- ✅ Created `docs/COMPONENT_GUIDE.md`
+- ✅ Created `docs/FEATURE_EXAMPLES.md`
+- ✅ Created `docs/API_INTEGRATION.md`
+- ✅ Complete walkthroughs for common patterns
+
+**Phase 0 Review:** ✅ All docs complete, clear, and accurate
+
+---
+
+## Phase 1: Project Setup & Infrastructure ✅
+
+**Status:** COMPLETE
+**Duration:** 3 days
+**Completed:** October 31, 2025
+
+### Task 1.1: Dependency Installation & Configuration ✅
+**Status:** COMPLETE
+**Blockers:** None
+
+**Installed Dependencies:**
+```bash
+# Core
+@tanstack/react-query@5, zustand@4, axios@1
+@hey-api/openapi-ts (dev)
+react-hook-form@7, zod@3, @hookform/resolvers
+date-fns, clsx, tailwind-merge, lucide-react
+recharts@2
+
+# shadcn/ui
+npx shadcn@latest init
+npx shadcn@latest add button card input label form select table dialog
+  toast tabs dropdown-menu popover sheet avatar badge separator skeleton alert
+
+# Testing
+jest, @testing-library/react, @testing-library/jest-dom
+@testing-library/user-event, @playwright/test, @types/jest
+@peculiar/webcrypto (for real crypto in tests)
+```
+
+**Configuration:**
+- ✅ `components.json` for shadcn/ui
+- ✅ `tsconfig.json` with path aliases
+- ✅ Tailwind configured for dark mode
+- ✅ `.env.example` and `.env.local` created
+- ✅ `jest.config.js` with Next.js integration
+- ✅ `jest.setup.js` with global mocks
+
+### Task 1.2: OpenAPI Client Generation Setup ✅
+**Status:** COMPLETE
+**Can run parallel with:** 1.3, 1.4
+
+**Completed:**
+- ✅ Created `scripts/generate-api-client.sh` using `@hey-api/openapi-ts`
+- ✅ Configured output to `src/lib/api/generated/`
+- ✅ Added npm script: `"generate:api": "./scripts/generate-api-client.sh"`
+- ✅ Fixed deprecated options (removed `--name`, `--useOptions`, `--exportSchemas`)
+- ✅ Used modern syntax: `--client @hey-api/client-axios`
+- ✅ Successfully generated TypeScript client from backend API
+- ✅ TypeScript compilation passes with generated types
+
+**Generated Files:**
+- `src/lib/api/generated/index.ts` - Main exports
+- `src/lib/api/generated/types.gen.ts` - TypeScript types (35KB)
+- `src/lib/api/generated/sdk.gen.ts` - API functions (29KB)
+- `src/lib/api/generated/client.gen.ts` - Axios client
+- `src/lib/api/generated/client/` - Client utilities
+- `src/lib/api/generated/core/` - Core utilities
+
+**To Regenerate (When Backend Changes):**
+```bash
+npm run generate:api
+```
+
+### Task 1.3: Axios Client & Interceptors ✅
+**Status:** COMPLETE (needs replacement in Phase 2)
+**Can run parallel with:** 1.2, 1.4
+
+**Completed:**
+- ✅ Created `src/lib/api/client.ts` - Axios wrapper
+  - Request interceptor: Add Authorization header
+  - Response interceptor: Handle 401, 403, 429, 500
+  - Error response parser
+  - Timeout configuration (30s default)
+  - Development logging
+- ✅ Created `src/lib/api/errors.ts` - Error types and parsing
+- ✅ Tests written for error parsing
+
+**⚠️ Note:** This is a manual implementation. Will be replaced with generated client + thin interceptor wrapper once backend API is generated.
+
+### Task 1.4: Folder Structure Creation ✅
+**Status:** COMPLETE
+**Can run parallel with:** 1.2, 1.3
+
+**Completed:**
+- ✅ All directories created per requirements
+- ✅ Placeholder index.ts files for exports
+- ✅ Structure matches `docs/ARCHITECTURE.md`
+
+### Task 1.5: Authentication Core Implementation ✅
+**Status:** COMPLETE (additional work beyond original plan)
+
+**Completed:**
+- ✅ `src/lib/auth/crypto.ts` - AES-GCM encryption with random IVs
+- ✅ `src/lib/auth/storage.ts` - Encrypted token storage with localStorage
+- ✅ `src/stores/authStore.ts` - Complete Zustand auth store
+- ✅ `src/config/app.config.ts` - Centralized configuration with validation
+- ✅ All SSR-safe with proper browser API guards
+- ✅ 66 comprehensive tests written (81.6% coverage)
+- ✅ Security audit completed
+- ✅ Real crypto testing (no mocks)
+
+**Security Features:**
+- AES-GCM encryption with 256-bit keys
+- Random IV per encryption
+- Key stored in sessionStorage (per-session)
+- Token validation (JWT format checking)
+- Type-safe throughout
+- No token leaks in logs
+
+**Phase 1 Review:** ✅ Multi-agent audit completed. Infrastructure solid. All tests passing. Ready for Phase 2.
+
+### Audit Results (October 31, 2025)
+
+**Comprehensive audit conducted with the following results:**
+
+**Critical Issues Found:** 5
+**Critical Issues Fixed:** 5 ✅
+
+**Issues Resolved:**
+1. ✅ TypeScript compilation error (unused @ts-expect-error)
+2. ✅ Duplicate configuration files
+3. ✅ Test mocks didn't match real implementation
+4. ✅ Test coverage properly configured
+5. ✅ API client exclusions documented
+
+**Final Metrics:**
+- Tests: 66/66 passing (100%)
+- Coverage: 81.6% (exceeds 70% target)
+- TypeScript: 0 errors
+- Security: No vulnerabilities
+
+**Audit Documents:**
+- `/tmp/AUDIT_SUMMARY.txt` - Executive summary
+- `/tmp/AUDIT_COMPLETE.md` - Full report
+- `/tmp/COVERAGE_CONFIG.md` - Coverage configuration
+- `/tmp/detailed_findings.md` - Issue details
+
+---
+
+## Phase 2: Authentication System
+
+**Status:** READY TO START 📋
+**Duration:** 3-4 days
+**Prerequisites:** Phase 1 complete ✅
+
+**Context for Phase 2:**
+Phase 1 already implemented core authentication infrastructure (crypto, storage, auth store). Phase 2 will build the UI layer on top of this foundation.
+
+### Task 2.1: Token Storage & Auth Store ✅ (Done in Phase 1)
+**Status:** COMPLETE (already done)
+
+This was completed as part of Phase 1 infrastructure:
+- ✅ `src/lib/auth/crypto.ts` - AES-GCM encryption
+- ✅ `src/lib/auth/storage.ts` - Token storage utilities
+- ✅ `src/stores/authStore.ts` - Complete Zustand store
+- ✅ 92.59% test coverage on auth store
+- ✅ Security audit passed
+
+**Skip this task - move to 2.2**
+
+### Task 2.2: Auth Interceptor Integration 🔗
+**Status:** PARTIALLY COMPLETE (needs update)
+**Depends on:** 2.1 ✅ (already complete)
+
+**Current State:**
+- `src/lib/api/client.ts` exists with basic interceptor logic
+- Integrates with auth store
+- Has token refresh flow
+- Has retry mechanism
+
+**Actions Needed:**
+- [ ] Test with generated API client (once backend ready)
+- [ ] Verify token rotation works
+- [ ] Add race condition testing
+- [ ] Verify no infinite refresh loops
+
+**Reference:** `docs/API_INTEGRATION.md`, Requirements Section 5.2
+
+### Task 2.3: Auth Hooks & Components 🔐
+**Status:** TODO 📋
+**Can run parallel with:** 2.4, 2.5 after 2.2 complete
+
+**Actions Needed:**
+
+Create React Query hooks in `src/lib/api/hooks/useAuth.ts`:
+- [ ] `useLogin` - Login mutation
+- [ ] `useRegister` - Register mutation
+- [ ] `useLogout` - Logout mutation
+- [ ] `useLogoutAll` - Logout all devices
+- [ ] `useRefreshToken` - Token refresh
+- [ ] `useMe` - Get current user
+
+Create convenience hooks in `src/hooks/useAuth.ts`:
+- [ ] Wrapper around auth store for easy component access
+
+Create auth protection components:
+- [ ] `src/components/auth/AuthGuard.tsx` - HOC for route protection
+- [ ] `src/components/auth/ProtectedRoute.tsx` - Client component wrapper
+
+**Testing:**
+- [ ] Unit tests for each hook
+- [ ] Test loading states
+- [ ] Test error handling
+- [ ] Test redirect logic
+
+**Reference:** `docs/FEATURE_EXAMPLES.md` (auth patterns), Requirements Section 4.3
+
+### Task 2.4: Login & Registration Pages 📄
+**Status:** TODO 📋
+**Can run parallel with:** 2.3, 2.5 after 2.2 complete
+
+**Actions Needed:**
+
+Create forms with validation:
+- [ ] `src/components/auth/LoginForm.tsx`
+  - Email + password fields
+  - react-hook-form + zod validation
+  - Loading states
+  - Error display
+  - Remember me checkbox (optional)
+- [ ] `src/components/auth/RegisterForm.tsx`
+  - Email, password, first_name, last_name
+  - Password confirmation field
+  - Password strength indicator
+  - Validation matching backend rules:
+    - Min 8 chars
+    - 1 digit
+    - 1 uppercase letter
+
+Create pages:
+- [ ] `src/app/(auth)/layout.tsx` - Centered form layout
+- [ ] `src/app/(auth)/login/page.tsx` - Login page
+- [ ] `src/app/(auth)/register/page.tsx` - Registration page
+
+**API Endpoints:**
+- POST `/api/v1/auth/register` - Register new user
+- POST `/api/v1/auth/login` - Authenticate user
+
+**Testing:**
+- [ ] Form validation tests
+- [ ] Submission success/error
+- [ ] E2E login flow
+- [ ] E2E registration flow
+- [ ] Accessibility (keyboard nav, screen reader)
+
+**Reference:** `docs/COMPONENT_GUIDE.md` (form patterns), Requirements Section 8.1
+
+### Task 2.5: Password Reset Flow 🔑
+**Status:** TODO 📋
+**Can run parallel with:** 2.3, 2.4 after 2.2 complete
+
+**Actions Needed:**
+
+Create password reset pages:
+- [ ] `src/app/(auth)/password-reset/page.tsx` - Request reset
+- [ ] `src/app/(auth)/password-reset/confirm/page.tsx` - Confirm reset with token
+
+Create forms:
+- [ ] `src/components/auth/PasswordResetForm.tsx` - Email input form
+- [ ] `src/components/auth/PasswordResetConfirmForm.tsx` - New password form
+
+**Flow:**
+1. User enters email → POST `/api/v1/auth/password-reset/request`
+2. User receives email with token link
+3. User clicks link → Opens confirm page with token in URL
+4. User enters new password → POST `/api/v1/auth/password-reset/confirm`
+
+**API Endpoints:**
+- POST `/api/v1/auth/password-reset/request` - Request reset email
+- POST `/api/v1/auth/password-reset/confirm` - Reset with token
+
+**Testing:**
+- [ ] Request form validation
+- [ ] Email sent confirmation message
+- [ ] Token validation
+- [ ] Password update success
+- [ ] Expired token handling
+- [ ] E2E password reset flow
+
+**Security Considerations:**
+- [ ] Email enumeration protection (always show success)
+- [ ] Token expiry handling
+- [ ] Single-use tokens
+
+**Reference:** Requirements Section 4.3, `docs/FEATURE_EXAMPLES.md`
+
+### Phase 2 Review Checklist
+
+When Phase 2 is complete, verify:
+- [ ] All auth pages functional
+- [ ] Forms have proper validation
+- [ ] Error messages are user-friendly
+- [ ] Loading states on all async operations
+- [ ] E2E tests for full auth flows pass
+- [ ] Security audit completed
+- [ ] Accessibility audit completed
+- [ ] No console errors
+- [ ] Works in mobile viewport
+- [ ] Dark mode works on all pages
+
+**Before proceeding to Phase 3:**
+- [ ] Run multi-agent review
+- [ ] Security audit of auth implementation
+- [ ] E2E test full auth flows
+- [ ] Update this plan with actual progress
+
+---
+
+## Phase 3: User Profile & Settings
+
+**Status:** TODO 📋
+**Duration:** 3-4 days
+**Prerequisites:** Phase 2 complete
+
+**Detailed tasks will be added here after Phase 2 is complete.**
+
+**High-level Overview:**
+- Authenticated layout with navigation
+- User profile management
+- Password change
+- Session management UI
+- User preferences (optional)
+
+---
+
+## Phase 4-12: Future Phases
+
+**Status:** TODO 📋
+
+**Remaining Phases:**
+- **Phase 4:** Base Component Library & Layout
+- **Phase 5:** Admin Dashboard Foundation
+- **Phase 6:** User Management (Admin)
+- **Phase 7:** Organization Management (Admin)
+- **Phase 8:** Charts & Analytics
+- **Phase 9:** Testing & Quality Assurance
+- **Phase 10:** Documentation & Dev Tools
+- **Phase 11:** Production Readiness & Optimization
+- **Phase 12:** Final Integration & Handoff
+
+**Note:** These phases will be detailed in this document as we progress through each phase. Context from completed phases will inform the implementation of future phases.
+
+---
+
+## Progress Tracking
+
+### Overall Progress Dashboard
+
+| Phase | Status | Started | Completed | Duration | Key Deliverables |
+|-------|--------|---------|-----------|----------|------------------|
+| 0: Foundation Docs | ✅ Complete | Oct 29 | Oct 29 | 1 day | 5 documentation files |
+| 1: Infrastructure | ✅ Complete | Oct 29 | Oct 31 | 3 days | Setup + auth core + tests |
+| 2: Auth System | 📋 TODO | - | - | 3-4 days | Login, register, reset flows |
+| 3: User Settings | 📋 TODO | - | - | 3-4 days | Profile, password, sessions |
+| 4: Component Library | 📋 TODO | - | - | 2-3 days | Common components |
+| 5: Admin Foundation | 📋 TODO | - | - | 2-3 days | Admin layout, navigation |
+| 6: User Management | 📋 TODO | - | - | 4-5 days | Admin user CRUD |
+| 7: Org Management | 📋 TODO | - | - | 4-5 days | Admin org CRUD |
+| 8: Charts | 📋 TODO | - | - | 2-3 days | Dashboard analytics |
+| 9: Testing | 📋 TODO | - | - | 3-4 days | Comprehensive test suite |
+| 10: Documentation | 📋 TODO | - | - | 2-3 days | Final docs |
+| 11: Production Prep | 📋 TODO | - | - | 2-3 days | Performance, security |
+| 12: Handoff | 📋 TODO | - | - | 1-2 days | Final validation |
+
+**Current:** Phase 1 Complete, Ready for Phase 2
+**Next:** Start Phase 2 - Authentication System UI
+
+### Task Status Legend
+- ✅ **Complete** - Finished and reviewed
+- ⚙ **In Progress** - Currently being worked on
+- 📋 **TODO** - Not started
+- ❌ **Blocked** - Cannot proceed due to dependencies
+- 🔗 **Depends on** - Waiting for specific task
+
+---
+
+## Critical Path & Dependencies
+
+### Sequential Dependencies (Must Complete in Order)
+
+1. **Phase 0** → Phase 1 (Foundation docs must exist before setup)
+2. **Phase 1** → Phase 2 (Infrastructure needed for auth UI)
+3. **Phase 2** → Phase 3 (Auth system needed for user features)
+4. **Phase 1-4** → Phase 5 (Base components needed for admin)
+5. **Phase 5** → Phase 6, 7 (Admin layout needed for CRUD)
+
+### Parallelization Opportunities
+
+**Within Phase 2 (After Task 2.2):**
+- Tasks 2.3, 2.4, 2.5 can run in parallel (3 agents)
+
+**Within Phase 3 (After Task 3.1):**
+- Tasks 3.2, 3.3, 3.4, 3.5 can run in parallel (4 agents)
+
+**Within Phase 4:**
+- All tasks 4.1, 4.2, 4.3 can run in parallel (3 agents)
+
+**Within Phase 5 (After Task 5.1):**
+- Tasks 5.2, 5.3, 5.4 can run in parallel (3 agents)
+
+**Phase 9 (Testing):**
+- All testing tasks can run in parallel (4 agents)
+
+**Estimated Timeline:**
+- **With 4 parallel agents:** 8-10 weeks
+- **With 2 parallel agents:** 12-14 weeks
+- **With 1 agent (sequential):** 18-20 weeks
+
+---
+
+## Success Criteria
+
+### Template is Production-Ready When:
+
+1. ✅ All 12 phases complete
+2. ✅ Test coverage ≥90% (unit + component + integration)
+3. ✅ All E2E tests passing
+4. ✅ Lighthouse scores:
+   - Performance >90
+   - Accessibility 100
+   - Best Practices >90
+5. ✅ WCAG 2.1 Level AA compliance verified
+6. ✅ No high/critical security vulnerabilities
+7. ✅ All documentation complete and accurate
+8. ✅ Production deployment successful
+9. ✅ Frontend-backend integration verified
+10. ✅ Template can be extended by new developer using docs alone
+
+### Per-Phase Success Criteria
+
+**Each phase must meet these before proceeding:**
+- [ ] All tasks complete
+- [ ] Tests written and passing
+- [ ] Code reviewed (self + multi-agent)
+- [ ] Documentation updated
+- [ ] No regressions in previous functionality
+- [ ] This plan updated with actual progress
+
+---
+
+## Critical Context for Resuming Work
+
+### If Conversation is Interrupted
+
+**To Resume Work, Read These Files in Order:**
+
+1. **THIS FILE** - `IMPLEMENTATION_PLAN.md`
+   - Current phase and progress
+   - What's been completed
+   - What's next
+
+2. **`frontend-requirements.md`**
+   - Complete feature requirements
+   - API endpoint reference
+   - User model details
+
+3. **`docs/ARCHITECTURE.md`**
+   - System design
+   - Technology stack
+   - Data flow patterns
+
+4. **`docs/CODING_STANDARDS.md`**
+   - Code style rules
+   - Testing standards
+   - Best practices
+
+5. **`docs/FEATURE_EXAMPLES.md`**
+   - Implementation patterns
+   - Code examples
+   - Common pitfalls
+
+### Key Commands Reference
+
+```bash
+# Development
+npm run dev                  # Start dev server (http://localhost:3000)
+npm run build                # Production build
+npm run start                # Start production server
+
+# Testing
+npm test                     # Run tests
+npm test -- --coverage       # Run tests with coverage report
+npm run type-check           # TypeScript compilation check
+npm run lint                 # ESLint check
+
+# API Client Generation (needs backend running)
+npm run generate:api         # Generate TypeScript client from OpenAPI spec
+
+# Package Management
+npm install                  # Install dependencies
+npm audit                    # Check for vulnerabilities
+```
+
+### Environment Variables
+
+**Required:**
+```env
+NEXT_PUBLIC_API_URL=http://localhost:8000
+NEXT_PUBLIC_APP_NAME=Template Project
+```
+
+**Optional:**
+```env
+NEXT_PUBLIC_API_TIMEOUT=30000
+NEXT_PUBLIC_TOKEN_REFRESH_THRESHOLD=300000
+NEXT_PUBLIC_DEBUG_API=false
+```
+
+See `.env.example` for complete list.
+
+### Current Technical State
+
+**What Works:**
+- ✅ Authentication core (crypto, storage, store)
+- ✅ Configuration management
+- ✅ Test infrastructure
+- ✅ TypeScript compilation
+- ✅ Development environment
+
+**What's Needed Next:**
+- [ ] Generate API client from backend
+- [ ] Build auth UI (login, register, password reset)
+- [ ] Implement auth pages
+- [ ] Add E2E tests for auth flows
+
+**Technical Debt:**
+- Manual API client files (will be replaced)
+- Old implementation files (need cleanup)
+- No API generation yet (needs backend)
+
+---
+
+## References
+
+### Always Reference During Implementation
+
+**Primary Documents:**
+- `IMPLEMENTATION_PLAN.md` (this file) - Implementation roadmap
+- `frontend-requirements.md` - Detailed requirements
+- `docs/ARCHITECTURE.md` - System design and patterns
+- `docs/CODING_STANDARDS.md` - Code style and standards
+- `docs/COMPONENT_GUIDE.md` - Component usage
+- `docs/FEATURE_EXAMPLES.md` - Implementation examples
+- `docs/API_INTEGRATION.md` - Backend API integration
+
+**Backend References:**
+- `../backend/docs/ARCHITECTURE.md` - Backend patterns to mirror
+- `../backend/docs/CODING_STANDARDS.md` - Backend conventions
+- Backend OpenAPI spec: `http://localhost:8000/api/v1/openapi.json`
+
+**Testing References:**
+- `jest.config.js` - Test configuration
+- `jest.setup.js` - Global test setup
+- `tests/` directory - Existing test patterns
+
+### Audit & Quality Reports
+
+**Available in `/tmp/`:**
+- `AUDIT_SUMMARY.txt` - Quick reference
+- `AUDIT_COMPLETE.md` - Full audit results
+- `COVERAGE_CONFIG.md` - Coverage explanation
+- `detailed_findings.md` - Issue analysis
+
+---
+
+## Version History
+
+| Version | Date | Changes | Author |
+|---------|------|---------|--------|
+| 1.0 | Oct 29, 2025 | Initial plan created | Claude |
+| 1.1 | Oct 31, 2025 | Phase 0 complete, updated structure | Claude |
+| 1.2 | Oct 31, 2025 | Phase 1 complete, comprehensive audit | Claude |
+| 1.3 | Oct 31, 2025 | **Major Update:** Reformatted as self-contained document | Claude |
+
+---
+
+## Notes for Future Development
+
+### When Starting Phase 2
+
+1. Generate API client first:
+   ```bash
+   # Ensure backend is running
+   cd ../backend && uvicorn app.main:app --reload
+
+   # In separate terminal
+   cd frontend
+   npm run generate:api
+   ```
+
+2. Review generated types in `src/lib/api/generated/`
+
+3. Replace manual client files:
+   - Archive or delete `src/lib/api/client.ts`
+   - Archive or delete `src/lib/api/errors.ts`
+   - Create thin wrapper if interceptor logic needed
+
+4. Follow patterns in `docs/FEATURE_EXAMPLES.md`
+
+5. Write tests alongside code (not after)
+
+### Remember
+
+- **Documentation First:** Check docs before implementing
+- **Test As You Go:** Don't batch testing at end
+- **Review Often:** Self-review after each task
+- **Update This Plan:** Keep it current with actual progress
+- **Context Matters:** This file + docs = full context
+
+---
+
+**Last Updated:** October 31, 2025
+**Next Review:** After Phase 2 completion
+**Contact:** Update this section with team contact info