# Glossary # Glossary
Relevant source files The following files were used as context for generating this wiki page: - [README.md](README.md) - [package.json](package.json) - [pnpm-lock.yaml](pnpm-lock.yaml) - [src/config/config-loader.ts](src/config/config-loader.ts) - [src/config/iconfig-entity.ts](src/config/iconfig-entity.ts) - [src/env/env-validator.ts](src/env/env-validator.ts) - [src/http/health-check.ts](src/http/health-check.ts) - [src/http/http-server.ts](src/http/http-server.ts) - [src/index.ts](src/index.ts) - [src/lifecycle/graceful-shutdown.ts](src/lifecycle/graceful-shutdown.ts) - [src/migrations/apply-patches.ts](src/migrations/apply-patches.ts) - [src/migrations/patch-naming.ts](src/migrations/patch-naming.ts) - [src/migrations/patch-registry.ts](src/migrations/patch-registry.ts) - [src/nats/nats-client.ts](src/nats/nats-client.ts) - [src/ports/config-repository-port.ts](src/ports/config-repository-port.ts) - [src/ports/database-port.ts](src/ports/database-port.ts) - [src/ports/health-check-port.ts](src/ports/health-check-port.ts) - [src/ports/service-registry-port.ts](src/ports/service-registry-port.ts) - [src/service/service-registrar.ts](src/service/service-registrar.ts) - [src/service/service-registry.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** ```mermaid 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** ```mermaid 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]()