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

// 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

cd web
npm install  # if not done
npm run dev  # starts on http://localhost:3000

2. Create Feature Branch

git checkout -b claude/feature-name-2025-11-18

3. Follow Git Workflow

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

const colors = {
  primary: '#3B82F6',     // Blue
  secondary: '#8B5CF6',   // Purple
  error: '#EF4444',       // Red
  success: '#10B981',     // Green
  warning: '#F59E0B',     // Amber
  text: '#111827',        // Dark
  background: '#FFFFFF',  // Light
}

Typography:

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:

// 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:

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

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

npm test  # Run tests (jest + React Testing Library)

E2E Tests (User Flows)

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

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)

# Push to main branch
git push origin main

# Vercel auto-deploys on main push
# Monitor at: https://vercel.com/morethanadiagnosis

Deploy to nexus-vector

# 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

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