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**
   ```bash
   npm install
   ```

2. **Set up environment variables**
   ```bash
   cp .env.example .env.local
   # Edit .env.local with your configuration
   ```

3. **Start development server**
   ```bash
   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**:
```typescript
import { apiClient } from '@/lib/api'

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

See `lib/api.ts` for client configuration.

## 🧪 Testing

**Unit Tests** (TODO):
```bash
npm run test
```

**Build Check**:
```bash
npm run build
```

**Type Check**:
```bash
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
```bash
npm run build
```

### Start
```bash
npm start
```

### Docker
```bash
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`:
```bash
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

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