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

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

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

cd frontend
npm install
npm run dev  # Start dev server on localhost:5173

Production Testing (After Deploy)

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