Files

T

alex e7819bfc82 feat: implement docker infrastructure (US-001)

- Add docker-compose.yml with postgres, redis, api, and web services
- Add multi-stage Dockerfile for API (Python 3.11)
- Add multi-stage Dockerfile for web (Node.js 20 + nginx)
- Add Makefile with common development commands
- Add .env.example with all required environment variables
- Add placeholder pyproject.toml and package.json for builds
- Configure health checks for all services
- Setup persistent volumes for postgres, redis, and repos
- Run services as non-root users

2026-05-16 17:44:39 +00:00

2.2 KiB

Raw Permalink Blame History

API Documentation Specification

Purpose

Provide comprehensive API documentation and health monitoring endpoints.

Requirements

Requirement: OpenAPI/Swagger Documentation

The system SHALL auto-generate API documentation.

Scenario: API docs access

GIVEN the running API server
WHEN visiting /docs
THEN Swagger UI displays:
- All available endpoints
- Request/response schemas
- Authentication requirements
- Example requests and responses

Requirement: Health Check Endpoints

The system SHALL provide health monitoring endpoints.

Scenario: General health check

GIVEN the running API server
WHEN visiting /health
THEN it returns:
- Overall service status
- Database connectivity status
- Redis connectivity status
- Disk space status
- Uptime information

Scenario: Database health check

GIVEN the running API server
WHEN visiting /health/db
THEN it returns:
- Database connection status
- Response time
- Connection pool status

Requirement: API Setup Documentation

The system SHALL document API setup and configuration.

Scenario: Developer onboarding

GIVEN a new developer
WHEN they read apps/api/README.md
THEN they find:
- Setup instructions
- Environment variables
- Running tests
- Common commands
- Architecture overview

Requirement: Architecture Decision Records

The system SHALL document significant architectural decisions.

Scenario: Auth decision record

GIVEN the codebase
THEN an ADR SHALL exist documenting:
- Why httpOnly cookies were chosen
- Alternatives considered
- Trade-offs and risks
- Decision date and participants

Requirement: Endpoint Documentation

The system SHALL document all API endpoints.

Scenario: Endpoint coverage

GIVEN the API codebase
THEN every endpoint SHALL have:
- Pydantic request/response models
- Docstrings with descriptions
- Response status codes
- Authentication requirements

Dependencies

FastAPI (auto-generates OpenAPI)
Pydantic v2

Quality Gates

/docs endpoint loads successfully
/health returns 200 with valid JSON
/health/db returns database status
pytest must pass
mypy . must pass
ruff check . must pass

2.2 KiB Raw Permalink Blame History