Fusion
94aa88c154
- Add Sessions tab to navigation between Dashboard and Projects - Show active session count badge in navigation - Create SessionsPage with: - Last session section with resume button - Active sessions grid with open/stop actions - Recent sessions list - Create session form with project/repo/tool selectors - Add last_session_id to user config - Update UserConfig schemas (backend and frontend) - Add comprehensive CSS for sessions page Quality gates: typecheck ✓, lint ✓, build ✓
117 lines
2.3 KiB
Markdown
117 lines
2.3 KiB
Markdown
# API Documentation - Design
|
|
|
|
## Architecture
|
|
|
|
```
|
|
API Documentation
|
|
├── OpenAPI (FastAPI native)
|
|
│ ├── /docs (Swagger UI)
|
|
│ ├── /redoc (ReDoc)
|
|
│ └── /openapi.json
|
|
├── Health Endpoints
|
|
│ ├── GET /health
|
|
│ └── GET /health/db
|
|
├── API README
|
|
│ └── apps/api/README.md
|
|
└── Architecture Decision Records
|
|
└── docs/architecture/decisions/
|
|
```
|
|
|
|
## Component Design
|
|
|
|
### OpenAPI Documentation
|
|
|
|
FastAPI automatically generates OpenAPI schema from:
|
|
- Pydantic models (request/response)
|
|
- Endpoint docstrings
|
|
- Path operation parameters
|
|
- Response status codes
|
|
|
|
**Enhancements needed:**
|
|
- Add descriptions to all Pydantic models
|
|
- Add docstrings to all endpoints
|
|
- Add response examples where helpful
|
|
- Add authentication requirements
|
|
|
|
### Health Endpoints
|
|
|
|
**GET /health**
|
|
```json
|
|
{
|
|
"status": "healthy",
|
|
"timestamp": "2026-05-19T12:00:00Z",
|
|
"version": "0.1.0",
|
|
"checks": {
|
|
"database": {
|
|
"status": "healthy",
|
|
"response_time_ms": 5.2
|
|
},
|
|
"disk": {
|
|
"status": "healthy",
|
|
"free_gb": 45.2,
|
|
"total_gb": 100.0
|
|
}
|
|
},
|
|
"uptime_seconds": 3600
|
|
}
|
|
```
|
|
|
|
**GET /health/db**
|
|
```json
|
|
{
|
|
"status": "healthy",
|
|
"response_time_ms": 5.2,
|
|
"connections": {
|
|
"active": 2,
|
|
"idle": 3,
|
|
"max": 20
|
|
}
|
|
}
|
|
```
|
|
|
|
### API README
|
|
|
|
**Sections:**
|
|
1. Overview
|
|
2. Quick Start
|
|
3. Environment Variables
|
|
4. Development Setup
|
|
5. Running Tests
|
|
6. Architecture Overview
|
|
7. Common Commands
|
|
8. Deployment
|
|
|
|
### Architecture Decision Records
|
|
|
|
**Format:**
|
|
- Title
|
|
- Status (proposed, accepted, deprecated)
|
|
- Context
|
|
- Decision
|
|
- Consequences
|
|
- Date
|
|
|
|
**ADRs to create:**
|
|
1. Session-based authentication (vs JWT)
|
|
2. SQLAlchemy async with PostgreSQL
|
|
3. Docker-based tool instances
|
|
|
|
## Technical Details
|
|
|
|
**Libraries:**
|
|
- FastAPI (built-in OpenAPI)
|
|
- Pydantic v2 (schemas)
|
|
- psutil (disk/health metrics)
|
|
|
|
**Files to modify:**
|
|
- `apps/api/src/main.py` - Add health endpoints
|
|
- All `apps/api/src/api/*.py` - Add docstrings
|
|
- All `apps/api/src/models/*.py` - Add model descriptions
|
|
- `apps/api/src/schemas/*.py` - Add response schemas
|
|
|
|
## Error Handling
|
|
|
|
- Health endpoints return 200 even if degraded
|
|
- Failed checks included in response with "degraded" status
|
|
- Never expose sensitive info in health responses
|