platform-health

Health check orchestration for NestJS applications built on @nestjs/terminus. Register custom health indicators and expose aggregated health status via a single orchestrator. Extracted from platform-core to provide a focused, independently versionable health module.

Package: @breadstone/archipel-platform-health

npm install @breadstone/archipel-platform-health

Installation

import {
  HealthModule,
  HealthOrchestrator,
  IHealthIndicator,
  IHealthCheckResult,
  HEALTH_INDICATORS,
} from '@breadstone/archipel-platform-health';

---

Module Registration

Register the module with one or more health indicators:

import { Module } from '@nestjs/common';
import { HealthModule } from '@breadstone/archipel-platform-health';
import { DatabaseHealthIndicator } from './health/DatabaseHealthIndicator';
import { RedisHealthIndicator } from './health/RedisHealthIndicator';

@Module({
  imports: [
    HealthModule.withIndicators([DatabaseHealthIndicator, RedisHealthIndicator]),
  ],
})
export class AppModule {}

Implementing a Health Indicator

Each indicator implements the IHealthIndicator interface:

import { Injectable } from '@nestjs/common';
import type { IHealthIndicator, IHealthCheckResult } from '@breadstone/archipel-platform-health';

@Injectable()
export class DatabaseHealthIndicator implements IHealthIndicator {
  public readonly name = 'database';

  public async isHealthy(): Promise<IHealthCheckResult> {
    try {
      await this._prisma.$queryRaw`SELECT 1`;
      return { status: 'up' };
    } catch (error) {
      return { status: 'down', details: { error: (error as Error).message } };
    }
  }
}

Using the Orchestrator

The HealthOrchestrator runs all registered indicators and returns aggregated results:

import { Controller, Get } from '@nestjs/common';
import { HealthOrchestrator } from '@breadstone/archipel-platform-health';

@Controller('health')
export class HealthController {
  constructor(private readonly _healthOrchestrator: HealthOrchestrator) {}

  @Get()
  public async check(): Promise<unknown> {
    return this._healthOrchestrator.check();
  }
}

---

Built-in Consumers

All Archipel platform libraries provide health indicators via their /health subpath export. Register them with HealthModule.withIndicators():

Library	Indicator	Key	Check
platform-database	DatabaseHealthIndicator	database	Prisma SELECT 1 ping
platform-blob-storage	BlobHealthIndicator	blob	HTTP ping to blob URL (or disabled if unconfigured)
platform-mailing	MailHealthIndicator	mail	Validates mail host, user, and port config
platform-caching	CachingHealthIndicator	caching	Always up
platform-queue	QueueHealthIndicator	queue	Always up
platform-payments	PaymentHealthIndicator	payment	up if PaymentClientPort injected, else disabled
platform-esigning	EsigningHealthIndicator	esigning	up if EsigningClientPort injected, else disabled
platform-intelligence	IntelligenceHealthIndicator	intelligence	up if IntelligenceCapabilityRegistry injected, else disabled
platform-analytics	AnalyticsHealthIndicator	analytics	up if AnalyticsClientPort injected, else disabled
platform-telemetry	TelemetryHealthIndicator	telemetry	up if OtelSdkHolder injected, else disabled
platform-authentication	AuthenticationHealthIndicator	authentication	Always up
platform-mcp	McpHealthIndicator	mcp	up if McpRegistryService injected, else disabled

See the Health Indicators guide for full setup instructions.

---

Interfaces

Interface	Description
IHealthIndicator	Contract for health check implementations (name + isHealthy)
IHealthCheckResult	Result object with status ('up' or 'down') and optional details

---

Tokens

Token	Description
HEALTH_INDICATORS	Multi-provider token for registering health indicators

---

Resource Bounds

The HealthOrchestrator enforces a maximum of 100 registered indicators. If the limit is exceeded, the indicator is skipped and a warning is logged.

---

API Reference

The auto-generated API reference is published when API docs are generated for this package.