Copy page

SDK Library

Core Modules

Core Modules

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/index.ts

The @primebrick/sdk is organized into six functional modules that provide the foundational infrastructure for Primebrick v3 microservices. These modules are designed to be database-agnostic, relying on Port Interfaces defined in the src/ports/ directory to interact with external storage or specialized service logic.

Module Interaction Overview

The following diagram illustrates how the core modules interact within a typical microservice lifecycle, from environment validation to graceful shutdown.

Service Startup and Lifecycle Flow

Code
graph TD
    subgraph "Initialization Phase"
        ENV["env module"] -->|Validate| CFG["config module"]
        CFG -->|Load via Port| MIG["migrations module"]
    end

    subgraph "Runtime Phase"
        MIG -->|Apply Patches| SRV["service module"]
        SRV -->|Heartbeat| HTTP["http module"]
        HTTP -->|Health Check| NATS["nats module"]
    end

    subgraph "Termination Phase"
        SRV -.->|Stop| LIFE["lifecycle module"]
        NATS -.->|Close| LIFE
        HTTP -.->|Shutdown| LIFE
    end

    [GracefulShutdown]:::code --> LIFE
    [ConfigLoader]:::code --> CFG
    [ServiceRegistrar]:::code --> SRV
    [NatsClient]:::code --> NATS
    [createHttpServer]:::code --> HTTP

    classDef code font-family:monospace, font-weight:bold;

Sources: src/index.ts:7-16, README.md:5-17

---

2.1. Configuration Management

The config module provides a centralized, cached mechanism for managing application settings stored in a database. It uses the ConfigLoader class to fetch IConfigEntity objects through a ConfigRepositoryPort. This ensures that "hot path" configuration lookups are performed against an in-memory cache rather than hitting the database repeatedly.

For details, see Configuration Management.

Sources: src/config/config-loader.ts:1-10, src/config/iconfig-entity.ts:1-5, src/ports/config-repository-port.ts:1-5

---

2.2. Environment Validation

The env module replaces scattered process.env checks with a structured validation schema. Using validateEnv and requireEnv, developers can define required variables, default values, and human-readable descriptions. This module ensures that a microservice fails fast during the "Initialization Phase" if the environment is misconfigured.

For details, see Environment Validation.

Sources: src/env/env-validator.ts:1-20

---

2.3. Database Migrations

The migrations module implements a SHA-256-based idempotent patch runner. The applyPatches function manages the execution of SQL or logic updates by comparing local patch files against the primebrick_database_patches registry table. It prevents accidental re-runs and detects if a previously applied patch has been tampered with.

For details, see Database Migrations.

Sources: src/migrations/apply-patches.ts:1-10, src/migrations/patch-registry.ts:1-15, src/migrations/patch-naming.ts:1-10

---

2.4. Service Registration & Heartbeat

The service module handles service discovery and availability tracking. The ServiceRegistrar class registers the microservice instance into a service_registry table and maintains a recurring heartbeat. This allows the system to monitor the health and versioning of all active nodes in the cluster.

For details, see Service Registration & Heartbeat.

Sources: src/service/service-registrar.ts:1-15, src/service/service-registry.ts:1-10

---

2.5. Lifecycle & Graceful Shutdown

The lifecycle module manages the orderly termination of the process. The GracefulShutdown class intercepts system signals (e.g., SIGTERM) and executes registered CleanupFn callbacks in parallel. It includes a re-entrancy guard to ensure that cleanup logic is only triggered once, even if multiple signals are received.

For details, see Lifecycle & Graceful Shutdown.

Sources: src/lifecycle/graceful-shutdown.ts:1-20

---

2.6. HTTP Server & Health Checks

The http module provides a lightweight HttpServer factory and a HealthCheck utility. It automatically exposes a /health endpoint that aggregates status reports from the database (via HealthCheckPort) and other internal components to inform load balancers or orchestrators of the service's readiness.

For details, see HTTP Server & Health Checks.

Sources: src/http/http-server.ts:1-10, src/http/health-check.ts:1-15

---

2.7. NATS Messaging Client

The nats module provides a singleton NatsClient for managing connections to the NATS messaging server. It lazily initializes the connection using the NATS_URL environment variable and provides access to JetStream for event-driven architectures. It is designed as an optional peer dependency.

For details, see NATS Messaging Client.

Sources: src/nats/nats-client.ts:1-15

---