System Status

Health check and monitoring endpoint for application uptime, cache performance, and external dependency status.

System Status API (`app/api/system-status/`)

Health check and monitoring endpoint for application uptime, cache performance, and external dependency status.

Purpose

Provides real-time health metrics for:

Application uptime and availability
Cache utilization and performance
External API reachability (NJ OGIS APIs)
Overall system status (healthy/degraded/unhealthy)

Endpoint

GET /api/system-status

Query Parameters

Parameter	Type	Required	Description
`checkApis`	string	No	Set to `"true"` to include external API health verification (slower)

Response Format

interface HealthCheckResponse {
  status: "healthy" | "degraded" | "unhealthy";
  timestamp: string; // ISO 8601 format
  uptime: {
    seconds: number;
    formatted: string; // Human-readable (e.g., "2d 5h 30m 15s")
  };
  cache: {
    enabled: boolean;
    size: number; // Current number of cached items
    maxSize: number; // Maximum cache capacity
    utilizationPercent: number; // Percentage full
  };
  externalApis?: {
    njStateApis: {
      status: "reachable" | "unreachable" | "unknown";
      responseTime?: number; // Milliseconds
      error?: string; // Error message if unreachable
    };
  };
}

Status Codes

Code	Meaning	Description
`200 OK`	Healthy or degraded	Application is operational
`503 Service Unavailable`	Unhealthy	Application cannot serve requests

Health Status Levels

Healthy

Application is fully operational:

Uptime tracking working
Cache functioning
External APIs reachable (if checked)

Degraded

Application is operational but with reduced functionality:

External APIs unreachable (main app still works via cache)
Cache nearing capacity (> 90% full)

Unhealthy

Application cannot serve requests:

Critical component failure
Unable to respond to requests

Usage Examples

Quick Health Check (Fast)

# Returns in ~50ms
curl http://localhost:3000/api/system-status

Response:

{
  "status": "healthy",
  "timestamp": "2025-12-26T10:30:00.000Z",
  "uptime": {
    "seconds": 86400,
    "formatted": "1d 0h 0m 0s"
  },
  "cache": {
    "enabled": true,
    "size": 150,
    "maxSize": 1000,
    "utilizationPercent": 15
  }
}

Deep Health Check (With External APIs)

# Returns in ~1s (depends on API response time)
curl http://localhost:3000/api/system-status?checkApis=true

Response:

{
  "status": "healthy",
  "timestamp": "2025-12-26T10:30:00.000Z",
  "uptime": {
    "seconds": 86400,
    "formatted": "1d 0h 0m 0s"
  },
  "cache": {
    "enabled": true,
    "size": 150,
    "maxSize": 1000,
    "utilizationPercent": 15
  },
  "externalApis": {
    "njStateApis": {
      "status": "reachable",
      "responseTime": 234
    }
  }
}

Degraded Status Example

{
  "status": "degraded",
  "timestamp": "2025-12-26T10:30:00.000Z",
  "uptime": {
    "seconds": 172800,
    "formatted": "2d 0h 0m 0s"
  },
  "cache": {
    "enabled": true,
    "size": 150,
    "maxSize": 1000,
    "utilizationPercent": 15
  },
  "externalApis": {
    "njStateApis": {
      "status": "unreachable",
      "responseTime": 5000,
      "error": "Connection timeout"
    }
  }
}

Integration Examples

Load Balancer Health Check

# NGINX upstream health check
upstream app_servers {
  server app1.example.com:3000;
  server app2.example.com:3000;

  # Check every 30 seconds
  health_check interval=30s
               fails=3
               passes=2
               uri=/api/system-status;
}

Monitoring Dashboard (React)

"use client";
import { useEffect, useState } from "react";

interface SystemHealth {
  status: "healthy" | "degraded" | "unhealthy";
  uptime: string;
  cacheUtilization: number;
  apiReachable: boolean;
}

export function HealthDashboard() {
  const [health, setHealth] = useState<SystemHealth | null>(null);

  useEffect(() => {
    async function fetchHealth() {
      const res = await fetch("/api/system-status?checkApis=true");
      const data = await res.json();

      setHealth({
        status: data.status,
        uptime: data.uptime.formatted,
        cacheUtilization: data.cache.utilizationPercent,
        apiReachable: data.externalApis?.njStateApis.status === "reachable",
      });
    }

    fetchHealth();
    const interval = setInterval(fetchHealth, 30000); // Refresh every 30s
    return () => clearInterval(interval);
  }, []);

  if (!health) return <div>Loading...</div>;

  return (
    <div>
      <h1>System Status: {health.status}</h1>
      <p>Uptime: {health.uptime}</p>
      <p>Cache: {health.cacheUtilization}% full</p>
      <p>NJ APIs: {health.apiReachable ? "✅ Reachable" : "❌ Unreachable"}</p>
    </div>
  );
}

CI/CD Health Verification

# GitHub Actions workflow
- name: Deploy to production
  run: |
    # Deploy application
    ./deploy.sh

    # Wait for deployment
    sleep 10

    # Verify health
    curl -f https://app.example.com/api/system-status || exit 1

Uptime Monitoring (cron job)

#!/bin/bash
# Check health every 5 minutes

ENDPOINT="https://app.example.com/api/system-status?checkApis=true"
RESPONSE=$(curl -s $ENDPOINT)
STATUS=$(echo $RESPONSE | jq -r '.status')

if [ "$STATUS" != "healthy" ]; then
  # Send alert
  echo "System unhealthy: $RESPONSE" | mail -s "Health Alert" ops@example.com
fi

Implementation Details

Uptime Tracking

Application start time is tracked at module initialization:

const APP_START_TIME = Date.now();

// Calculate uptime
const uptimeSeconds = (Date.now() - APP_START_TIME) / 1000;

Cache Statistics

Fetched from in-memory cache adapter:

const cacheStats = await cache.getStats();
// { size, maxSize, hits, misses, hitRate, evictions }

External API Check

Tests NJ Suggestions API with a simple query:

try {
  await suggestionsClient.getSuggestions("test", 1);
  return { status: "reachable", responseTime };
} catch (error) {
  return { status: "unreachable", error: error.message };
}

Performance Considerations

Quick Mode (no `checkApis` parameter)

Response Time: < 50ms
Operations: Memory reads only (uptime, cache stats)
Use Case: Frequent health checks (every 10-30s)

Deep Mode (`checkApis=true`)

Response Time: 500ms - 1s
Operations: Memory reads + external API call
Use Case: Periodic deep checks (every 5-10 minutes)

API Routes Overview - All API endpoints
Cache Adapter - Cache implementation
NJ API Client - External API integration
System Status Page - User-facing status dashboard