# Getting Started

# Getting Started

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

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

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

</details>



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
```bash
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.
```bash
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**
```mermaid
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**
```mermaid
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)

---