# Core Modules

# Core Modules

<details>
<summary>Relevant source files</summary>

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

- [README.md](README.md)
- [src/index.ts](src/index.ts)

</details>



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**
```mermaid
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](#2.1).

**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](#2.2).

**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](#2.3).

**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](#2.4).

**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](#2.5).

**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](#2.6).

**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](#2.7).

**Sources:** [src/nats/nats-client.ts:1-15]()

---