Copy page

SDK Library

Overview

Overview

Relevant source files

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

• README.md
• package.json
• src/index.ts

The @primebrick/sdk package provides shared microservice infrastructure for the Primebrick v3 ecosystem. Its primary goal is to standardize common cross-cutting concerns—such as configuration loading, database migrations, service registration, and lifecycle management—while remaining strictly decoupled from specific database drivers or business logic.

The SDK is built on the Ports and Adapters (Hexagonal) architecture pattern. By defining abstract interfaces (Ports) for external dependencies, the SDK allows consuming microservices to provide their own implementations (Adapters) using whatever Data Access Layer (DAL) or database technology they prefer.

System Purpose & Core Philosophy

The SDK serves as the foundational backbone for microservices, ensuring that every service follows a consistent operational pattern:

• Zero Direct Dependencies: The SDK has no mandatory runtime dependencies on database drivers or specific frameworks package.json:33.
• Dependency Inversion: Consumers implement port interfaces to bridge the SDK with their chosen persistence layer src/index.ts:4-5.
• Graceful Resilience: Built-in support for signal handling, parallel resource cleanup, and idempotent migrations README.md:10-13.
• Type Safety: First-class TypeScript support with exported interfaces for all configuration and registry entities src/index.ts:18-58.

High-Level Architecture

The following diagram illustrates how the SDK sits between the Microservice logic and external infrastructure through the use of Port interfaces.

SDK Integration Pattern

Code
graph TD
    subgraph "Microservice (Consumer)"
        ServiceLogic["Service Logic"]
        Adapters["Adapters (Impl Ports)"]
    end

    subgraph "@primebrick/sdk"
        direction TB
        Ports["Port Interfaces"]
        Modules["Core Modules (Config, Migrations, etc.)"]
    end

    subgraph "External Infrastructure"
        DB[("Database (PostgreSQL, SQLite, etc.)")]
        NATS["NATS Broker"]
    end

    ServiceLogic --> Modules
    Modules -.-> Ports
    Adapters -- "Implements" --> Ports
    Adapters --> DB
    Modules -.-> NATS

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

Module Map

The SDK is organized into several functional modules, each addressing a specific microservice requirement:

Module	Primary Responsibility	Key Entities
Ports	Abstract contracts for external systems.	ConfigRepositoryPort, DatabasePort, ServiceRegistryPort, HealthCheckPort
Config	Database-backed configuration with in-memory caching.	ConfigLoader, IConfigEntity
Migrations	SHA256-based idempotent database patch runner.	applyPatches, PATCH_REGISTRY_DDL
Service	Service discovery and heartbeat management.	ServiceRegistrar, IServiceRegistry
Lifecycle	Signal handling and graceful shutdown orchestration.	GracefulShutdown
HTTP	Lightweight health check server.	createHttpServer, HealthCheck
Env	Centralized environment variable validation.	validateEnv, requireEnv
NATS	Singleton management for NATS messaging.	NatsClient

Sources: src/index.ts:18-58, README.md:5-17

Integration Flow

When a microservice starts, it typically follows this integration sequence using the SDK:

1. Environment Validation: Use requireEnv to ensure all necessary process.env variables are present src/index.ts:57.
2. Port Implementation: The service creates classes or objects that satisfy the Port interfaces (e.g., a DatabasePort implementation using Drizzle or Prisma).
3. Bootstrap:
   • Initialize ConfigLoader to fetch runtime settings src/index.ts:26.
   • Execute applyPatches to ensure the database schema is up to date src/index.ts:40.
   • Register the service instance via ServiceRegistrar to start heartbeats src/index.ts:44.
4. Lifecycle Setup: Install GracefulShutdown handlers to manage SIGTERM and SIGINT signals src/index.ts:47.

Entity Mapping: Code to Infrastructure

Code
graph LR
    subgraph "Code Entities"
        SR["ServiceRegistrar"]
        CL["ConfigLoader"]
        MR["applyPatches"]
    end

    subgraph "Data Structures"
        ISR["IServiceRegistry (Table)"]
        ICE["IConfigEntity (Table)"]
        PRD["PATCH_REGISTRY_DDL"]
    end

    SR -- "updates" --> ISR
    CL -- "reads" --> ICE
    MR -- "creates/tracks" --> PRD

Sources: src/index.ts:25-44, src/migrations/patch-registry.ts:30-31

Next Steps

To dive deeper into specific areas of the SDK, refer to the following sections:

• Getting Started: A step-by-step guide on installing the package, handling the nats peer dependency, and wiring the SDK into a new service.
• Architecture: Ports & Adapters: A detailed look at the hexagonal design, the specific port contracts, and how to write custom adapters.
• Core Modules: Detailed documentation for each individual module (Config, Migrations, Lifecycle, etc.).

---