arch(blueprints): unify database engine to SQL Server 2022 and map service entities

Author: beyondnetPeru

architecture/adrs/0026-authoritative-database-engine-strategy.md

@@ -1,32 +1,34 @@
-# ADR 0026: Authoritative Database Engine Strategy by Language Stack
+# ADR 0026: Authoritative Unified Database Engine Strategy
 
 ## Status
-Proposed
+Approved
 
 ## Context
-As the UMS project evolves into an enterprise-grade monorepo and migrates core components to .NET 8, it is necessary to standardize the database engine preferences to optimize for ecosystem alignment, performance, and maintainability across different language stacks.
+As the UMS project evolves into an enterprise-grade monorepo, it is necessary to standardize the database engine to optimize for operational simplicity, cross-service data integrity, and corporate licensing alignment. 
 
-Previously, PostgreSQL was used as the default relational engine for both Node.js and .NET prototypes. However, corporate standards for .NET excellence prioritize SQL Server for mission-critical .NET applications.
+Previously, a polyglot engine strategy was proposed (SQL Server for .NET and PostgreSQL/MongoDB for Node.js). However, managing multiple database engines in production—especially in on-premise or localized deployments—increases infrastructure overhead, security complexity (multiple RLS implementations), and total cost of ownership.
 
 ## Decision
-We will adopt a polyglot-aware database strategy based on the primary language of the application service:
+We will adopt a **Unified Database Strategy** for all services within the UMS product ecosystem:
 
-1.  **For .NET 8+ Applications (e.g., UMS Core API):**
-    *   **Relational Engine:** **SQL Server 2022** (Latest stable version).
-    *   **ORM:** Entity Framework Core (EF Core) with `Microsoft.EntityFrameworkCore.SqlServer`.
-    *   **Rationale:** Seamless integration with .NET ecosystem, superior tooling (SSMS/Azure Data Studio), and optimized execution plans for MediatR-based workloads.
+1.  **Unified Relational Engine:** **SQL Server 2022** (Standard or Enterprise).
+    *   **All runtimes** (.NET 8 Core API and Node.js/NestJS Satellite services) must persist their data exclusively in SQL Server 2022.
+    *   **Rationale:** Standardizing on a single engine allows for a unified Row-Level Security (RLS) implementation, simplified backup/restore procedures, and consistent execution plan analysis.
 
-2.  **For Node.js / NestJS Applications:**
-    *   **Relational Engine:** **PostgreSQL 16**.
-    *   **NoSQL Engine:** **MongoDB**.
-    *   **Rationale:** Community maturity, native JSONB support in PG, and high developer velocity in the Node.js ecosystem.
+2.  **Schema-per-Context Isolation:**
+    *   To maintain modularity, each Bounded Context will own a dedicated SQL Server Schema (e.g., `[ums_identity]`, `[ums_authz]`).
+    *   Direct cross-schema joins are discouraged in favor of domain events, but permitted for optimized read-only reporting views under strict governance.
 
-### Security Implementation
-*   **Row-Level Security (RLS):** For .NET/SQL Server services, RLS will be implemented using SQL Server **Security Policies** and **Inline Table-Valued Functions (iTVF)** for filtering, instead of PostgreSQL policies.
-*   **Multi-Tenancy:** The "Shared Database, Shared Schema" model remains mandatory, enforced via SQL Server RLS.
+3.  **ORM / Driver Support:**
+    *   **.NET 8**: Entity Framework Core with `Microsoft.EntityFrameworkCore.SqlServer`.
+    *   **Node.js / NestJS**: TypeORM or Prisma using the **`mssql`** driver.
+
+4.  **Security Implementation:**
+    *   **Unified RLS**: All services will utilize SQL Server **Security Policies** and **SESSION_CONTEXT** for multi-tenant isolation.
+    *   This eliminates the need to maintain parallel RLS logic for PostgreSQL.
 
 ## Consequences
-*   The UMS migration plan from NestJS (Node) to .NET 8 must be updated to replace Npgsql with the SQL Server provider.
-*   Local development environments (Docker Compose) will include a `mssql-server-linux` container for the .NET API.
-*   Architectural blueprints and technical inventories must be updated to reflect SQL Server as the authoritative engine for the .NET stack.
-*   Satellite systems inheriting from this reference architecture must follow these same engine preferences based on their language stack.
+*   **Correction**: All references to PostgreSQL or MongoDB for Node.js services in `stack.md` or earlier documentation are now deprecated.
+*   **Infrastructure**: Local development environments (Docker Compose) will only require a single `mssql-server-linux` instance.
+*   **Skill Set**: The team must ensure proficiency in T-SQL and SQL Server-specific performance tuning across all language stacks.
+*   **Migration**: Any existing Node.js prototypes using PostgreSQL must be migrated to SQL Server.

architecture/blueprints/service-entity-map.md

@@ -0,0 +1,59 @@
+# Service-Entity Map & Data Ownership
+
+This document serves as the authoritative mapping between system entities, their Bounded Contexts, owning services, and database schemas within the UMS enterprise ecosystem.
+
+---
+
+## 🏛️ 1. Entity Ownership & Schema Mapping
+
+| Entity | Bounded Context | Service Owner (Write) | Runtime | SQL Server Schema |
+| :--- | :--- | :--- | :--- | :--- |
+| **TENANT** | Identity | UMS Core API | .NET 8 | `[ums_identity]` |
+| **BRANCH** | Identity | UMS Core API | .NET 8 | `[ums_identity]` |
+| **USER_ACCOUNT** | Identity | UMS Core API | .NET 8 | `[ums_identity]` |
+| **ROLE** | Authorization | UMS Core API | .NET 8 | `[ums_authz]` |
+| **PROFILE** | Authorization | UMS Core API | .NET 8 | `[ums_authz]` |
+| **PROFILE_PERMISSION** | Authorization | UMS Core API | .NET 8 | `[ums_authz]` |
+| **PERMISSION_TEMPLATE** | Authorization | UMS Core API | .NET 8 | `[ums_authz]` |
+| **FUNCTIONAL_MODULE** | Authorization | UMS Core API | .NET 8 | `[ums_authz]` |
+| **FUNCTIONAL_SUBMODULE**| Authorization | UMS Core API | .NET 8 | `[ums_authz]` |
+| **FUNCTIONAL_OPTION** | Authorization | UMS Core API | .NET 8 | `[ums_authz]` |
+| **ACTION** | Authorization | UMS Core API | .NET 8 | `[ums_authz]` |
+| **SYSTEM_SUITE** | Authorization | UMS Core API | .NET 8 | `[ums_authz]` |
+| **ROLE_PROMOTION_CRITERIA**| IGA | IGA Satellite | NestJS | `[ums_iga]` |
+| **USER_PROMOTION_PROCESS** | IGA | IGA Satellite | NestJS | `[ums_iga]` |
+| **USER_MANAGEMENT_DELEGATION**| IGA | IGA Satellite | NestJS | `[ums_iga]` |
+| **DOCUMENT_TYPE** | Compliance | Compliance Satellite | NestJS | `[ums_compliance]` |
+| **USER_DOCUMENT** | Compliance | Compliance Satellite | NestJS | `[ums_compliance]` |
+| **NOTIFICATION_RULE** | Compliance | Compliance Satellite | NestJS | `[ums_compliance]` |
+| **ACCESS_ENFORCEMENT_POLICY**| Compliance | Compliance Satellite | NestJS | `[ums_compliance]` |
+| **APPROVAL_WORKFLOW** | Approvals | UMS Core API | .NET 8 | `[ums_approval]` |
+| **APPROVAL_REQUIRED_DOCUMENT**| Approvals | UMS Core API | .NET 8 | `[ums_approval]` |
+| **APPROVAL_REQUEST** | Approvals | UMS Core API | .NET 8 | `[ums_approval]` |
+| **APPROVAL_LOG** | Approvals | UMS Core API | .NET 8 | `[ums_approval]` |
+| **APP_CONFIGURATION** | Configuration | UMS Core API | .NET 8 | `[ums_config]` |
+
+---
+
+## 🛠️ 2. Data Access & Governance Rules
+
+1.  **Strict Write Ownership**: Only the **Service Owner** specified in the table above is allowed to perform `INSERT`, `UPDATE`, or `DELETE` operations on the corresponding entities.
+2.  **Cross-Service Reads (Read-Only)**:
+    *   Satellite services (NestJS) may perform `SELECT` operations on `ums_identity` and `ums_authz` schemas to resolve context, but must do so through optimized views or read-only database users.
+    *   Cross-service data dependency should ideally be resolved via **Domain Events** (Asynchronous) rather than direct cross-schema joins to maintain decoupling.
+3.  **Schema Isolation**: Each schema acts as a logical boundary. Permissions in SQL Server must be granted granularly per service account.
+
+---
+
+## ⚠️ 3. Explicit Correction: Database Engine Standardization
+
+> [!IMPORTANT]
+> **Unified Engine Strategy**: Although `architecture/blueprints/stack.md` and some early prototypes mention PostgreSQL for Node.js/NestJS components, the final authoritative decision for the UMS production product is **SQL Server 2022 for all services**, regardless of the runtime (.NET 8 or NestJS).
+>
+> **Action Required**: **ADR-0026** must be updated to reflect this unification, removing PostgreSQL and MongoDB from the relational/NoSQL requirements for this specific codebase.
+
+---
+
+## 🔗 4. References
+*   For the complete E/R diagram and relationship cardinality, refer to **[er-export-formats.md](er-export-formats.md)**.
+*   For technical implementation of Row-Level Security (RLS) in SQL Server, refer to the Identity Context documentation.

architecture/blueprints/stack.md

@@ -18,7 +18,7 @@
 *   **Team Expertise:** Strong NestJS & TypeScript/JavaScript, some DevOps (Docker, Kubernetes), no Java expertise
 *   **Existing Constraints:** Transitioning to .NET 8 for Core API, SQL Server relational engine, high-performance Redis cache, Dapr-ready architecture, strict on-premise K8s deployment capability.
 *   **Non-Negotiables:** Absolutely zero cloud-provider SDK dependencies in the core domain layer (strict Hexagonal Architecture); 100% self-hostable open-source infrastructure alternatives.
-*   **Polyglot Strategy (ADR 0026):** .NET 8 -> SQL Server; Node.js -> PostgreSQL/MongoDB.
+*   **Polyglot Strategy (ADR 0026):** .NET 8 (Core) & Node.js (Satellites) -> **Unified SQL Server 2022 Engine**.
 
 ---
 
@@ -97,7 +97,7 @@
 
 ### 4.1 Architectural Pattern
 *   **Chosen Tool:** **Hexagonal Architecture (Ports & Adapters) / Clean Architecture**
-*   **Why Chosen:** Mandated to ensure the core Domain layer has **absolutely zero dependencies** on NestJS, TypeORM, PostgreSQL, or external cloud SDKs. Core logic communicates exclusively with interfaces (Ports), making the kernel completely sovereign and future-proof.
+*   **Why Chosen:** Mandated to ensure the core Domain layer has **absolutely zero dependencies** on NestJS, TypeORM, SQL Server, or external cloud SDKs. Core logic communicates exclusively with interfaces (Ports), making the kernel completely sovereign and future-proof.
 *   **Alternatives Rejected:**
     *   *Standard 3-Tier Layered Architecture*: Creates strong coupling between business logic, database ORMs, and network frameworks, violating our non-negotiable sovereignty constraint.
 
@@ -109,7 +109,7 @@
 
 ### 4.3 CQRS Approach
 *   **Chosen Tool:** **Internal CQRS via NestJS CQRS module**
-*   **Why Chosen:** Decouples heavy permission graph compilation (Queries) from basic identity mutations (Commands), optimizing read performance. Caches read-projections in Redis while writing sequentially to PostgreSQL.
+*   **Why Chosen:** Decouples heavy permission graph compilation (Queries) from basic identity mutations (Commands), optimizing read performance. Caches read-projections in Redis while writing sequentially to **SQL Server 2022**.
 *   **Alternatives Rejected:**
     *   *Direct CRUD*: Directly querying and compiling relational tables on every read request degrades database performance under high concurrent loads.
 
@@ -118,12 +118,10 @@
 ## 5. Data Layer
 
 ### 5.1 Primary Database + ORM/Query Builder
-*   **For .NET 8 Services:** **SQL Server 2022 + Entity Framework Core (EF Core)**
-    *   **Why:** Official Microsoft support, tight ecosystem integration, and optimized RLS via `SESSION_CONTEXT`.
-*   **For Node.js Relational Services:** **PostgreSQL v16 + TypeORM / Drizzle**
-    *   **Why:** Robust native JSONB support and high maturity in the Node.js community.
-*   **For Node.js NoSQL Services:** **MongoDB (Atlas / Enterprise)**
-    *   **Why:** High flexibility for unstructured documents and rapid prototyping.
+*   **Unified Relational Engine:** **SQL Server 2022 (All Services)**
+    *   **For .NET 8 Services:** EF Core with SQL Server Provider.
+    *   **For Node.js Services:** TypeORM / Prisma with `mssql` driver.
+    *   **Why:** Official corporate standard, superior RLS via `SESSION_CONTEXT`, and operational simplicity for on-premise deployments.
 
 ### 5.2 Migration Strategy
 *   **Chosen Tool:** **TypeORM Migrations executed via K8s Init-Containers**
@@ -155,9 +153,8 @@
 
 ### 6.1 Isolation Model
 *   **Strategy:** **Shared Database with Native Row-Level Security (RLS)**
-*   **Implementation (SQL Server):** Uses `SESSION_CONTEXT('TenantId', @value)` and Security Policies with iTVF predicates.
-*   **Implementation (PostgreSQL):** Uses `SET LOCAL app.current_tenant = 'value'` and native `CREATE POLICY`.
-*   **Why Chosen:** High packing density and low administrative overhead while maintaining absolute isolation at the engine level.
+*   **Implementation (Unified):** Uses SQL Server `SESSION_CONTEXT('TenantId', @value)` and Security Policies with iTVF predicates for both .NET and Node.js.
+*   **Why Chosen:** High packing density and absolute isolation at the engine level with a single implementation to maintain.
 *   **Alternatives Rejected:**
     *   *Database-per-tenant*: High infrastructure cost and severe administrative overhead when managing thousands of databases.
     *   *Schema-per-tenant*: Becomes hard to scale and migrate when tenant counts exceed 1,000, causing connection pool exhaustion.
@@ -166,7 +163,7 @@
 *   **Chosen Tool:** **NestJS Interceptor + PostgreSQL Connection Session Context**
 *   **Why Chosen:** Resolves the `tenant_id` from JWT claims or `X-Tenant-ID` headers at ingress, and uses a database transaction wrapper to inject the tenant context into the active PostgreSQL session dynamically.
 *   **Alternatives Rejected:**
-    *   *Application-level filtering*: Prone to developer omissions (forgetting a `WHERE tenant_id = x` clause), leading to critical data leak vulnerabilities. RLS prevents this at the database level.
+    *   *Application-level filtering*: Prone to developer omissions (forgetting a `WHERE tenant_id = x` clause), leading to critical data leak vulnerabilities. RLS prevents this at the database level across all runtimes.
 
 ---
 
@@ -232,7 +229,7 @@
 
 ### 10.1 Local Development Setup
 *   **Chosen Tool:** **Docker Compose Spec**
-*   **Why Chosen:** Allows developers to spin up the entire UMS dependency suite (**SQL Server**, **PostgreSQL**, Redis, RabbitMQ, MinIO) locally with a single command (`docker compose up -d`).
+*   **Why Chosen:** Allows developers to spin up the entire UMS dependency suite (**SQL Server 2022**, Redis, RabbitMQ, MinIO) locally with a single command (`docker compose up -d`).
 
 ### 10.2 Monorepo vs. Multi-repo
 *   **Chosen Tool:** **Nx Monorepo**
@@ -241,7 +238,7 @@
 ### 10.3 Testing Pyramid
 *   **Chosen Tool:**
     *   *Unit Tests*: Jest (aiming for >80% coverage).
-    *   *Integration Tests*: Jest + Supertest with **Testcontainers** (spinning up ephemeral PostgreSQL and Redis instances in local Docker for realistic testing).
+    *   *Integration Tests*: Jest + Supertest with **Testcontainers** (spinning up ephemeral **SQL Server Edge/Express** and Redis instances in local Docker for realistic testing).
     *   *End-to-End*: Playwright for Web Console regression testing.
 
 ---
@@ -261,7 +258,7 @@ To avoid cloud-provider lock-in and support offline, on-premise environments, **
 
 | Component | Chosen Solution | Lock-in Risk | Mitigation Strategy | Re-evaluate Trigger |
 | :--- | :--- | :--- | :--- | :--- |
-| **Database** | PostgreSQL v16 | **Low** | Standard SQL compliance. Domain layer has no direct dependency (decoupled via Ports). | Exceeding 20 TB of active data |
+| **Database** | SQL Server 2022 | **Medium** | Standard SQL compliance. Domain layer has no direct dependency (decoupled via Ports). Use of RLS creates some lock-in. | Licensing cost change |
 | **Object Store** | MinIO | **Low** | MinIO uses the exact AWS S3 API contract. Swapping requires a simple config change. | Performance bottlenecks |
 | **Secrets Store**| HashiCorp Vault | **Low** | Secret resolution is abstracted via K8s secrets injection or custom Adapter. | Licensing model changes |
 | **Gateway** | Kong Gateway | **Low** | Configuration is managed via standard K8s Ingress resources. | Custom routing constraints |
@@ -275,10 +272,10 @@ To avoid cloud-provider lock-in and support offline, on-premise environments, **
 *   **Rationale:** Balances high-performance/safety requirements for the core with development speed for utilities.
 *   **Revisit When:** Organizational skills shift significantly or a unified single-runtime model is required.
 
-### Decision 2: Language-Driven Database Selection (ADR 0026)
-*   **Decision:** **SQL Server for .NET; PostgreSQL/Mongo for Node.**
-*   **Rationale:** Leverages the native strengths of each platform's driver and ecosystem support.
-*   **Revisit When:** Cross-service data sharing requires a single unified engine or licensing costs exceed budget.
+### Decision 2: Unified Database Engine (ADR 0026)
+*   **Decision:** **SQL Server 2022 for all services (.NET and Node.js).**
+*   **Rationale:** Eliminates infrastructure fragmentation and ensures unified security enforcement (RLS).
+*   **Revisit When:** Licensing costs exceed budget or a specific context requires native NoSQL features.
 
 ---