# Overview


`@primebrick/sdk` is the shared infrastructure SDK for Primebrick v3. It provides
the building blocks that every backend service and microservice needs: config
loading, service registration, NATS™ messaging, auth, JSON serialization, health
checks, graceful shutdown, env validation, and database migrations.

## Design principles

- **DB-agnostic** — the SDK depends on port interfaces, not on any specific DAL.
  Consumers provide adapters using their DAL of choice.
- **Framework-agnostic** — auth works with raw Node.js® HTTP, Express, and NATS™
  through a single `HeaderProvider` abstraction.
- **NATS™-first** — microservices register and heartbeat via NATS™, not via direct
  DB access. The BE subscribes to lifecycle events and persists them.
- **BigInt-safe** — all JSON serialization uses `ext-json` so `bigint` values
  survive the wire format without `number | bigint` ambiguity.
- **Optional Redis cache** — best-effort cache for hot single-row reads. The
  system is fully valid without it; if Redis is unavailable, reads fall through
  to the database with `warn` logs. See [Cache layer](cache-layer) for usage.

## Modules

| Module | What it does |
|--------|-------------|
| **auth** | JWT/OIDC verification, API keys, RBAC, session context (AsyncLocalStorage) |
| **nats** | Singleton NATS™ client with Ext-JSON publish/subscribe/request-reply |
| **service** | NATS™-based service registration, heartbeats, and lifecycle events |
| **json** | BigInt-safe JSON stringify/parse + Express middleware |
| **cache** | Optional Redis cache layer (`@Cached`, `@CacheKey`, `withCache`, `RedisCachePort`) |
| **http** | Minimal HTTP server with unified `/health` endpoint and RFC 7807 error responses |
| **config** | Dictionary-style config loader with in-memory cache + NATS™ `config.get` sharing |
| **lifecycle** | Graceful shutdown coordinator + consistent `[startup]` logging banner |
| **migrations** | SHA-256-enforced database patch runner |
| **env** | Environment variable validation |
| **sse** | Server-Sent Events writer, event bus, and NATS™→SSE bridge (BE only) |
| **presence** | Real-time collaboration awareness — who is viewing/editing an entity (BE only) |

## Architecture

<Mermaid chart={`flowchart LR
  subgraph BE["Backend (STANDALONE mode)"]
    BEAuth["verifyAuth()"]
    BEProxy["Proxy / serialize"]
    BESse["SSE + Presence"]
  end
  subgraph NATS["NATS"]
    Subjects["service.register\nservice.heartbeat\nservice.unregister\nemailsender.send\npresence.*.*\nentity.*.*.changed"]
  end
  subgraph US["Microservices (GATEWAY-RESOLVED mode)"]
    USAuth["verifyAuthGatewayResolved()"]
    USReg["ServiceRegistrar"]
  end
  BEAuth --> BEProxy
  BEProxy -->|"headers + gateway secret"| NATS
  NATS --> USAuth
  USReg -->|"publish lifecycle"| NATS
  NATS -->|"BE subscribes"| BE
  BESse -->|"presence + changed markers"| NATS
`} />

The BE validates JWTs against the IDP (STANDALONE mode), resolves users to
internal UUIDs, expands roles to permissions, then serializes the full
`AuthUser` into headers when proxying to microservices. Microservices
(GATEWAY-RESOLVED mode) verify the gateway secret and deserialize the
pre-resolved user — no DB access, no ports needed.

The BE also publishes presence deltas and entity-changed markers to NATS™
(`presence.{entityType}.{entityUuid}` and `entity.{entityType}.{entityUuid}.changed`),
bridges them to per-entity SSE event buses, and forwards them to connected FE
clients. See [Presence](presence) for the collaboration awareness contract.

## Quick start

The fastest way to verify a service built on the SDK is up is the `/health`
endpoint. Every service that uses `createHttpServer()` exposes it, and the BE
exposes it at `/api/v1/health`.

```bash
# Microservice (US) — uses createHttpServer() from the SDK
curl http://localhost:3002/health
```

```json
{
  "ok": true,
  "service": "emailsender",
  "version": "1.4.0",
  "url": "http://localhost:3002",
  "checks": {
    "db":   { "ok": true, "version": "18.0" },
    "nats": { "ok": true, "version": "2.14.3" },
    "redis":{ "ok": true, "version": "8.8.0" }
  }
}
```

If any check fails, `ok` is `false` and the HTTP status is `503`. The FE's 503
interceptor probes `/health` and shows the right health chip. See
[HTTP Server](http-server) for the full `HealthResponse` shape and
[Getting Started](getting-started) for the complete service bootstrap.

## Next steps

- [Getting Started](getting-started) — install and wire up the SDK
- [Authentication](authentication) — auth modes, RBAC, session context
- [NATS Client](nats-client) — publish/subscribe with Ext-JSON
- [Service Registration](service-registration) — NATS™-based lifecycle
- [Ext-JSON](ext-json) — BigInt-safe serialization
- [Cache layer](cache-layer) — optional Redis cache for hot single-row reads
- [HTTP Server](http-server) — unified health checks and RFC 7807 errors
- [SSE standard](sse-standard) — Server-Sent Events writer, event bus, NATS™ bridge
- [Presence](presence) — real-time collaboration awareness
- [API Reference](api-reference) — every exported symbol