morethanadiagnosis-hub/web/README.md

MoreThanADiagnosis Web Platform

Next.js 14 web frontend for the MoreThanADiagnosis community platform.

Job ID: MTAD-IMPL-2025-11-18-CL

🏗 Technology Stack

• Framework: Next.js 14+ (App Router)
• Language: TypeScript
• Styling: Tailwind CSS
• State Management: Zustand
• API Client: Axios + React Query
• Package Manager: npm

📦 Project Structure

web/
├── app/                          # Next.js App Router
│   ├── layout.tsx               # Root layout
│   ├── page.tsx                 # Home page
│   ├── auth/                    # Authentication pages
│   │   ├── login/
│   │   ├── signup/
│   │   └── reset-password/
│   ├── blog/                    # Blog pages
│   ├── forum/                   # Forum pages
│   ├── merch/                   # Merch store pages
│   ├── podcast/                 # Podcast pages
│   ├── profiles/                # User profiles
│   ├── resources/               # Resources knowledge base
│   ├── tribute/                 # Tributes/memorials
│   └── dashboard/               # User dashboard
├── components/
│   ├── common/                  # Shared components
│   │   ├── Header.tsx
│   │   ├── Footer.tsx
│   │   ├── Navigation.tsx
│   │   └── Button.tsx
│   ├── layouts/                 # Layout components
│   │   ├── MainLayout.tsx
│   │   └── AuthLayout.tsx
│   └── mvps/                    # MVP-specific components
│       ├── blog/
│       ├── forum/
│       ├── merch/
│       ├── podcast/
│       ├── profiles/
│       ├── resources/
│       └── tribute/
├── lib/
│   ├── api.ts                   # API client configuration
│   ├── auth.ts                  # Authentication utilities
│   ├── hooks.ts                 # Custom React hooks
│   ├── store.ts                 # Zustand store
│   └── types.ts                 # TypeScript types
├── styles/
│   ├── globals.css              # Global styles
│   └── variables.css            # CSS variables
├── public/                      # Static files
├── package.json
├── next.config.js
├── tsconfig.json
└── README.md (this file)

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm 8+

Installation

1. Install dependencies

   npm install
   

2. Set up environment variables

   cp .env.example .env.local
   # Edit .env.local with your configuration
   

3. Start development server

   npm run dev
   

4. Open browser

   http://localhost:3000
   

📝 Environment Variables

Create .env.local:

NEXT_PUBLIC_API_BASE_URL=http://localhost:8000/api/v1
NEXT_PUBLIC_APP_URL=http://localhost:3000

🎨 Design System

The web frontend integrates with the MoreThanADiagnosis Design System (../../openspec/specs/design-system.md).

Available Components:

• Button (variants: primary, secondary, ghost, danger)
• Input (text, email, password, textarea)
• Card
• Modal/Dialog
• Form helpers
• Navigation components

See Design System spec for complete documentation.

🔐 Authentication

All protected routes require authentication via JWT tokens.

Authentication Flow:

1. User registers/logs in on /auth/login
2. Backend returns access_token and refresh_token
3. Frontend stores tokens in secure storage
4. API requests include Authorization: Bearer {access_token}
5. Token refresh handled automatically

See lib/auth.ts for implementation.

📱 Features (MVPs)

1. Blog

• List and search published posts
• Read full articles
• Filter by author/category
• Responsive design

2. Forum

• Browse categories and threads
• Read discussions
• View user profiles
• Real-time updates (WebSocket)

3. Merch Store

• Browse products
• View details and pricing
• Shopping cart management
• Checkout flow

4. Podcast

• Episode list with playback
• Audio player
• Episode notes and metadata
• Subscribe/download

5. Profiles

• View user profiles
• Edit own profile
• Display pseudonym/health journey
• Privacy-conscious design

6. Resources

• Browse knowledge base
• Search by tags/topics
• Filter by access tier
• Related resources

7. Tribute

• View memorials
• Create tribute entries
• Share memories
• Respectful layout

🔄 API Integration

The frontend communicates with the FastAPI backend at /api/v1/.

Example API Call:

import { apiClient } from '@/lib/api'

const blogPosts = await apiClient.get('/blog')

See lib/api.ts for client configuration.

🧪 Testing

Unit Tests (TODO):

npm run test

Build Check:

npm run build

Type Check:

npm run type-check

📊 Performance

• Static generation for blog/resources
• ISR (Incremental Static Regeneration) for frequently updated content
• Image optimization with Next.js Image component
• Code splitting per route
• CSS-in-JS optimization

🚀 Production Deployment

Build

npm run build

Start

npm start

Docker

docker build -t mtad-web .
docker run -p 3000:3000 mtad-web

🔍 Accessibility (WCAG 2.2 AA+)

• Semantic HTML
• ARIA labels and roles
• Keyboard navigation
• Screen reader support
• Color contrast compliance
• Focus management
• Reduced motion support

📚 Documentation

• Design System: ../../openspec/specs/design-system.md
• API Spec: ../../backend/README.md
• Architecture: ../../openspec/specs/architecture.md

🛠 Troubleshooting

API Connection Issues

1. Ensure backend is running on localhost:8000
2. Check CORS configuration in backend
3. Verify NEXT_PUBLIC_API_BASE_URL environment variable

Build Errors

1. Clear .next directory
2. Reinstall dependencies: npm install
3. Check TypeScript errors: npm run type-check

Port Conflicts

Change port in package.json:

npm run dev -- -p 3001

🤝 Contributing

1. Follow OpenSpec lifecycle for feature changes
2. Create feature branches: claude/feature-name-date
3. Link commits to Job IDs
4. Ensure accessibility compliance
5. Add tests for new features

📝 Git Workflow

# Create feature branch
git checkout -b claude/feature-name-2025-11-18

# Make changes, commit with Job ID
git commit -m "feat: description (JOB MTAD-IMPL-2025-11-18-CL)"

# Push and create PR
git push origin claude/feature-name-2025-11-18

Status

• ✅ Project scaffolding complete
• ⏳ Component development (in progress)
• ⏳ Feature page implementation (pending)
• ⏳ Integration testing (pending)
• ⏳ Production deployment (pending)

---

Job ID: MTAD-IMPL-2025-11-18-CL Last Updated: 2025-11-18 Maintained By: Claude (Frontend Agent)