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
This commit is contained in:
admin
parent
cb4431eade
commit
b87ede6f3b
1 changed files with 320 additions and 0 deletions
320
backend/FRONTEND_HANDOFF.md
Normal file
320
backend/FRONTEND_HANDOFF.md
Normal file
|
|
@ -0,0 +1,320 @@
|
||||||
|
# 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
|
||||||
|
```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.**
|
||||||
Loading…
Add table
Reference in a new issue