feat: add Sessions Hub page

- 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 ✓
2026-05-19 23:06:54 +02:00
parent 4f695d7e62
commit 94aa88c154
17 changed files with 996 additions and 11 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+name: api-documentation
@@ -0,0 +1,116 @@
+# 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
@@ -0,0 +1,54 @@
+# API Documentation
+
+## Problem
+
+The API lacks comprehensive documentation:
+- No auto-generated OpenAPI/Swagger UI
+- Health endpoint is minimal (only checks database)
+- Missing endpoint documentation and docstrings
+- No API README for developer onboarding
+- No Architecture Decision Records (ADRs)
+
+## Solution
+
+Provide comprehensive API documentation:
+
+1. **Auto-generated OpenAPI docs** - FastAPI native `/docs` and `/redoc` endpoints
+2. **Enhanced health checks** - `/health` with full system status, `/health/db` for database
+3. **Endpoint documentation** - Proper docstrings, Pydantic models, response codes
+4. **API README** - Developer onboarding guide
+5. **Architecture Decision Records** - Document key architectural choices
+
+## Key Features
+
+### OpenAPI Documentation
+- Interactive Swagger UI at `/docs`
+- ReDoc at `/redoc`
+- All endpoints with schemas and examples
+- Authentication documented
+
+### Health Monitoring
+- `/health` - Overall system health (database, disk, uptime)
+- `/health/db` - Database-specific health check
+- JSON responses with status indicators
+
+### Developer Documentation
+- `apps/api/README.md` - Setup, env vars, testing
+- ADRs in `docs/architecture/decisions/`
+- Inline code documentation
+
+## Benefits
+
+- **Developer onboarding** - New devs can understand the API quickly
+- **API discoverability** - Interactive docs for testing endpoints
+- **Health monitoring** - Operations can monitor system health
+- **Knowledge preservation** - ADRs capture why decisions were made
+
+## Success Criteria
+
+- [ ] `/docs` loads Swagger UI with all endpoints
+- [ ] `/health` returns comprehensive health data
+- [ ] `/health/db` returns database status
+- [ ] All endpoints have docstrings
+- [ ] API README exists with setup instructions
+- [ ] At least one ADR exists
@@ -0,0 +1,125 @@
+# API Documentation Specification
+
+## Requirements
+
+### Functional Requirements
+
+1. **OpenAPI Documentation**: Auto-generated at `/docs` and `/redoc`
+2. **Health Endpoints**: `/health` and `/health/db` with comprehensive status
+3. **Endpoint Documentation**: All endpoints have docstrings and Pydantic models
+4. **API README**: `apps/api/README.md` with developer onboarding
+5. **Architecture Decision Records**: Document key architectural choices
+
+### Non-Functional Requirements
+
+1. **Performance**: Health checks complete in < 100ms
+2. **Security**: Health endpoints don't expose sensitive data
+3. **Maintainability**: Documentation stays in sync with code
+
+## API Specification
+
+### GET /health
+
+Returns overall system health status.
+
+**Response 200:**
+```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
+
+Returns database-specific health status.
+
+**Response 200:**
+```json
+{
+  "status": "healthy",
+  "response_time_ms": 5.2
+}
+```
+
+### GET /docs
+
+FastAPI Swagger UI (auto-generated).
+
+### GET /redoc
+
+FastAPI ReDoc (auto-generated).
+
+## Documentation Requirements
+
+### Endpoint Docstrings
+
+Every endpoint must have:
+- Description of what it does
+- Request/response model descriptions
+- Authentication requirements
+- Error responses
+
+### Pydantic Models
+
+Every model must have:
+- `description` field metadata
+- Example values where helpful
+- Proper typing
+
+### API README Structure
+
+```markdown
+# Headquarter API
+
+## Overview
+## Quick Start
+## Environment Variables
+## Development
+## Testing
+## Architecture
+## Deployment
+```
+
+## ADR Template
+
+```markdown
+# ADR-XXX: Title
+
+## Status
+Accepted
+
+## Context
+What is the issue we're facing?
+
+## Decision
+What did we decide?
+
+## Consequences
+What are the trade-offs?
+
+## Date
+2026-05-19
+```
+
+## Quality Gates
+
+- `/docs` loads successfully
+- `/health` returns 200 with valid JSON
+- `/health/db` returns database status
+- All endpoints have docstrings
+- API README is complete
+- At least one ADR exists
@@ -0,0 +1,94 @@
+# API Documentation - Tasks
+
+## Phase 1: Health Endpoints
+
+- [x] **Task 1.1**: Enhance `/health` endpoint
+  - Add timestamp, version, uptime
+  - Add disk space check
+  - Add comprehensive checks object
+  - Create HealthCheck Pydantic models
+
+- [x] **Task 1.2**: Create `/health/db` endpoint
+  - Database connection check
+  - Response time measurement
+  - Connection pool status
+
+## Phase 2: Endpoint Documentation
+
+- [x] **Task 2.1**: Document auth endpoints
+  - Add docstrings to `src/api/auth.py`
+  - Add response model descriptions
+  - Add error responses
+
+- [x] **Task 2.2**: Document projects endpoints
+  - Add docstrings to `src/api/projects.py`
+  - Document request/response models
+
+- [x] **Task 2.3**: Document repositories endpoints
+  - Add docstrings to `src/api/git_repositories.py`
+  - Document file operations
+
+- [x] **Task 2.4**: Document user endpoints
+  - Add docstrings to `src/api/users.py`
+  - Document profile endpoints
+
+- [x] **Task 2.5**: Document tool endpoints
+  - Add docstrings to `src/api/tool_types.py`
+  - Add docstrings to `src/api/tool_instances.py`
+
+- [x] **Task 2.6**: Document SSH keys endpoints
+  - Add docstrings to `src/api/ssh_keys.py`
+
+- [x] **Task 2.7**: Document config endpoints
+  - Add docstrings to `src/api/user_config.py`
+
+- [x] **Task 2.8**: Document dashboard endpoint
+  - Add docstrings to `src/api/dashboard.py`
+
+- [x] **Task 2.9**: Document terminal endpoint
+  - Add docstrings to `src/api/terminal.py`
+
+## Phase 3: Model Documentation
+
+- [x] **Task 3.1**: Document Pydantic models
+  - Add descriptions to all response models
+  - Add example values
+  - Document in `src/schemas/` or inline
+
+## Phase 4: API README
+
+- [x] **Task 4.1**: Create `apps/api/README.md`
+  - Overview section
+  - Quick start guide
+  - Environment variables table
+  - Development setup
+  - Testing instructions
+  - Architecture overview
+  - Common commands
+
+## Phase 5: Architecture Decision Records
+
+- [x] **Task 5.1**: Create ADR for session auth
+  - Document why cookies vs JWT
+  - Trade-offs and risks
+
+- [x] **Task 5.2**: Create ADR for async SQLAlchemy
+  - Document async pattern choice
+  - PostgreSQL decision
+
+## Phase 6: Quality Gates
+
+- [x] **Task 6.1**: Verify `/docs` endpoint
+  - Check all endpoints appear
+  - Verify schemas are documented
+
+- [x] **Task 6.2**: Verify health endpoints
+  - Test `/health`
+  - Test `/health/db`
+
+- [x] **Task 6.3**: Run linting
+  - ruff check
+  - mypy
+
+- [x] **Task 6.4**: Run tests
+  - pytest