morethanadiagnosis-hub/.github/CLAUDE_WEB_AGENT_HANDOFF.md

# 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)