0003. Model customer identity as linkage, not a golden record¶

Date: 2026-07-10 Status: Accepted

Context¶

Customer, Order, and Product rows hang off system_connection_id, not off Tenant. The same real customer present in two connected systems (e.g. Acme's WooCommerce shop and Acme's User Platform account) today produces two independent Customer rows with no link between them. Two prior internal design notes — the "Identity Layer" and the "Bridge" — each proposed a way to close this gap; this decision consolidates them into one model.

Decision¶

The same real customer across systems is represented by linking existing per-connection Customer rows via a new CustomerIdentity entity, matched on normalised email (match_key), scoped by Tenant — not by merging them into a golden record. No merge means no merge-conflict machinery. The "Bridge" correlation builds on this same link instead of duplicating it.

CustomerIdentity is a separate linking entity (id, tenant_id, match_key), not an identity_id column bolted onto Customer. Uniqueness is unique(['tenant_id','match_key']), so one real person maps to one identity per tenant. See Cross-System Identity for the mechanism detail — how Customer joins to it, why the correlation layer sits below the connection.

Consequences¶

Whether Conflux still writes a custom_id (a Conflux-generated UUID) back into connected systems as the correlation key — as the "Bridge" did — or adopts the email match_key as the id everywhere (which may make the Bridge resolver largely redundant) is a separate downstream question, not resolved by this decision. It only becomes relevant once push-out (see ADR-0004) is implemented.