Copy page

SDK Library

Glossary

Glossary

Relevant source files

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

• README.md
• package.json
• pnpm-lock.yaml
• src/config/config-loader.ts
• src/config/iconfig-entity.ts
• src/env/env-validator.ts
• src/http/health-check.ts
• src/http/http-server.ts
• src/index.ts
• src/lifecycle/graceful-shutdown.ts
• src/migrations/apply-patches.ts
• src/migrations/patch-naming.ts
• src/migrations/patch-registry.ts
• src/nats/nats-client.ts
• src/ports/config-repository-port.ts
• src/ports/database-port.ts
• src/ports/health-check-port.ts
• src/ports/service-registry-port.ts
• src/service/service-registrar.ts
• src/service/service-registry.ts

This glossary defines the core domain concepts, architectural patterns, and specific code entities used within the @primebrick/sdk. The SDK is designed to provide shared microservice infrastructure while remaining database-agnostic through the use of Ports.

Core Concepts

Port (Interface)

A Port is a TypeScript interface that defines a contract for an external dependency (like a database or a configuration store). The SDK depends on these interfaces rather than concrete implementations, following the Dependency Inversion Principle.

• Implementation: Microservices consuming the SDK must provide Adapters that implement these ports using their specific Data Access Layer (DAL).
• Key Ports:
  • ConfigRepositoryPort: For fetching configuration rows src/ports/config-repository-port.ts:1-7.
  • DatabasePort: For executing raw SQL and managing transactions during migrations src/ports/database-port.ts:1-12.
  • ServiceRegistryPort: For upserting service heartbeats src/ports/service-registry-port.ts:1-7.
  • HealthCheckPort: For verifying database connectivity src/ports/health-check-port.ts:1-3.

Sources: src/index.ts:18-22, README.md:5-7

Patch (Migration)

A Patch is a .sql file representing a discrete change to the database schema or data. Patches are idempotent and tracked via SHA-256 hashing.

• Patch ID: Derived from the filename (e.g., 20231027120000_create_users.sql becomes 20231027120000_create_users) src/migrations/patch-naming.ts:20-22.
• Registry: The primebrick_database_patches table (aliased as PATCH_REGISTRY_FQNAME) stores the record of applied patches src/migrations/patch-registry.ts:3-10.

Sources: src/migrations/apply-patches.ts:12-29, src/migrations/patch-naming.ts:24-26

---

Code Entity Map: Configuration & Environment

The following diagram bridges the natural language concepts of "Settings" and "Validation" to the specific classes and functions in the codebase.

Title: Configuration Data Flow

Code
graph TD
    subgraph "Natural Language Space"
        ENV["Environment Variables"]
        DB_CONF["Database Settings"]
    end

    subgraph "Code Entity Space"
        EV["validateEnv() / requireEnv()"]
        CL["ConfigLoader"]
        CE["IConfigEntity"]
        CRP["ConfigRepositoryPort"]
    end

    ENV -->|Validated by| EV
    DB_CONF -->|Represented as| CE
    CE -->|Fetched via| CRP
    CRP -->|Populates Cache in| CL
    CL -->|get / require| AppLogic["Application Logic"]

Sources: src/env/env-validator.ts:22-46, src/config/config-loader.ts:15-31, src/config/iconfig-entity.ts:10-19

Entity Definitions

Term	Code Symbol	Definition
Config Loader	ConfigLoader	A class that loads dictionary-style configuration from a database into an in-memory cache to eliminate hot-path DB hits src/config/config-loader.ts:15-18.
Config Entity	IConfigEntity	The shape of a configuration row, containing a key and a string value src/config/iconfig-entity.ts:10-19.
Env Schema	EnvSchema	A definition object specifying which environment variables are required and their default values src/env/env-validator.ts:1-7.

---

Code Entity Map: Lifecycle & Reliability

This diagram illustrates how the system manages service health and teardown, mapping operational states to code symbols.

Title: Lifecycle and Health Management

Code
graph LR
    subgraph "System State"
        STARTING["Starting"]
        RUNNING["Running"]
        STOPPING["Stopping"]
    end

    subgraph "Code Entities"
        SR["ServiceRegistrar"]
        HC["HealthCheck"]
        GS["GracefulShutdown"]
        HS["createHttpServer"]
    end

    STARTING --> SR
    SR -->|startHeartbeat| RUNNING
    RUNNING --> HC
    HC -->|/health| HS
    RUNNING -->|Signal/Error| GS
    GS -->|shutdown()| STOPPING
    STOPPING -->|process.exit| EXIT["Process Terminated"]

Sources: src/service/service-registrar.ts:1-20, src/http/health-check.ts:16-21, src/lifecycle/graceful-shutdown.ts:16-23, src/http/http-server.ts:17-22

Entity Definitions

Term	Code Symbol	Definition
Graceful Shutdown	GracefulShutdown	Manager that handles process signals (SIGTERM, SIGINT) and runs registered CleanupFn tasks in parallel via Promise.allSettled src/lifecycle/graceful-shutdown.ts:16-59.
Service Registrar	ServiceRegistrar	Manages service discovery by upserting the service's status and metadata into a central registry at regular intervals src/service/service-registrar.ts:21-40.
Health Check	HealthCheck	A utility that aggregates various system checks (DB connectivity, custom logic) to determine if the service is "healthy" or "degraded" src/http/health-check.ts:16-48.
NATS Client	NatsClient	A singleton manager for NATS/JetStream connections. It is an optional module requiring the nats peer dependency src/nats/nats-client.ts:1-15, package.json:34-39.

---

Technical Abbreviations

• DDL: Data Definition Language. Used in PATCH_REGISTRY_DDL to define the schema for tracking migrations src/migrations/patch-registry.ts:3-10.
• FQNAME: Fully Qualified Name. Refers to the schema-qualified table name for the patch registry (public.primebrick_database_patches) src/migrations/patch-registry.ts:12.
• SHA: Secure Hash Algorithm. Specifically sha256Hex is used to ensure the immutability of database patches src/migrations/patch-naming.ts:24-26.

Sources: src/migrations/patch-registry.ts:1-12, src/migrations/patch-naming.ts:1-26