supplier-golden-record-platform

Reference implementation of retail supplier MDM: build a Supplier Golden Record from multi-source legacy systems (mainframe, SQL Server, IBM DB2), apply survivorship and classification (1P / DSV / 3P across countries), materialize to Cassandra, and publish changes on Kafka for hundreds of downstream consumers.

Part of the Enterprise Platform Reference Architecture.

Problem

Legacy supplier data lives in three systems of record at different grains: LegacySupplierID + CountryCode + TypeOfBusiness (1P|DSV|3P). Downstream apps need one golden supplier per LegacySupplierID with auditable lineage and near-real-time updates.

Architecture

flowchart LR
  mf[Mainframe CDC] --> kafka[(Kafka)]
  sql[SQL Server CDC] --> kafka
  db2[IBM DB2 CDC] --> kafka
  kafka --> pipe[Match + Survivorship + Classify]
  batch[Nightly batch reconcile] --> pipe
  pipe --> cass[(Cassandra golden record)]
  pipe --> out[supplier.golden-record.changed]
  out --> apps[300+ consumers]

Loading

Key design choices

Topic	Decision
Legacy grain	LegacySupplierID + Country + TypeOfBusiness unique per source row
Golden grain	One record per LegacySupplierID (flat v1 — no parent hierarchy)
Survivorship	Mainframe → legal identity; SQL → operational; DB2 → international/trade
Multi-type / multi-country	JSON facets with provenance (relationship_types, country_presence)
Ingestion	Kafka CDC (incremental) + nightly batch reconciliation
Serving store	Cassandra query-first tables + xref lookups

Run

mvn test
mvn spring-boot:run
# POST http://localhost:8085/api/admin/ingest/samples
# GET  http://localhost:8085/api/suppliers/legacy/004821
docker compose up --build

API

Method	Path	Description
GET	/api/suppliers/legacy/{legacySupplierId}	Golden record by 6-digit legacy ID
GET	/api/suppliers/golden/{goldenId}	Golden record by UUID
GET	/api/suppliers/grain/{id}/{country}/{type}	Resolve grain → golden
POST	/api/admin/ingest/samples	Load sample mainframe/sql/db2 data
POST	/api/admin/reconcile	Trigger batch reconciliation

Documentation

• System design
• Industry applicability
• Business & governance: BRD · SOP · NFR · Cost savings
• ADRs: docs/adr/
• Cassandra DDL: src/main/resources/cassandra/schema.cql

Tech

Java 21, Spring Boot 3.3, Spring Kafka, Spring Data Cassandra (DDL + entity mapping), Cassandra 4, Redpanda/Kafka, Maven, Docker Compose.