Appendix A: Glossary and Indexes
A.1 Term Definitions
| Term | Definition |
|---|---|
| Atlas | A declarative database schema management tool used alongside Prisma Migrate for schema evolution in the platform. |
| Coexistence period | The time during which both Prisma Client and Kysely operate simultaneously within backend-main, with each endpoint assigned to one query path. |
| Dual-execution mode | A validation technique where both the Prisma and Kysely paths execute for the same request; the Prisma result serves the response while the Kysely result is compared offline. |
| Kysely | A type-safe TypeScript SQL query builder that compiles typed query expressions to parameterized SQL without an intermediary engine process. |
pg (node-postgres) | A PostgreSQL client library for Node.js that provides the wire protocol implementation and connection pool (pg.Pool) used by Kysely's PostgresDialect. |
pg.Pool | The connection pool provided by the pg driver, managing a bounded set of PostgreSQL connections shared across all tenant queries in the target architecture. |
| PgBouncer | A connection pooler for PostgreSQL that mediates client connections to the database, supporting transaction and session pool modes. |
| Prisma Client | An auto-generated ORM client that provides a TypeScript query API over PostgreSQL; the current query engine for tenant SQL operations. |
| Prisma Engine | A Rust-based binary that Prisma Client uses internally for query generation, connection management, and result serialization. |
| Prisma Migrate | A schema migration tool that generates and applies DDL changes based on the Prisma schema definition files. |
PrismaManager | A static singleton in @pnats/schema-manager that caches TenantPrismaClient instances per tenant ID and manages tenant schema creation and migrations. |
PrismaService | A NestJS injectable service in @pnats/schema-manager that provides getClient(tenantId) for tenant-scoped Prisma access and manages ATS-main and tenant SQL clients. |
| Query-layer overhead | The latency contribution of the query generation, serialization, and engine processing that occurs between the application query API call and SQL dispatch to the database. |
| Relation hydration | The process of composing multi-table queries to produce nested object graphs matching the response shape expected by API consumers. |
| Schema-per-tenant | A multi-tenant isolation pattern where each tenant's data resides in a dedicated PostgreSQL schema named by the tenant's identifier. |
search_path | A PostgreSQL session variable that determines schema resolution order for unqualified table references. |
TenantPrismaClient | The Prisma-generated client for the tenant SQL database, instantiated per tenant and cached in PrismaManager.tenantClients. |
withSchema() | A Kysely method that returns a schema-qualified query builder, prefixing all table references with the specified schema name in generated SQL. |
A.2 ADR Index
| ADR | Decision | Rationale | Defined In |
|---|---|---|---|
| ADR-001 | Adopt Kysely as the replacement query builder for tenant SQL | 6.2.1 | 2.1 |
| ADR-002 | Use withSchema() for per-query multi-tenant isolation | 6.2.1 | 2.3 |
| ADR-003 | Reject Drizzle ORM due to schema-scoping maturity concerns | 6.2.2 | 2.3 |
| ADR-004 | Reject raw SQL due to type safety violations | 6.2.3 | 2.3 |
| ADR-005 | Reject TypeORM due to runtime overhead reintroduction | 6.2.4 | 2.3 |
| ADR-006 | Retain Prisma Migrate and Atlas for schema migration | — | 2.1.6 |
| ADR-007 | Consolidate connection pooling to a shared pg.Pool | 6.2.1 | 2.1.5 |
| ADR-008 | Phased migration with dual-path coexistence | — | 5.1 |
A.3 Invariant Index
| Invariant | Title | Section |
|---|---|---|
| 1 | Type Safety | 2.3 |
| 2 | Multi-Tenant Isolation | 2.3 |
| 3 | Feature Parity | 2.3 |
| 4 | Zero Data Regression | 2.3 |
| 5 | Rollback Capability | 2.3 |
| 6 | Connection Pool Stability | 2.3 |
A.4 Diagram Index
| Diagram | Type | Section | Description |
|---|---|---|---|
| Figure 3-1 | flowchart | 3.1 | Target architecture showing dual query paths, connection layers, and poolers |