content-factory/docs/public-health-interfaces.md

Public Health Interfaces

Task 001 pre-requirement contract. These interfaces are the public test surface for the dockerized foundation implementation. Tests must exercise only the Docker Compose stack and HTTP endpoints, not service internals.

Local Stack

The local stack starts from the repository root:

docker compose up --build

The implementation must expose these local ports:

Service	URL
Frontend	http://localhost:3000
Backend	http://localhost:8000
Runner	http://localhost:8010

Health Endpoints

Backend Process Health

GET http://localhost:8000/health

Expected response:

{
  "service": "backend",
  "status": "ok"
}

This endpoint proves that the FastAPI process is serving HTTP.

Backend Connectivity Smoke

GET http://localhost:8000/health/dependencies

Expected response:

{
  "service": "backend",
  "status": "ok",
  "dependencies": {
    "postgres": "ok",
    "redis": "ok",
    "object_storage": "ok"
  }
}

This endpoint is the public smoke surface for backend connectivity to Postgres, Redis, and S3-compatible object storage. Implementations may add fields, but must preserve these keys and ok statuses when dependencies are reachable.

Runner Health

GET http://localhost:8010/health

Expected response:

{
  "service": "runner",
  "status": "ok"
}

Frontend Health

GET http://localhost:3000/health

Expected response:

{
  "service": "frontend",
  "status": "ok"
}

Architecture Boundaries

The frontend application must follow Feature-Sliced Design with these top-level layers:

app/
processes/
pages/
widgets/
features/
entities/
shared/

The backend and runner services must use these top-level architecture layers:

domain/
application/
infrastructure/
presentation/
shared/