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