diff --git a/.github/CLAUDE_WEB_AGENT_HANDOFF.md b/.github/CLAUDE_WEB_AGENT_HANDOFF.md new file mode 100644 index 0000000..ce14d81 --- /dev/null +++ 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 +