runfoo-org/morethanadiagnosis-hub
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
morethanadiagnosis-hub/backend/FRONTEND_HANDOFF.md
admin b87ede6f3b docs: frontend development handoff - home screen needed 
- Backend API fully operational and deployed
- Added comprehensive handoff document for frontend development
- Includes deployment options, API integration details, and checklist
- Ready for claude-web agent to build frontend home screen

Job ID: MTAD-IMPL-2025-11-18-CL
2025-11-18 05:24:42 +00:00

7.8 KiB
Raw Blame History

Frontend Development Handoff - MoreThanADiagnosis Hub

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

Quick Summary

✅ Backend is fully operational and deployed to https://mtd.runfoo.run

❌ Frontend is missing - Root path / currently returns 404

Your task: Build and deploy a frontend home screen + navigation

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 is ready. Frontend is your turn.