Domain Context Mapping and Integration Design

Wrote docs/architecture/tasks/banking-context-map-001/context-mapping/context-map-diagram.md. Complete strategic context mapping specification establishing upstream-downstream relationships, Anti-Corruption Layers, Open Host Service contracts, and team communication boundaries.

skill: context-mapping

Context Map Diagram Specification: Retail & Lending Integration [CMAP-FIN-001]

Summary

This specification establishes the strategic Context Map and integration relationship architecture for retail-lending-integration under run ID banking-context-map-001. It governs cross-boundary integrations between five autonomous bounded contexts (RetailDepositContext, CommercialLendingContext, CreditScoringContext, CustomerMasterContext, and CoreAccountingContext) across 65 microservices. It decisively eliminates the uncoordinated schema drift and cascading breakages demonstrated in incident INC-4919 (where upstream changes to retail transaction codes silently broke downstream loan underwriting covenants for 12 days). The specification defines explicit relationship patterns (Upstream-Downstream, Open Host Service / Published Language, Customer-Supplier, Anti-Corruption Layer, and Separate Ways), formalizes cross-context ubiquitous language translations, mandates in-process translation adapters, and eliminates direct shared database tables.

Detailed Description

Without explicit strategic context maps, distributed services develop tangled integration patterns. Downstream teams unwittingly conform to upstream data structures, importing foreign domain concepts and creating tight operational coupling. A formal Context Map classifies the power dynamics, organizational relationships, and technical integration seams between collaborating bounded contexts.

                  [ CustomerMasterContext ] (Upstream - OHS/PL)
                              │
               ┌──────────────┴──────────────┐
               ▼ (Customer-Supplier / ACL)   ▼ (Conformist)
    [ RetailDepositContext ]     [ CommercialLendingContext ]
               │                             │
               ▼ (Upstream: OHS/PL)          ▼ (Downstream: Customer-Supplier + ACL)
    [ CoreAccountingContext ] ◄──────────────┘
               ▲
               │ (Separate Ways / Cold Batch Sync)
    [ CreditScoringContext ]

Criteria and weights

Comparison

Result

Option C is selected. Strategic context mapping defines formal Upstream/Downstream relationships, mandates Anti-Corruption Layers at critical seams, and protects domain model integrity.

Required Mechanisms

1. Language: Ubiquitous Cross-Context Translation [MC-LG-01]

• Translation Matrix:
  • RetailDepositContext (AccountDebitedEvent) maps to CommercialLendingContext (LoanInstallmentPaidCommand).
  • RetailDepositContext (CheckingAccount) maps to CoreAccountingContext (GeneralLedgerSubAccount).
  • CustomerMasterContext (PartyRecord) maps to CommercialLendingContext (BorrowerLegalEntity).
• Linguistic Invariant: No context may directly import or execute another context's domain model classes.

2. Invariant: Cross-Boundary Integrity Protection [MC-IV-01]

Invariant 1 (INV-CMAP-OHS): Upstream contexts providing services to multiple downstream consumers must expose an

Open Host Service (OHS) with a stable, versioned

Published Language (PL) (OpenAPI / Protobuf).

Invariant 2 (INV-CMAP-ACL): Downstream contexts with differing core models must isolate incoming contracts via an

Anti-Corruption Layer (ACL).

3. State Transition & Communication Mechanics [MC-ST-01]

• Technical Seams:
  1. CustomerMaster $\to$ Retail: REST/JSON query over TLS 1.3 for identity verification.
  2. Retail $\to$ Accounting: Asynchronous Kafka event stream (retail.ledger.v1) processed via transactional outbox.
  3. Retail $\to$ Lending: Customer-Supplier relationship mediated via in-process ACL adapter LendingRetailTranslationAdapter.

4. Event Or Command: Integration Contracts [MC-EC-01]

• Published Language Schema (RetailAccountDebited.json):

  {
    "event_id": "evt_01J8N6B5H2QZ3R8V8",
    "context": "RetailDepositContext",
    "event_type": "account.debited",
    "occurred_at": "2026-09-15T14:22:00Z",
    "account_number": "DDA-881204",
    "amount_cents": 125000,
    "currency": "USD"
  }
  

ACL Consumption: The Commercial Lending ACL converts this event into internal value object LoanRepaymentAmount in $< 1.2$ ms.

Invariants and Contracts

Mandatory Anti-Corruption Layer Invariant [INV-CMAP-01]
  Downstream bounded contexts must implement an explicit Anti-Corruption Layer when integrating
  with upstream systems whose domain language or data schema differs from local ubiquitous language.

Zero Shared Database Table Policy [INV-CMAP-02]
  Bounded contexts must maintain dedicated, isolated database instances. Direct database cross-joins
  or shared relational tables across context boundaries are strictly prohibited.

Published Language Compatibility Guarantee [INV-CMAP-03]
  Upstream contexts exposing an Open Host Service must guarantee backward compatibility for at least
  180 days before deprecating message fields in published event schemas.

Explicit Unknowns

• Network latency overhead when chaining 3 asynchronous context hops across multi-region VPC peerings (G-1).
• Operational maintenance overhead of maintaining 14 distinct translation adapters across quarterly banking releases (G-2).

Traceability

Verification

No validator was supplied, so no command was run.

Reviewer self-check against context mapping standards:

• Relationship Hygiene: PASS. Formally classifies Upstream-Downstream, OHS/PL, Customer-Supplier, and ACL seams.
• Linguistic Scoping: PASS. Disambiguates domain models across Retail, Lending, and Accounting.
• Decoupling: PASS. Anti-Corruption Layers protect downstream domain models from upstream breaking changes.
• Markdown Hygiene: PASS. Native Markdown syntax strictly adheres to rule_markdown.md.

Open Decisions

• DEC-CMAP-01: David O'Reilly to determine whether an enterprise schema registry (Confluent / Apicurio) should be mandated for all cross-context Kafka topics in Q4 (Owner: David O'Reilly).

Next steps

1. Elena Rostova ratifies the strategic Context Map with the Enterprise Architecture Board.
2. Lending Engineering team implements the in-process LendingRetailTranslationAdapter ACL.
3. Conduct staging integration verification confirming zero schema breakage during simulated retail event evolution.