Copy page

SDK Library

Getting Started

Getting Started

Relevant source files

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

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

The @primebrick/sdk provides a shared infrastructure foundation for Primebrick v3 microservices. It is designed around the Hexagonal Architecture (Ports and Adapters) pattern, ensuring the SDK remains agnostic of specific database drivers or transport implementations while providing robust lifecycle management, configuration, and messaging utilities.

1. Installation

The SDK is published as a public scoped package. It utilizes a peer-dependency model for the NATS messaging client to keep the core bundle lightweight for services that do not require pub/sub capabilities.

Install the Package

Code
pnpm add @primebrick/sdk

Peer Dependency: NATS

If your microservice requires NATS connectivity, you must explicitly install the nats package. The SDK defines this as an optional peer dependency.

Code
pnpm add nats

Sources:

• package.json:2-3 (Package name and version)
• package.json:34-39 (NATS peer dependency configuration)
• src/index.ts:49-50 (NATS client export note)

---

2. Implementing Port Adapters

The SDK does not include a database driver. Instead, it defines Ports (interfaces) that the consuming microservice must implement using its preferred Data Access Layer (DAL), such as Drizzle, Prisma, or raw SQL drivers.

Required Port Interfaces

To use the SDK's core features (Migrations, Config, Service Registration), you must implement the following:

Port	Purpose	Required For
DatabasePort	Execute raw SQL and check DB health.	applyPatches, HealthCheck
ConfigRepositoryPort	Fetch configuration rows from a table.	ConfigLoader
ServiceRegistryPort	Upsert service heartbeat and registration.	ServiceRegistrar
HealthCheckPort	Perform a "ping" or "select 1" on the DB.	HealthCheck, /health endpoint

Sources:

• src/index.ts:18-22 (Exported Port interfaces)
• README.md:7-7 (List of abstract contracts)

---

3. Service Startup & Wiring

Integrating the SDK into a microservice involves a specific sequence: validating environment variables, implementing the adapters, and initializing the SDK modules.

Initialization Data Flow

The following diagram illustrates how a consuming service wires its local adapters into the SDK's functional modules.

Diagram: Wiring Adapters to SDK Modules

Code
graph TD
    subgraph "Consuming Microservice"
        A["[AppEntry]"] --> B["[LocalAdapters]"]
        B -->|implements| C["[DatabasePort]"]
        B -->|implements| D["[ConfigRepositoryPort]"]
        B -->|implements| E["[ServiceRegistryPort]"]
    end

    subgraph "@primebrick/sdk Entities"
        C --> F["[applyPatches]"]
        D --> G["[ConfigLoader]"]
        E --> H["[ServiceRegistrar]"]
        I["[GracefulShutdown]"]
        J["[NatsClient]"]
    end

    A -->|orchestrates| F
    A -->|orchestrates| G
    A -->|orchestrates| H
    A -->|registers cleanup| I

Sources:

• src/index.ts:1-16 (Module map and architecture philosophy)
• README.md:5-17 (Overview of provided SDK utilities)

---

4. Implementation Example

Below is the standard lifecycle for wiring the SDK at service startup.

Step A: Environment Validation

Use requireEnv or validateEnv early in the process to fail-fast if the environment is misconfigured. Sources: src/index.ts:56-57, src/env/env-validator.ts:1-15

Step B: Setup Lifecycle Management

Initialize GracefulShutdown to handle OS signals (SIGTERM, SIGINT) and ensure resources like NATS or DB pools are closed correctly. Sources: src/index.ts:47-47, src/lifecycle/graceful-shutdown.ts:1-10

Step C: Run Migrations

Use applyPatches with your DatabasePort implementation to ensure the database schema is up to date before the service starts accepting traffic. Sources: src/index.ts:40-40, src/migrations/apply-patches.ts:1-20

Step D: Start HTTP & Health Checks

Initialize the HttpServer which provides the standard /health endpoint. Sources: src/index.ts:53-54, src/http/http-server.ts:1-10

---

5. Architectural Data Flow

The SDK acts as a bridge between the service logic and the external infrastructure. The consumer provides the "How" (the Adapter) while the SDK provides the "What" (the Logic).

Diagram: Request and Lifecycle Flow

Code
sequenceDiagram
    participant OS as "Operating System"
    participant App as "Microservice Entry"
    participant SDK as "@primebrick/sdk"
    participant DB as "Database (via Adapter)"

    App->>SDK: "validateEnv(schema)"
    App->>SDK: "GracefulShutdown.install()"
    App->>SDK: "applyPatches(DatabasePort, patches)"
    SDK->>DB: "SELECT version FROM primebrick_database_patches"
    DB-->>SDK: "Current Schema State"
    SDK->>DB: "EXECUTE [New Patches]"
    App->>SDK: "ConfigLoader.load(ConfigRepositoryPort)"
    App->>SDK: "ServiceRegistrar.startHeartbeat(ServiceRegistryPort)"
    OS->>SDK: "SIGTERM"
    SDK->>App: "Execute registered CleanupFn"
    App->>OS: "process.exit(0)"

Sources:

• src/lifecycle/graceful-shutdown.ts:1-40 (Signal handling and cleanup flow)
• src/migrations/apply-patches.ts:1-50 (Migration execution logic)
• src/service/service-registrar.ts:1-30 (Heartbeat and registration logic)

---