Liveness, readiness, and deep dependency health endpoints for Next.js and FastAPI. Codifies the project's three-tier health probe architecture, Docker healthchecks, cron-based monitoring, and system health script.
Liveness, readiness, and deep dependency health endpoints for Next.js and FastAPI. Codifies the project's three-tier health probe architecture, Docker healthchecks, cron-based monitoring, and system health script.
Health Check - Liveness, Readiness & Dependency Probes
Codifies the project's three-tier health probe architecture (shallow liveness, readiness, deep dependency checks), Docker container healthchecks, cron-based periodic monitoring, route discovery verification, and the comprehensive system health script. Patterns align with Kubernetes probe conventions even when running outside K8s.
Description
Codifies liveness, readiness, and deep dependency health endpoints for NodeJS-Starter-V1's Next.js and FastAPI services, covering three-tier probe architecture, Docker healthchecks, cron-based monitoring, route discovery verification, and the system health script.
When to Apply
Positive Triggers
Adding new health check endpoints or probes
Integrating new dependencies that need health verification
Configuring Docker healthchecks for containers
Setting up periodic health monitoring via cron
Implementing startup, liveness, or readiness probes
Adding service dependency checks to existing endpoints
Designing dashboard UI for health status (use dashboard-patterns instead)
Implementing graceful shutdown (use graceful-shutdown when available)
Core Directives
The Three Laws of Health Checks
Three tiers, not one: Separate liveness (am I alive?), readiness (can I serve traffic?), and deep (are all dependencies healthy?). Never combine them.
Parallel dependency checks: Check all dependencies concurrently via Promise.all or asyncio.gather. Never check sequentially — a slow database should not delay the Redis check.
503 for unhealthy: Return HTTP 200 for healthy/degraded, HTTP 503 for unhealthy. Load balancers and orchestrators use status codes, not response bodies.
Existing Project Infrastructure
Backend (FastAPI)
Endpoint
Type
Location
GET /health
Liveness
apps/backend/src/api/routes/health.py
GET /ready
Readiness
apps/backend/src/api/routes/health.py
GET /api/agents/{id}/health
Agent health
apps/backend/src/api/routes/agent_dashboard.py
Frontend (Next.js)
Endpoint
Type
Location
GET /api/health
Shallow liveness
apps/web/app/api/health/route.ts
GET /api/health/deep
Deep dependency
apps/web/app/api/health/deep/route.ts
GET /api/health/routes
Route discovery
apps/web/app/api/health/routes/route.ts
GET /api/cron/health-check
Periodic cron
apps/web/app/api/cron/health-check/route.ts
Docker
Service
Command
Interval
Timeout
Retries
PostgreSQL
pg_isready -U starter_user -d starter_db
10s
5s
5
Redis
redis-cli ping
10s
5s
5
System Script
scripts/health-check.ps1 — 6-phase comprehensive health check (prerequisites, database, backend, frontend, integration, summary) with exit code 0 (healthy) or 1 (unhealthy).
Health Status Model
All health endpoints use a three-state status:
Status
HTTP Code
Meaning
Action
healthy
200
All systems operational
None
degraded
200
Functional but impaired
Monitor, alert
unhealthy
503
Cannot serve requests
Remove from load balancer
Aggregation Rule
if any dependency is unhealthy → overall = unhealthy (503)
else if any dependency is degraded → overall = degraded (200)
else → overall = healthy (200)
Probe Patterns
Tier 1: Liveness (Shallow)
Returns immediately with minimal computation. Used by load balancers and orchestrators to confirm the process is alive.
start_period gives the application time to initialise before healthchecks begin. Use depends_on with condition: service_healthy to sequence container startup.
Cron-Based Monitoring
The project's /api/cron/health-check runs every 5 minutes, pings the backend, and logs results. Secured with CRON_SECRET bearer token.
