Description

Overview

The Health API provides comprehensive health monitoring endpoints for the CoreBanq system:

• Basic health check (liveness)
• Readiness probe for container orchestration
• Detailed component health checks for all system dependencies
• PreStop hook for graceful shutdown

Health Check Components

The system monitors the following components:

• Database (PostgreSQL) - Critical internal component
• Redis Cache - Critical external component
• OCR Tesseract - External optional service for document processing
• CRP gRPC Service - Critical external service for crypto operations
• Email Service - External service for notifications
• SMS Service - External service for notifications
• Queue Service - Critical internal service (SQS/Local)
• TOTP Service - Internal service for 2FA
• LLM Service - External AI service

Endpoints

Basic Health Check

Get Health Status

GET /health

Simple health check endpoint following industry standards.

Response:

Application is healthy

Liveness Probe

Get Liveness Status

GET /health/live

Container liveness probe endpoint for orchestration platforms.

Response:

Application is healthy

Readiness Check

Get Readiness Status

GET /health/ready

Check if application is ready to serve traffic.

Response:

Application is ready

Comprehensive Health Check

Get Detailed Health Status

GET /health/detailed

Detailed health check of all system components including external dependencies.

Response:

{
  "overall_status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "components": [
    {
      "component": "database",
      "status": "healthy",
      "response_time_ms": 150,
      "details": {
        "connection": "active"
      },
      "last_checked": "2024-01-15T10:30:00Z",
      "tags": ["critical", "internal"]
    }
  ],
  "summary": {
    "total_components": 5,
    "healthy_count": 5,
    "unhealthy_count": 0,
    "degraded_count": 0,
    "avg_response_time_ms": 702.0
  },
  "system_info": {
    "service_name": "corebanq-api",
    "version": "unknown",
    "environment": "development",
    "uptime": "2h15m30s",
    "start_time": "2024-01-15T08:15:00Z",
    "go_version": "go1.21.5",
    "server_ready": true
  },
  "message": "System is shutting down"
}

Lifecycle Management

PreStop Hook

GET /lifecycle/prestop

Container preStop hook for graceful shutdown.

Response:

Shutting down gracefully

Legacy Endpoints (Deprecated)

The following endpoints are maintained for backward compatibility:

• /v1/check/health → Use /health instead
• /v1/check/ready → Use /health/ready instead
• /v1/lifecycle/prestop → Use /lifecycle/prestop instead

Note: /v1/check/comprehensive never existed - use /health/detailed instead.

Status Codes

Health Endpoints Status Matrix

Endpoint Purposes

• Liveness (/health/live): Kubernetes liveness probe - only fails during application shutdown/deadlock
• Readiness (/health/ready): Kubernetes readiness probe - fails when not ready to accept traffic (critical dependencies down)
• Detailed Health (/health/detailed): Complete system health with component-level diagnostics

Health Statuses

• healthy - Component works normally
• degraded - There are issues, but still working
• unhealthy - Component is not working
• unknown - Status is unknown

Component Tags

• critical - Critically important components (database, core services)
• external - External services
• internal - Internal components
• optional - Optional components

Security Considerations

• PreStop hook only accepts requests from localhost/internal network
• Health checks are public endpoints
• Basic text responses for simple checks, JSON for detailed checks
• No sensitive data exposure in health responses

Container Orchestration Integration

AWS ECS Health Checks

"healthCheck": {
  "command": ["CMD-SHELL", "curl -f http://localhost:8080/health || exit 1"],
  "interval": 30,
  "timeout": 5,
  "retries": 3,
  "startPeriod": 60
}

AWS ALB Target Group

{
  "HealthCheckPath": "/health/ready",
  "HealthCheckProtocol": "HTTP",
  "HealthCheckIntervalSeconds": 15,
  "HealthCheckTimeoutSeconds": 5,
  "HealthyThresholdCount": 2,
  "UnhealthyThresholdCount": 3
}

Kubernetes Configuration

Liveness Probe

livenessProbe:
  httpGet:
    path: /health/live
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 10

Readiness Probe

readinessProbe:
  httpGet:
    path: /health/ready
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 5

PreStop Hook

lifecycle:
  preStop:
    httpGet:
      path: /lifecycle/prestop
      port: 8080

Docker Compose

services:
  corebanq-api:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 60s

Language Support

The API supports localization through the Accept-Language header:

• English (en)
• German (de)
• French (fr)
• Italian (it)