Phase 3c : service Customers (capacité net-new moderne) + database-per-service

Author: wylson02

README.md

@@ -24,6 +24,7 @@ The interesting decisions are written down as ADRs, not buried in commits:
 - [ADR-0003 — YARP API gateway](docs/adr/0003-yarp-api-gateway.md)
 - [ADR-0004 — RabbitMQ event-driven messaging](docs/adr/0004-rabbitmq-eventing.md)
 - [ADR-0005 — SignalR real-time dashboard](docs/adr/0005-signalr-realtime.md)
+- [ADR-0006 — Database-per-service on a shared PostgreSQL server](docs/adr/0006-database-per-service.md)
 
 Full picture: [docs/architecture.md](docs/architecture.md).
 
@@ -48,7 +49,7 @@ Full picture: [docs/architecture.md](docs/architecture.md).
 | 0 | Foundations (repo, docs, ADRs, compose, CI) | ✅ done |
 | 1 | Legacy core: COBOL batch + data, containerized | ✅ runs today |
 | 2 | The bridge: COBOL → JSON over HTTP | ✅ done |
-| 3 | Microservices behind the gateway | 🟡 in progress (3a: gateway, 3b: accounts + strangler switch) |
+| 3 | Microservices behind the gateway | 🟡 in progress (3a: gateway, 3b: accounts + strangler switch, 3c: customers) |
 | 4 | Event-driven + real-time dashboard | ⬜ planned |
 | 5 | CI/CD hardening, observability, tests | ⬜ planned |
 
@@ -169,6 +170,40 @@ network.
 dotnet test src/CobraBridge.sln
 ```
 
+## Run the customers service (a net-new capability)
+
+Phase 3c adds **CustomersService**: customer profiles with KYC status. This
+one isn't a migration — the COBOL core never had a notion of "customer" or
+KYC at all, so there's nothing to strangle. It's a modern capability the
+mainframe simply couldn't offer, built straight on PostgreSQL behind the
+gateway, no legacy source, no switch.
+
+It follows database-per-service (see
+[ADR-0006](docs/adr/0006-database-per-service.md)): same Postgres server as
+AccountsService, separate database (`cobrabridge_customers` vs.
+`cobrabridge_accounts`).
+
+```bash
+# locally
+dotnet run --project src/CobraBridge.CustomersService
+
+# or as part of the full stack
+docker compose up -d legacy-core postgres bridge accounts-service customers-service gateway
+```
+
+```bash
+curl http://localhost:8090/api/customers
+curl http://localhost:8090/api/customers/CUST000003
+curl "http://localhost:8090/api/customers?kycStatus=Verified"
+```
+
+`customers-service` has no published port either — reached only through the
+gateway, like every other internal service.
+
+```bash
+dotnet test src/CobraBridge.sln
+```
+
 ## Repository layout
 
 ```

docker-compose.yml

@@ -1,9 +1,10 @@
 # CobraBridge — local orchestration.
-# Phase 1 (legacy-core), Phase 2 (bridge), and Phase 3a/b (gateway, postgres,
-# accounts-service, Strangler switch) run today. The gateway is the only
-# service with a published port: everything else is reachable only on the
-# internal compose network. Later phases are scaffolded and commented until
-# their services exist, so `docker compose up` always works.
+# Phase 1 (legacy-core), Phase 2 (bridge), and Phase 3a/b/c (gateway,
+# postgres, accounts-service, Strangler switch, customers-service) run
+# today. The gateway is the only service with a published port: everything
+# else is reachable only on the internal compose network. Later phases are
+# scaffolded and commented until their services exist, so
+# `docker compose up` always works.
 
 services:
   legacy-core:
@@ -30,22 +31,26 @@ services:
     depends_on:
       - legacy-core
 
-  # --- Phase 3b: PostgreSQL for the modern AccountsService ---
+  # --- Phase 3b/c: PostgreSQL, shared server, one database per service ---
+  # (see docs/architecture.md and ADR-0006). POSTGRES_DB creates
+  # "cobrabridge_accounts"; postgres/init/01-create-customers-db.sql creates
+  # "cobrabridge_customers" the first time the data volume initializes.
   postgres:
     image: postgres:16
     container_name: cobrabridge-postgres
     environment:
       # Dev-only default credentials — never used outside this local/demo
       # stack. Override via POSTGRES_PASSWORD if that ever matters here.
-      - POSTGRES_DB=cobrabridge
+      - POSTGRES_DB=cobrabridge_accounts
       - POSTGRES_USER=cobrabridge
       - POSTGRES_PASSWORD=cobrabridge_dev_only_change_me
     volumes:
       - postgres-data:/var/lib/postgresql/data
-    # No published port: internal-only, reached by accounts-service via the
-    # "postgres" service name on the compose network.
+      - ./postgres/init:/docker-entrypoint-initdb.d:ro
+    # No published port: internal-only, reached by accounts-service and
+    # customers-service via the "postgres" service name on the compose network.
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U cobrabridge -d cobrabridge"]
+      test: ["CMD-SHELL", "pg_isready -U cobrabridge"]
       interval: 5s
       timeout: 5s
       retries: 10
@@ -58,7 +63,7 @@ services:
     image: cobrabridge-accounts-service
     container_name: cobrabridge-accounts-service
     environment:
-      - ConnectionStrings__Accounts=Host=postgres;Port=5432;Database=cobrabridge;Username=cobrabridge;Password=cobrabridge_dev_only_change_me
+      - ConnectionStrings__Accounts=Host=postgres;Port=5432;Database=cobrabridge_accounts;Username=cobrabridge;Password=cobrabridge_dev_only_change_me
       - Legacy__AccountsFile=/legacy/data/ACCOUNTS.DAT
     volumes:
       # read-only access to the legacy master, for the one-time seed migration
@@ -71,12 +76,28 @@ services:
       legacy-core:
         condition: service_completed_successfully
 
-  # --- Phase 3a/b: API gateway (YARP) — the single public entry point ---
+  # --- Phase 3c: the Customers service (PostgreSQL-backed, net-new) ---
+  customers-service:
+    build:
+      context: ./src/CobraBridge.CustomersService
+    image: cobrabridge-customers-service
+    container_name: cobrabridge-customers-service
+    environment:
+      - ConnectionStrings__Customers=Host=postgres;Port=5432;Database=cobrabridge_customers;Username=cobrabridge;Password=cobrabridge_dev_only_change_me
+    # No published port: internal-only, reached by the gateway via the
+    # "customers-service" service name on the compose network.
+    depends_on:
+      postgres:
+        condition: service_healthy
+
+  # --- Phase 3a/b/c: API gateway (YARP) — the single public entry point ---
   # AccountsSource picks which backend answers /api/accounts: "legacy" (the
   # Bridge/COBOL, the default below) or "modern" (accounts-service/Postgres).
   # Flip it with: docker compose up -d --build --force-recreate
   #               -e ACCOUNTS_SOURCE=modern gateway
   # or simpler: ACCOUNTS_SOURCE=modern docker compose up -d gateway
+  # /api/customers has no such switch — it's a net-new capability with a
+  # single backend (customers-service), not a legacy/modern migration.
   gateway:
     build: ./src/CobraBridge.Gateway
     image: cobrabridge-gateway
@@ -85,17 +106,18 @@ services:
       - AccountsSource=${ACCOUNTS_SOURCE:-legacy}
       - Services__Bridge=http://bridge:8080/
       - Services__AccountsService=http://accounts-service:8080/
+      - ReverseProxy__Clusters__customers-svc__Destinations__d1__Address=http://customers-service:8080/
     ports:
       # Host 8080 is taken by an unrelated local container on this machine;
       # the gateway still listens on 8080 inside its own container.
       - "8090:8080"
     depends_on:
       - bridge
       - accounts-service
+      - customers-service
 
-  # --- Phase 3c/d: microservices behind the gateway ---
+  # --- Phase 3d: microservices behind the gateway ---
   # transactions-svc: { }
-  # customers-svc:  { }
 
   # --- Phase 4: messaging + dashboard ---
   # rabbitmq:       { image: rabbitmq:3-management }

docs/adr/0006-database-per-service.md

@@ -0,0 +1,43 @@
+# ADR-0006 — Database-per-service on a shared PostgreSQL server
+
+**Status:** Accepted
+**Date:** 2026-06-19
+
+## Context
+
+With AccountsService (Phase 3b) and CustomersService (Phase 3c), CobraBridge
+now has two independent microservices that both need PostgreSQL. They have
+no business sharing data directly — AccountsService never needs a customer's
+KYC status, CustomersService never needs an account balance. The only
+sanctioned integration point is the gateway/HTTP boundary.
+
+## Decision
+
+Each service owns **its own database** — `cobrabridge_accounts`,
+`cobrabridge_customers` — created on **one shared PostgreSQL server**
+(one `postgres` container in docker-compose, not one container per service).
+A service only ever holds a connection string to its own database; nothing
+queries across databases.
+
+This is the standard "database-per-service" microservices pattern, scoped
+down for a local/demo footprint: it gets the structural isolation (each
+service's schema can evolve independently, no hidden coupling through
+shared tables) without paying for N separate Postgres processes on a
+developer laptop.
+
+## Consequences
+
+- **Positive:** each service's EF Core migrations are independent — adding
+  a column to `customers` can never accidentally affect `accounts`.
+- **Positive:** matches how this would actually scale: moving a service's
+  database to its own server later is a connection-string change, not a
+  schema untangling exercise.
+- **Positive:** makes the "no cross-service queries" rule structurally true
+  rather than just a convention someone could quietly violate with a join.
+- **Neutral:** still one Postgres *process* to operate locally — full
+  process-per-service isolation (separate containers, separate failure
+  domains) is a later, real-infra concern, not a local-dev one.
+- **Negative:** the one-time database creation now needs an init step
+  (`postgres/init/*.sql`, run by the official Postgres image on first boot)
+  instead of relying on `POSTGRES_DB` alone — one extra moving part to keep
+  in sync when a future service needs its own database.

docs/architecture.md

@@ -67,7 +67,7 @@ Strangler Fig story into something a recruiter can *see* in ten seconds.
 | 0 | Foundations: repo, docs, ADRs, docker-compose skeleton, CI | **done** |
 | 1 | Legacy core: GnuCOBOL batch + fixed-width data (containerized) | **done** |
 | 2 | The bridge (ACL): C# service wrapping COBOL, first modern endpoint | **done** |
-| 3 | Microservices behind the YARP gateway | **in progress (3a: gateway, 3b: accounts + strangler switch)** |
+| 3 | Microservices behind the YARP gateway | **in progress (3a: gateway, 3b: accounts + strangler switch, 3c: customers)** |
 | 4 | Event-driven + real-time React/SignalR dashboard | planned |
 | 5 | CI/CD hardening, observability, tests, polish | planned |
 
@@ -80,8 +80,46 @@ Phase 3b delivered the modern side of the swap and the Strangler switch
 itself — see below. The shared `Account` model, `FixedWidthAccountParser`,
 and the legacy-file path resolver moved out of the Bridge into
 `CobraBridge.Domain` so AccountsService could reuse them instead of
-duplicating them. Phases 3c–d (transactions, customers microservices) are
-not built yet.
+duplicating them.
+
+Phase 3c delivered CustomersService — see "Migration vs. net-new" below.
+Phase 3d (transactions microservice) is not built yet.
+
+## Migration vs. net-new
+
+Not every capability behind the gateway is a Strangler migration of
+something COBOL already did. CobraBridge deliberately has both kinds, side
+by side, because that's what real modernization looks like:
+
+```
+Migrated (Strangler):  /api/accounts
+  COBOL already does this -> Bridge parses it live, AccountsService holds a
+  migrated copy in Postgres, AccountsSource picks which one answers. The
+  point is the *swap* being invisible to the client.
+
+Net-new (no legacy equivalent): /api/customers
+  COBOL never had this -> CustomersService is the only and original source.
+  There is nothing to migrate, nothing to strangle, no AccountsSource-style
+  switch — just one backend behind the gateway, like any other service
+  would be in a system built from scratch.
+```
+
+Conflating the two would misrepresent both: claiming `/api/customers` was
+"migrated" would invent a legacy capability that never existed, and treating
+`/api/accounts` as plain net-new work would hide the actual hard part — the
+anti-corruption layer and the live cutover. The gateway config says so
+explicitly (see `customers-svc` cluster comments in
+`src/CobraBridge.Gateway/appsettings.json`).
+
+## Database-per-service (Phase 3b/3c)
+
+AccountsService and CustomersService each own their own PostgreSQL
+database — `cobrabridge_accounts` and `cobrabridge_customers` — on one
+shared Postgres server (see [ADR-0006](adr/0006-database-per-service.md)).
+Neither service ever queries the other's database; the gateway/HTTP
+boundary is the only sanctioned integration point. `postgres/init/*.sql`
+creates the second database the first time the data volume initializes
+(`POSTGRES_DB` only creates one).
 
 ## The Strangler switch (Phase 3b)
 
@@ -122,18 +160,21 @@ for the full walkthrough.
 ```
 cobrabridge/
 ├── README.md
-├── docker-compose.yml          # orchestrates the whole system locally
+├── docker-compose.yml                 # orchestrates the whole system locally
+├── postgres/init/                     # one-time DB-per-service creation scripts
 ├── docs/
-│   ├── architecture.md         # this file
-│   └── adr/                    # architecture decision records
-├── legacy-core/                # the COBOL "mainframe" (Phase 1, runs today)
-├── src/                              # .NET solution (gateway, services, bridge)
-│   ├── CobraBridge.Domain/             # shared Account model, legacy parser, path resolver
-│   ├── CobraBridge.Domain.Tests/       # parser + path resolver tests
-│   ├── CobraBridge.Bridge/             # anti-corruption layer (Phase 2, done)
-│   ├── CobraBridge.AccountsService/    # modern accounts API (Phase 3b, Postgres-backed)
-│   ├── CobraBridge.AccountsService.Tests/ # mapper, seeder, endpoint, legacy/modern equivalence tests
-│   ├── CobraBridge.Gateway/            # YARP API gateway + Strangler switch (Phase 3a/3b)
-│   └── CobraBridge.Gateway.Tests/      # health, routing, and switch tests for the gateway
+│   ├── architecture.md                # this file
+│   └── adr/                           # architecture decision records
+├── legacy-core/                       # the COBOL "mainframe" (Phase 1, runs today)
+├── src/                                  # .NET solution (gateway, services, bridge)
+│   ├── CobraBridge.Domain/                 # shared Account model, legacy parser, path resolver
+│   ├── CobraBridge.Domain.Tests/           # parser + path resolver tests
+│   ├── CobraBridge.Bridge/                 # anti-corruption layer (Phase 2, done)
+│   ├── CobraBridge.AccountsService/        # modern accounts API (Phase 3b, migrated, Postgres-backed)
+│   ├── CobraBridge.AccountsService.Tests/  # mapper, seeder, endpoint, legacy/modern equivalence tests
+│   ├── CobraBridge.CustomersService/       # customer/KYC API (Phase 3c, net-new, Postgres-backed)
+│   ├── CobraBridge.CustomersService.Tests/ # mapper, seeder, endpoint, KYC-filter tests
+│   ├── CobraBridge.Gateway/                # YARP API gateway + Strangler switch (Phase 3a/3b/3c)
+│   └── CobraBridge.Gateway.Tests/          # health, routing, and switch tests for the gateway
 └── .github/workflows/ci.yml    # build + test pipeline
 ```

postgres/init/01-create-customers-db.sql

@@ -0,0 +1,7 @@
+-- Database-per-service (see docs/architecture.md and ADR-0006): each
+-- service owns its own database on this one shared Postgres server.
+-- POSTGRES_DB (docker-compose) creates "cobrabridge_accounts" for
+-- AccountsService automatically; this script creates the second database,
+-- for CustomersService. Runs once, only when the postgres-data volume is
+-- first initialized.
+CREATE DATABASE cobrabridge_customers;

src/CobraBridge.AccountsService/Program.cs

@@ -15,9 +15,11 @@
 });
 
 // Dev-only default credentials — never used outside this local/demo stack.
-// docker-compose and any real deployment override this via ConnectionStrings__Accounts.
+// Database-per-service: "cobrabridge_accounts" is this service's own
+// database (see docs/architecture.md). docker-compose and any real
+// deployment override this via ConnectionStrings__Accounts.
 var connectionString = builder.Configuration.GetConnectionString("Accounts")
-    ?? "Host=localhost;Port=5432;Database=cobrabridge;Username=cobrabridge;Password=cobrabridge_dev_only_change_me";
+    ?? "Host=localhost;Port=5432;Database=cobrabridge_accounts;Username=cobrabridge;Password=cobrabridge_dev_only_change_me";
 
 builder.Services.AddDbContext<AccountsDbContext>(options => options.UseNpgsql(connectionString));
 

src/CobraBridge.AccountsService/appsettings.json

@@ -8,9 +8,12 @@
   "AllowedHosts": "*",
 
   // Dev-only default credentials for the local/demo Postgres instance.
-  // Never used outside this project's compose stack; override in real
-  // deployments via the ConnectionStrings__Accounts env var.
+  // Database-per-service: "cobrabridge_accounts" is this service's own
+  // database, separate from CustomersService's "cobrabridge_customers", on
+  // the same Postgres server. Never used outside this project's compose
+  // stack; override in real deployments via the ConnectionStrings__Accounts
+  // env var.
   "ConnectionStrings": {
-    "Accounts": "Host=localhost;Port=5432;Database=cobrabridge;Username=cobrabridge;Password=cobrabridge_dev_only_change_me"
+    "Accounts": "Host=localhost;Port=5432;Database=cobrabridge_accounts;Username=cobrabridge;Password=cobrabridge_dev_only_change_me"
   }
 }

src/CobraBridge.CustomersService.Tests/CobraBridge.CustomersService.Tests.csproj

@@ -0,0 +1,29 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+
+    <IsPackable>false</IsPackable>
+    <IsTestProject>true</IsTestProject>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="coverlet.collector" Version="6.0.0" />
+    <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="8.0.11" />
+    <PackageReference Include="Microsoft.EntityFrameworkCore.InMemory" Version="8.0.10" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
+    <PackageReference Include="xunit" Version="2.5.3" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="2.5.3" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Using Include="Xunit" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\CobraBridge.CustomersService\CobraBridge.CustomersService.csproj" />
+  </ItemGroup>
+
+</Project>