docs: comprehensive handoff for claude-agent web implementation

Complete handoff document for Next.js web frontend development: - Current state assessment (85% backend, 10% web) - Detailed implementation roadmap (5 phases, ~25-35 hours) - Phase breakdown: Foundation, Auth, MVPs, Dashboard, Polish - Complete API contract and endpoint reference - Design System integration guide - Accessibility requirements (WCAG 2.2 AA+) - Security checklist - Testing strategy - Success criteria - Deployment instructions - Development workflow - Estimated timeline Ready for claude-agent to begin Phase 1 implementation. Job ID: MTAD-IMPL-2025-11-18-CL 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-18 00:52:01 +00:00 · 2025-11-18 00:52:01 +00:00 · 646764c01a
commit 646764c01a
parent 053345dbcc
1 changed files with 707 additions and 0 deletions
--- a/.github/CLAUDE_WEB_AGENT_HANDOFF.md
+++ b/.github/CLAUDE_WEB_AGENT_HANDOFF.md
@ -0,0 +1,707 @@
+# Claude Web Agent Handoff
+
+**Job ID**: MTAD-IMPL-2025-11-18-CL
+**Date**: 2025-11-18
+**From**: Claude (Implementation Agent - Backend/Infrastructure)
+**To**: Claude Agent (Web Frontend Implementation)
+**Status**: Backend foundation 85% complete, Web ready for full implementation
+
+---
+
+## 🎯 Your Mission
+
+Implement the complete **Next.js 14 web frontend** for the MoreThanADiagnosis community platform with **all 7 MVPs** integrated and **production-ready** for deployment.
+
+---
+
+## 📊 Current State
+
+### What's Done ✅
+- **Backend**: 85% complete
+  - FastAPI application with 7 MVP endpoints
+  - SQLAlchemy ORM with 25 models
+  - Authentication endpoints (signup/login/refresh/logout)
+  - Alembic migrations (ready to run)
+  - Docker & Docker Compose configured
+  - Production deployment ready on nexus-vector
+
+- **Specifications**: 100% complete
+  - Architecture spec (openspec/specs/architecture.md)
+  - Data Model spec (openspec/specs/data-model.md)
+  - Authentication spec (openspec/specs/authentication.md)
+  - Design System spec (openspec/specs/design-system.md)
+  - All with WCAG 2.2 AA+ accessibility built-in
+
+- **Web Frontend**: 10% complete (scaffolding only)
+  - Next.js 14 project initialized
+  - TypeScript configured
+  - Tailwind CSS setup
+  - Package.json with dependencies
+  - README with structure overview
+  - Directory structure created
+
+### What's NOT Done ❌
+- **Web Frontend** (your job):
+  - No components implemented
+  - No pages/screens created
+  - No API integration (except client config)
+  - No authentication flow UI
+  - No MVP feature implementations
+  - No styling/theming applied
+  - No tests written
+  - Not deployed
+
+- **Mobile Frontend**:
+  - Only scaffolding done
+  - Available for future agent
+
+---
+
+## 🚀 What You Need to Implement
+
+### Phase 1: Foundation Components (20%)
+**Estimated**: 4-6 hours
+
+**Tasks**:
+1. Create Design System components in `/web/components/`
+   - Button (all variants)
+   - Input (all types)
+   - Card
+   - Modal/Dialog
+   - Form helpers
+   - Navigation components
+   - Avatar
+   - Badge
+
+2. Create layout components
+   - MainLayout (with Header/Footer/Nav)
+   - AuthLayout (minimal layout for login/signup)
+   - DashboardLayout (with sidebar)
+
+3. Set up styling
+   - Tailwind configuration finalized
+   - CSS variables for design tokens
+   - Dark mode support
+   - Responsive breakpoints
+
+4. Create utility hooks
+   - `useAuth()` - Authentication state
+   - `useApi()` - API calls with loading/error
+   - `useLocalStorage()` - Persistent state
+
+### Phase 2: Authentication Pages (15%)
+**Estimated**: 3-4 hours
+
+**Tasks**:
+1. `/app/(auth)/login/` page
+   - Email/password form
+   - "Remember me" checkbox
+   - Error handling
+   - Link to signup
+   - Link to password reset
+
+2. `/app/(auth)/signup/` page
+   - Email, password, display name form
+   - Terms acceptance
+   - Error validation
+   - Link to login
+
+3. `/app/(auth)/reset-password/` pages
+   - Request form (email)
+   - Confirmation form (token + new password)
+   - Success message
+
+4. Authentication context/store
+   - Token management (access + refresh)
+   - User state
+   - Logout flow
+
+### Phase 3: Core Feature Pages (50%)
+**Estimated**: 12-16 hours
+
+**For each MVP** (implement in parallel):
+
+#### Blog MVP
+- **Pages**:
+  - `/blog` - List view (infinite scroll)
+  - `/blog/[slug]` - Single post view
+  - `/blog/new` - Create post (if author)
+  - `/blog/[slug]/edit` - Edit post (if author)
+
+- **Components**:
+  - BlogCard
+  - BlogPost
+  - BlogSearch
+  - AuthorBio
+
+- **Features**:
+  - Markdown rendering
+  - Syntax highlighting for code
+  - Search/filter by category
+  - Author profile links
+
+#### Forum MVP
+- **Pages**:
+  - `/forum` - Category list
+  - `/forum/[categoryId]` - Thread list
+  - `/forum/[categoryId]/[threadId]` - Thread view
+  - `/forum/compose` - New thread/post
+
+- **Components**:
+  - ForumCategory
+  - ForumThread
+  - ForumPost
+  - PostReactions
+  - ComposerBox
+  - ReportModal
+
+- **Features**:
+  - Real-time reactions
+  - Nested replies
+  - Moderation reporting
+  - User reputation badges
+
+#### Merch MVP
+- **Pages**:
+  - `/merch` - Product catalog
+  - `/merch/[productId]` - Product details
+  - `/merch/cart` - Shopping cart
+  - `/merch/checkout` - Order form
+  - `/merch/orders` - Order history (authenticated)
+
+- **Components**:
+  - ProductCard
+  - ProductGallery
+  - CartSummary
+  - CheckoutForm
+  - OrderStatus
+
+- **Features**:
+  - Product search/filter
+  - Image gallery
+  - Quantity selector
+  - Order tracking
+
+#### Podcast MVP
+- **Pages**:
+  - `/podcast` - Episode list
+  - `/podcast/[episodeId]` - Episode details
+  - `/podcast/player` - Full player view
+
+- **Components**:
+  - AudioPlayer
+  - EpisodeCard
+  - EpisodeTranscript
+  - PlaylistQueue
+
+- **Features**:
+  - Audio playback
+  - Progress tracking
+  - Download option (future)
+  - Playlist management
+
+#### Profiles MVP
+- **Pages**:
+  - `/profiles` - Public profile list
+  - `/profiles/[userId]` - User profile
+  - `/dashboard/profile` - Edit own profile
+
+- **Components**:
+  - ProfileCard
+  - ProfileHeader
+  - ProfileEdit
+  - HealthJourneyDisplay
+  - PseudonymBadge
+
+- **Features**:
+  - Public/private profile sections
+  - Pseudonym display
+  - Health journey (optional sharing)
+  - Privacy-conscious design
+
+#### Resources MVP
+- **Pages**:
+  - `/resources` - Knowledge base
+  - `/resources/[slug]` - Single resource
+  - `/resources/search` - Advanced search
+
+- **Components**:
+  - ResourceCard
+  - ResourceContent
+  - TagFilter
+  - SearchBox
+  - TableOfContents
+
+- **Features**:
+  - Full-text search
+  - Tag-based filtering
+  - Access tier (public/members)
+  - Related resources
+
+#### Tribute MVP
+- **Pages**:
+  - `/tribute` - Tribute list
+  - `/tribute/[id]` - Single tribute
+  - `/tribute/new` - Create tribute (authenticated)
+
+- **Components**:
+  - TributeCard
+  - TributeContent
+  - TributeComposer
+  - MemorialLayout
+
+- **Features**:
+  - Respectful design
+  - Comment threads
+  - Share options
+  - Privacy controls
+
+### Phase 4: User Dashboard (10%)
+**Estimated**: 2-3 hours
+
+**Pages**:
+- `/dashboard` - Dashboard home
+- `/dashboard/profile` - Edit profile
+- `/dashboard/preferences` - Settings
+- `/dashboard/security` - Password/MFA
+- `/dashboard/privacy` - Privacy & consent
+
+**Features**:
+- User account management
+- Email verification
+- Password change
+- MFA setup
+- Privacy preferences
+
+### Phase 5: Integration & Polish (5%)
+**Estimated**: 2-3 hours
+
+**Tasks**:
+1. Error boundary and error pages
+2. Loading states and skeletons
+3. Empty states
+4. Notifications/toasts
+5. Accessibility audit (axe)
+6. Mobile responsive testing
+7. Performance optimization
+
+---
+
+## 📚 Essential Reading
+
+**Must Read First** (30 min):
+1. `/openspec/specs/design-system.md` - Component specs
+2. `/backend/README.md` - API contract
+3. `/web/README.md` - Project structure
+
+**Reference**:
+- `/openspec/specs/architecture.md` - System architecture
+- `/openspec/specs/authentication.md` - Auth flow
+- `/openspec/specs/data-model.md` - Data structure
+- `/.github/MVP_IMPLEMENTATION_HANDOFF.md` - Previous handoff
+
+---
+
+## 🔗 API Contract
+
+### Base URL
+- **Development**: `http://localhost:8000/api/v1`
+- **Production**: `https://morethanadiagnosis.com/api/v1`
+
+### Authentication
+```typescript
+// All protected requests include:
+Authorization: Bearer {access_token}
+
+// Token refresh:
+POST /auth/refresh
+{
+  "refresh_token": "..."
+}
+```
+
+### Key Endpoints
+
+**Authentication**:
+- `POST /auth/signup` - Register
+- `POST /auth/login` - Login
+- `POST /auth/refresh` - Refresh token
+- `POST /auth/logout` - Logout
+- `GET /auth/me` - Current user
+
+**Blog**:
+- `GET /blog?skip=0&limit=10` - List posts
+- `GET /blog/{id}` - Get post
+- `POST /blog` - Create (auth required)
+- `PUT /blog/{id}` - Update
+- `DELETE /blog/{id}` - Delete
+
+**Forum**:
+- `GET /forum/categories` - List categories
+- `GET /forum/categories/{id}/threads` - List threads
+- `GET /forum/threads/{id}/posts` - List posts
+- `POST /forum/threads` - Create thread (auth required)
+- `POST /forum/posts` - Create post (auth required)
+
+**Merch**:
+- `GET /merch/products` - List products
+- `GET /merch/products/{id}` - Get product
+- `POST /merch/orders` - Create order (auth required)
+- `GET /merch/orders/{id}` - Get order details
+
+**Podcast**:
+- `GET /podcast/episodes` - List episodes
+- `GET /podcast/episodes/{id}` - Get episode
+
+**Profiles**:
+- `GET /profiles` - List public profiles
+- `GET /profiles/{userId}` - Get profile
+- `PUT /profiles/{userId}` - Update (auth required)
+
+**Resources**:
+- `GET /resources?access_tier=public` - List resources
+- `GET /resources/{id}` - Get resource
+- `GET /resources/slug/{slug}` - Get by slug
+
+**Tribute**:
+- `GET /tribute` - List tributes
+- `GET /tribute/{id}` - Get tribute
+- `POST /tribute` - Create (auth required)
+
+See `/backend/README.md` for complete API documentation.
+
+---
+
+## 🛠 Tech Stack (Already Configured)
+
+```
+Frontend:
+├── Next.js 14 (App Router)
+├── TypeScript
+├── React 18
+├── Tailwind CSS
+├── Zustand (state)
+├── Axios + React Query (API)
+└── Prettier + ESLint (code quality)
+
+Browser Support:
+├── Chrome/Edge 90+
+├── Safari 15+
+├── Firefox 88+
+└── Mobile browsers (iOS Safari, Chrome Android)
+```
+
+---
+
+## 📋 Development Workflow
+
+### 1. Start Development
+```bash
+cd web
+npm install  # if not done
+npm run dev  # starts on http://localhost:3000
+```
+
+### 2. Create Feature Branch
+```bash
+git checkout -b claude/feature-name-2025-11-18
+```
+
+### 3. Follow Git Workflow
+```bash
+# Make changes
+git add .
+git commit -m "feat: description (JOB MTAD-IMPL-2025-11-18-CL)"
+
+# Push
+git push origin claude/feature-name-2025-11-18
+```
+
+### 4. Commit Message Format
+```
+feat(blog): implement blog post list component
+
+- Create BlogCard component
+- Implement infinite scroll
+- Add search filter
+- Ensure WCAG 2.2 AA+ compliance
+
+Job ID: MTAD-IMPL-2025-11-18-CL
+```
+
+---
+
+## 🎨 Design System Integration
+
+All components must follow the Design System spec:
+
+**Colors**:
+```typescript
+const colors = {
+  primary: '#3B82F6',     // Blue
+  secondary: '#8B5CF6',   // Purple
+  error: '#EF4444',       // Red
+  success: '#10B981',     // Green
+  warning: '#F59E0B',     // Amber
+  text: '#111827',        // Dark
+  background: '#FFFFFF',  // Light
+}
+```
+
+**Typography**:
+```typescript
+const typography = {
+  h1: 'text-4xl font-bold',
+  h2: 'text-3xl font-bold',
+  h3: 'text-2xl font-semibold',
+  body: 'text-base font-normal',
+  small: 'text-sm font-normal',
+}
+```
+
+**Spacing**:
+```typescript
+// 4px base unit
+// Use Tailwind: p-0, p-1 (4px), p-2 (8px), p-3 (12px), p-4 (16px), etc.
+```
+
+See `/openspec/specs/design-system.md` for complete specs.
+
+---
+
+## ♿ Accessibility Requirements
+
+**WCAG 2.2 AA+ Compliance**:
+- [ ] Semantic HTML (Button, Link, Form, etc.)
+- [ ] ARIA labels for interactive elements
+- [ ] Keyboard navigation (Tab, Enter, Escape)
+- [ ] Focus indicators visible
+- [ ] Color contrast ≥ 4.5:1 for text
+- [ ] Images have alt text
+- [ ] Form labels associated with inputs
+- [ ] Reduced motion respected
+
+**Testing**:
+```bash
+# Run accessibility audit
+npx axe-core --file web/app
+
+# Manual testing with screen reader
+# - Test with: NVDA (Windows), JAWS (Windows), VoiceOver (Mac)
+```
+
+---
+
+## 📱 Responsive Design
+
+**Breakpoints** (Tailwind defaults):
+- Mobile: 0-640px (sm)
+- Tablet: 641-768px (md)
+- Desktop: 769-1024px (lg)
+- Wide: 1025px+ (xl)
+
+**Pattern**:
+```typescript
+<div className="p-4 md:p-6 lg:p-8">
+  {/* Mobile first, then override for larger screens */}
+</div>
+```
+
+---
+
+## 🔐 Security Checklist
+
+- [ ] Never store tokens in localStorage
+- [ ] Use HttpOnly cookies for tokens (if backend supports)
+- [ ] HTTPS only in production
+- [ ] Validate all user input
+- [ ] Sanitize HTML content (use `dangerously-set-html` carefully)
+- [ ] CSRF protection (Next.js built-in)
+- [ ] Rate limiting on frontend (disable form while submitting)
+- [ ] Don't expose sensitive data in logs
+- [ ] Use environment variables for API URLs
+
+---
+
+## 🧪 Testing Strategy
+
+### Unit Tests (Components)
+```bash
+npm test  # Run tests (jest + React Testing Library)
+```
+
+### E2E Tests (User Flows)
+```bash
+npm run test:e2e  # Playwright tests (after setup)
+```
+
+### Manual Testing
+- [ ] Test on Chrome, Firefox, Safari
+- [ ] Test on iOS and Android
+- [ ] Test with screen reader (VoiceOver/TalkBack)
+- [ ] Test with keyboard only
+- [ ] Test in high contrast mode
+
+---
+
+## 📊 Success Criteria
+
+### MVP Complete = When ALL of:
+1. **All 7 MVPs fully implemented**
+   - Blog: create, read, search
+   - Forum: categories, threads, posts, reactions
+   - Merch: browse, cart, checkout
+   - Podcast: list, play, details
+   - Profiles: view, edit
+   - Resources: browse, search
+   - Tribute: view, create
+
+2. **Authentication working end-to-end**
+   - Signup → login → authenticated requests → logout
+
+3. **Design System implemented**
+   - All components use design system
+   - Consistent theming (light/dark modes)
+
+4. **Accessibility compliant**
+   - WCAG 2.2 AA+ verified
+   - Screen reader tested
+   - Keyboard navigation working
+
+5. **No console errors**
+   - Build succeeds: `npm run build`
+   - No type errors: `npm run type-check`
+   - No lint errors: `npm run lint`
+
+6. **Mobile responsive**
+   - Works on 320px (iPhone SE)
+   - Works on 1920px (desktop)
+
+7. **Performance acceptable**
+   - Lighthouse score ≥ 80
+   - Core Web Vitals met
+   - <3s initial load on 4G
+
+---
+
+## 🚀 Deployment
+
+### Testing Before Deploy
+```bash
+npm run build    # Check for build errors
+npm run type-check  # Check for type errors
+npm run lint     # Check for lint errors
+npm test         # Run tests
+```
+
+### Deploy to Vercel (Recommended)
+```bash
+# Push to main branch
+git push origin main
+
+# Vercel auto-deploys on main push
+# Monitor at: https://vercel.com/morethanadiagnosis
+```
+
+### Deploy to nexus-vector
+```bash
+# Create Docker image
+docker build -t mtad-web .
+
+# Run on nexus-vector
+docker run -p 3000:3000 mtad-web
+```
+
+---
+
+## 🆘 Support & Questions
+
+### If You Get Stuck:
+1. **Check the specs first**: `openspec/specs/`
+2. **Read existing code patterns**
+3. **Check Next.js docs**: https://nextjs.org
+4. **Check Tailwind docs**: https://tailwindcss.com
+5. **Search GitHub issues**
+
+### Known Limitations:
+- Backend auth needs database migrations run first
+- Backend may not be fully deployed yet
+- Some endpoints may return stub responses
+
+---
+
+## 📝 Git Commit Examples
+
+```bash
+# Good commits
+"feat(blog): implement blog post card component (JOB MTAD-IMPL-2025-11-18-CL)"
+"feat(forum): add category list with filtering (JOB MTAD-IMPL-2025-11-18-CL)"
+"fix(auth): correct token refresh logic (JOB MTAD-IMPL-2025-11-18-CL)"
+"test(components): add button component tests (JOB MTAD-IMPL-2025-11-18-CL)"
+
+# Bad commits
+"update stuff"
+"fix bug"
+"random changes"
+```
+
+---
+
+## 🎯 Estimated Timeline
+
+- **Phase 1** (Foundation): 4-6 hours
+- **Phase 2** (Auth): 3-4 hours
+- **Phase 3** (MVPs): 12-16 hours (can parallelize)
+- **Phase 4** (Dashboard): 2-3 hours
+- **Phase 5** (Polish): 2-3 hours
+
+**Total**: ~25-35 hours (3-4 days intensive work)
+
+---
+
+## ✅ Handoff Checklist
+
+Before you start:
+- [ ] Read all "Must Read" documents
+- [ ] Understand the API contract
+- [ ] Review the Design System spec
+- [ ] Test backend connectivity (if running)
+- [ ] Install dependencies: `cd web && npm install`
+- [ ] Start dev server: `npm run dev`
+- [ ] Verify everything loads
+
+---
+
+## 📞 Contact & Questions
+
+If you need clarification on:
+- **Specs**: Check `openspec/specs/` directory
+- **Backend API**: Read `/backend/README.md`
+- **Architecture**: Read `openspec/specs/architecture.md`
+- **Design System**: Read `openspec/specs/design-system.md`
+- **Auth Flow**: Read `openspec/specs/authentication.md`
+
+---
+
+## Version History
+
+| Date | From | To | Job ID | Status |
+|------|------|-----|--------|--------|
+| 2025-11-18 | Claude (Impl) | Claude (Web) | MTAD-IMPL-2025-11-18-CL | Ready for handoff |
+
+---
+
+**Status**: Backend foundation complete, Web frontend ready for implementation
+**Next Action**: Implement Phase 1 (foundation components)
+**Deadline**: Flexible, depends on complexity and priority
+**Deliverable**: Production-ready web app with all 7 MVPs
+
+---
+
+**Good luck! You've got this! 🚀**
+
+---
+
+**Location**: `/.github/CLAUDE_WEB_AGENT_HANDOFF.md`
+**Last Updated**: 2025-11-18
+**Maintained By**: Claude (Implementation Agent)