morethanadiagnosis-hub/backend/FRONTEND_HANDOFF.md

# Frontend Development Handoff - MoreThanADiagnosis Hub

**Date**: 2025-11-18
**Job ID**: MTAD-IMPL-2025-11-18-CL
**Status**: Backend API deployment complete → Frontend needs fixes and deployment
**Target**: Claude-Web Agent (GitHub access)

---

## Current Status

✅ **Backend API is fully operational and deployed** to `https://mtd.runfoo.run`
⚠️ **Frontend codebase exists but has build issues**
❌ **Frontend not yet deployed** - Root path `/` currently returns 404

---

## Critical Issues to Fix

The frontend code exists in `/web` directory but has **build-time errors** that prevent deployment:

### 1. TypeScript Type Errors
- **File**: `components/common/Header.tsx` (multiple locations)
- **Issue**: `onClick` prop passed to `Link` component, but Link props don't accept `onClick`
- **Solution**: Wrap Link in a `<div>` with the `onClick` handler, OR use next/link `onClick` callback pattern
- **Affected lines**: 138, 150, 182 (mobile menu navigation)

### 2. Checkbox Label Type Error
- **File**: `app/(auth)/signup/page.tsx:159`
- **Issue**: `label` prop expects `string` but JSX Element (`<span>` with links) is passed
- **Solution**: Either:
  - Use string label and style separately, OR
  - Create custom checkbox component that accepts JSX labels

### 3. useSearchParams() Without Suspense
- **File**: `app/(auth)/reset-password/confirm/page.tsx:11-12`
- **Issue**: 'use client' component uses `useSearchParams()` without Suspense boundary
- **Next.js 13+ requirement**: Must wrap in Suspense or use a separate non-async component
- **Solution**: Extract into separate component in Suspense boundary

### 4. Build Configuration
- **File**: `next.config.js`
- **Issue**: TypeScript errors currently disabled (`ignoreBuildErrors: true`)
- **Solution**: Re-enable proper TypeScript checking after fixing errors above

---

## Live Backend API

**URL**: `https://mtd.runfoo.run`

**Available endpoints** (already working):
- `/health` - Health check
- `/docs` - Swagger UI (interactive)
- `/redoc` - ReDoc documentation
- `/openapi.json` - OpenAPI schema
- `/api/v1/` - All API endpoints

**Full API Schema**: Fetch and review `/openapi.json` for all available endpoints and methods

---

## Your Task

### What needs to be built:
1. **Home/Landing Page** at `/` (currently 404)
2. **Navigation** - Link to API docs, features, etc.
3. **Optional**: Interactive dashboard or features that consume the backend API

### Constraints:
- Must serve from root path `/`
- HTTPS enabled (Cloudflare Flexible SSL)
- Must work with backend API at `https://mtd.runfoo.run/api/v1`
- CORS already configured on backend
- Rate limiting: 100 req/min default, 10 req/sec for API endpoints

---

## Deployment Options

### Option 1: Static SPA (Recommended - Simplest)
Build React/Vue/Svelte as static files, serve from nginx

**Advantages**: Fast, simple, no extra services
**Location**: Frontend code in this repo, built files served by nginx
**Steps**:
1. Create frontend in `/frontend` directory
2. Build to `/frontend/dist`
3. Mount in docker-compose nginx volume
4. Update nginx config `location /` to serve static files
5. Commit and push

### Option 2: Node.js Service
Add Node.js frontend service to docker-compose

**Advantages**: Dynamic rendering, SSR capable
**Location**: Separate service in docker-compose
**Steps**:
1. Create `frontend/` service in docker-compose.yml
2. Proxy `/` from nginx to frontend service
3. Mount code as volume
4. Test and deploy

### Option 3: FastAPI Static Mount
Modify backend FastAPI to serve frontend

**Advantages**: Integrated, single service
**Location**: Built files in backend app folder
**Steps**:
1. Add StaticFiles mount to FastAPI
2. Build frontend static files
3. Include in backend Docker build
4. Deploy with existing backend

**Recommendation**: Start with **Option 1** (static SPA) - simplest and most performant.

---

## Integration Details

### Backend API
```
Base URL: https://mtd.runfoo.run/api/v1
Protocol: HTTPS (via Cloudflare Flexible SSL)
Authentication: JWT (HS256)
CORS: Enabled (no additional headers needed)
```

### Example API Call
```javascript
// Check health
fetch('https://mtd.runfoo.run/health')
  .then(r => r.json())
  .then(data => console.log(data))

// API endpoint with auth
fetch('https://mtd.runfoo.run/api/v1/endpoint', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
})
```

### Rate Limits
- Default: 100 requests/60 seconds
- Auth endpoints (`/api/v1/auth/`): 5 requests/second, burst 10
- API endpoints (`/api/v1/`): 10 requests/second, burst 20

### Authentication
- Algorithm: HS256
- Access token: 15 minutes
- Refresh token: 30 days
- Password hashing: Argon2

---

## Current Infrastructure

### Backend Location
```
Repository: https://github.com/fullsizemalt/morethanadiagnosis-hub
Directory: /backend (after clone)
Language: Python, FastAPI
Database: PostgreSQL 15
Cache: Redis 7
Proxy: Nginx (Alpine)
```

### Docker Setup
- **docker-compose.yml**: Orchestrates all services
- **nginx.conf**: Reverse proxy configuration
- **Dockerfile**: Backend image definition
- Deployed on: nexus-vector (100.95.3.92)

### Current Nginx Config
File: `/backend/nginx.conf` (lines 77-90)

Current root handler returns 404:
```nginx
location / {
    return 404;
}
```

**This needs to change** to serve your frontend

---

## Frontend Repository Structure (Suggested)

```
morethanadiagnosis-hub/
├── backend/                    # (existing backend)
│   ├── app/
│   ├── docker-compose.yml
│   ├── Dockerfile
│   ├── nginx.conf
│   └── ...
├── frontend/                   # (create this)
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── App.jsx
│   │   └── index.jsx
│   ├── public/
│   ├── package.json
│   ├── vite.config.js
│   └── .gitignore
└── README.md
```

---

## Implementation Checklist

### Planning (You)
- [ ] Choose frontend framework (React, Vue, Svelte, plain HTML?)
- [ ] Define home page design/layout
- [ ] List required features
- [ ] Pick deployment option (1, 2, or 3)
- [ ] Review backend API schema (`/openapi.json`)

### Development (You)
- [ ] Create frontend code in repo
- [ ] Build and test locally
- [ ] Integrate with backend API
- [ ] Test all endpoints work
- [ ] Ensure responsive/mobile-friendly

### Deployment (You)
- [ ] Update nginx.conf for your approach
- [ ] Update docker-compose.yml if needed
- [ ] Build frontend
- [ ] Test on staging/production
- [ ] Commit changes
- [ ] Push to GitHub

### Verification (Post-Deploy)
- [ ] `https://mtd.runfoo.run/` loads home page (not 404)
- [ ] Navigation works
- [ ] Links to `/docs` work
- [ ] API integration functional
- [ ] HTTPS connection valid
- [ ] No console errors

---

## Key Files to Modify

### For Static SPA (Option 1)
1. **docker-compose.yml** - Add frontend volume mount to nginx
2. **nginx.conf** - Change root location to serve static files
3. **Create /frontend** - New frontend code directory

### For Node Service (Option 2)
1. **docker-compose.yml** - Add frontend service definition
2. **nginx.conf** - Add proxy_pass to frontend service
3. **Create /frontend** - Frontend code with Node.js

### For FastAPI Mount (Option 3)
1. **backend/app/main.py** - Add StaticFiles mount
2. **Dockerfile** - Include frontend build in image
3. **Create /frontend** - Frontend code

---

## Testing

### Local Frontend Testing
```bash
cd frontend
npm install
npm run dev  # Start dev server on localhost:5173
```

### Production Testing (After Deploy)
```bash
# Test home page
curl https://mtd.runfoo.run/

# Test API integration
curl https://mtd.runfoo.run/health

# Test docs still work
curl https://mtd.runfoo.run/docs
```

---

## Reference Information

### Backend API Documentation
- **Swagger**: `https://mtd.runfoo.run/docs`
- **ReDoc**: `https://mtd.runfoo.run/redoc`
- **OpenAPI Schema**: `https://mtd.runfoo.run/openapi.json`

### Backend Configuration
- Environment: `production`
- Debug: `false`
- Logging: JSON format, INFO level
- HTTPS: Cloudflare Flexible SSL

### CORS Configuration (Already Set)
```
Origins: https://mtd.runfoo.run, http://localhost:3000
Credentials: Allowed
Methods: All
Headers: All
```

---

## Questions Before Starting

1. **Framework**: React, Vue, Svelte, or plain HTML/CSS/JS?
2. **Complexity**: Simple landing page or feature-rich dashboard?
3. **Design**: Any brand guidelines or mockups?
4. **Features**: What should the home page highlight?
5. **Deployment approach**: Static (Option 1), Node service (Option 2), or FastAPI mount (Option 3)?

---

## Next Steps

1. Review backend API schema at `/openapi.json`
2. Decide on frontend framework and deployment option
3. Create frontend code in new `/frontend` directory
4. Implement home page and navigation
5. Update nginx.conf and/or docker-compose.yml
6. Build and test
7. Commit to GitHub
8. Deploy
9. Verify all endpoints work end-to-end

---

## Support

- **Backend API Status**: `https://mtd.runfoo.run/health`
- **Backend Docs**: `https://mtd.runfoo.run/docs`
- **OpenAPI Schema**: `https://mtd.runfoo.run/openapi.json`
- **Repository**: https://github.com/fullsizemalt/morethanadiagnosis-hub
- **Deployment**: nexus-vector (100.95.3.92)

---

**Backend is ready. Frontend is your turn.**