Multi-entity party graph manager¶


ID	`MOD-096`
System	SD02
Repo	`bank-kyc`
Build status	Deployed
Deployed	Yes
Last commit	`c01a544fb895508b2b8827a7b60ed8ec9f98496a`

What it does¶

MOD-096 is the multi-entity party graph manager. It extends the base customer party model to support a single authenticated user who operates across multiple legal and economic entities simultaneously — as themselves personally, as a sole trader, as a director of one or more companies, and as a property investor.

The problem it solves¶

A sole trader who also has a Ltd company and two rental properties is four distinct economic contexts under one login. Without a party graph: - All transactions appear in one undifferentiated stream - There is no way to view a clean P&L per entity - Classification signals for one context bleed into another - Xero/MYOB integration has no clean entity boundary to export to

MOD-096 creates the graph that separates these contexts while keeping them navigable under a single login.

Party graph structure¶

Each node in the graph is a party — a legal or economic entity with a type: - NATURAL_PERSON — the individual customer - SOLE_TRADER — the same individual acting in a business capacity (no separate legal entity in NZ/AU) - COMPANY — a Ltd company in which the customer is a director or shareholder - TRUST — a family trust or other trust with the customer as trustee or beneficiary - PROPERTY_CONTEXT — a non-legal operating context for a specific rental property (created by MOD-094)

Edges in the graph represent the relationship type: IS_DIRECTOR_OF, IS_TRUSTEE_OF, IS_BENEFICIAL_OWNER_OF, OPERATES_AS.

CDD requirement¶

Each entity node must have its own Customer Due Diligence profile. Adding a new entity to a customer's graph triggers the appropriate KYC/CDD check for that entity type via MOD-009 or MOD-010. A company cannot be added without verifying the UBO structure. A trust cannot be added without confirming the trustee arrangement.

The customer app (SD08) uses the party graph from MOD-096 to: - Render a context switcher (e.g. "Ross — Personal | Ross Consulting | 12 Smith St") - Apply access controls and data scoping per context - Route classification, tax logic, and accounting mapper outputs to the correct entity context

Design phase¶

This module is in design. Build begins in Phase 2 of the Expense Intelligence Platform. See the Expense Intelligence Platform summary for the full implementation roadmap.

Module dependencies¶

Depends on¶

Module	Title	Required?	Contract	Reason
MOD-009	eIDV & document verification	Required	`contract/api/`	eIDV verification for natural person entities (NATURAL_PERSON, SOLE_TRADER) is triggered via MOD-009 before a new party node is activated in the graph — AML-002 GATE requirement.
MOD-010	CDD tier assignment engine	Required	`contract/api/`	CDD tier assignment for business entities (COMPANY, TRUST) is orchestrated via MOD-010 before the entity relationship is confirmed in the party graph — AML-004 GATE requirement.
MOD-104	AWS shared infrastructure bootstrap	Required	—	AWS shared infrastructure provisioned by MOD-104 (EventBridge buses, KMS, Lambda execution role) is required before this module can be deployed.
MOD-103	Neon database platform bootstrap	Required	—	Neon database and schema provisioned by MOD-103 must exist before this module can read or write Postgres (party.party_relationships, kyc.idempotency_records).

Required by¶

Module	Title	As	Contract
MOD-094	Property attribution engine	Optional enhancement	`contract/api/`

Policies satisfied¶

Policy	Title	Mode	How
AML-002	Customer Due Diligence (CDD) Policy	`GATE`	Each entity in the party graph must have its own CDD profile; MOD-096 cannot link a new entity to a party graph without triggering the appropriate KYC/CDD check for that entity type.
AML-004	Politically Exposed Persons (PEP) Policy	`GATE`	Entity graph relationships with elevated risk indicators trigger enhanced due diligence via the existing EDD workflow before the relationship is confirmed.

Capabilities satisfied¶

Capability	Title	Mode	How
CAP-138	CAP-138	`AUTO`	Manages the graph of entities (natural person, sole trader, Ltd company, trust, property operating context) associated with a single login; enforces appropriate access controls and CDD requirements per entity; provides a single-login multi-entity view for customers operating across multiple legal and economic contexts.

Part of SD02 — Customer Identity & KYC Platform Compiled 2026-05-22 from source/entities/modules/MOD-096.yaml