Initial commit: Financial Crime domain exemplar

2026-06-01 21:18:19 +12:00
commit 2fc4dacd59
70 changed files with 5776 additions and 0 deletions
@@ -0,0 +1,167 @@
+# [Financial Crime](../domain.md)
+
+## Entities
+
+### Contact Address
+
+A Contact Address is the association between a Party and a physical Address, qualified by purpose, verification status, and the period during which it was in use. It is not the address itself — the canonical physical location is held in the Address entity and reused across parties. Contact Address carries only the metadata that describes *how* and *when* a Party uses a given address.
+
+This separation supports two critical financial crime capabilities. First, deduplication: if two parties share the same physical address, a single Address record exists and both Contact Address records point to it, enabling network analysis queries such as "which other parties are associated with this address". Second, temporal accuracy: the valid time period on Contact Address allows point-in-time queries — "what address did this party use at the time of this transaction" — which is essential for regulatory audit and SAR evidence.
+
+A Party *has* Contact Addresses — it owns the association. A Party Role *uses* Contact Addresses — a role references which of the party's addresses applies for the specific purpose of that role. For example, the same Person may have a residential address used for identification and a mailing address used by their Customer role for correspondence.
+
+```mermaid
+---
+config:
+  layout: elk
+---
+classDiagram
+  class ContactAddress{
+    * Contact Address Identifier : string
+    Address Purpose : enum~AddressPurpose~
+    Is Primary : boolean
+    Verification Status : enum~AddressVerificationStatus~
+    Verification Date : date
+    Verification Method : enum~VerificationMethod~
+    Valid From : date
+    Valid To : date
+  }
+
+  Party "1" --> "0..*" ContactAddress : has
+  PartyRole "0..*" --> "0..*" ContactAddress : uses
+  ContactAddress "0..*" --> "1" Address : references
+
+  class AddressPurpose["<a href='https://github.com/Semprini/md-ddl/blob/main/examples/Financial%20Crime/enums.md#address-purpose'>Address Purpose</a>"]{<<enumeration>>}
+  class AddressVerificationStatus["<a href='https://github.com/Semprini/md-ddl/blob/main/examples/Financial%20Crime/enums.md#address-verification-status'>Address Verification Status</a>"]{<<enumeration>>}
+  class VerificationMethod["<a href='https://github.com/Semprini/md-ddl/blob/main/examples/Financial%20Crime/enums.md#verification-method'>Verification Method</a>"]{<<enumeration>>}
+
+  class Party["<a href='https://github.com/Semprini/md-ddl/blob/main/examples/Financial%20Crime/entities/party.md'>Party</a>"]
+  class PartyRole["<a href='https://github.com/Semprini/md-ddl/blob/main/examples/Financial%20Crime/entities/party_role.md'>Party Role</a>"]
+  class Address["<a href='https://github.com/Semprini/md-ddl/blob/main/examples/Financial%20Crime/entities/address.md'>Address</a>"]
+```
+
+```yaml
+existence: associative
+mutability: slowly_changing
+temporal:
+  tracking: valid_time
+  description: >
+    Valid time is carried explicitly as Valid From and Valid To attributes rather than relying on generated temporal columns. This allows future-dated address changes (e.g. recording a new address before a customer moves) and supports point-in-time queries for regulatory audit.
+attributes:
+  Contact Address Identifier:
+    type: string
+    identifier: primary
+    description: >
+      Globally unique surrogate identifier for this party-address association instance.
+
+  Address Purpose:
+    type: enum:Address Purpose
+    description: >
+      The purpose for which this address is used by the party. Determines regulatory significance — a Residential Address is required for individual identification under the AML/CTF Act 2006; a Registered Office Address is required for legal entity verification.
+
+  Is Primary:
+    type: boolean
+    default: false
+    description: >
+      Indicates whether this is the party's primary contact address for the given purpose. A party may have only one primary address per Address Purpose at any point in time.
+
+  Verification Status:
+    type: enum:Address Verification Status
+    description: >
+      The current verification status of this address association. Unverified addresses must not be used as the sole basis for satisfying AML/CTF identification obligations. Expired verification must be renewed at the next CDD review.
+
+  Verification Date:
+    type: date
+    description: >
+      The date on which the address was most recently verified against an acceptable document or electronic source. Used to determine whether re-verification is required at periodic CDD review.
+
+  Verification Method:
+    type: enum:Verification Method
+    description: >
+      The method used to verify this address. Documentary verification requires an acceptable identity or address document. Electronic verification uses a third-party data source. In-person verification is performed at a branch or by a third party.
+
+  Valid From:
+    type: date
+    description: >
+      The date from which the party began using this address for the stated purpose. Establishes the start of the valid time period for point-in-time queries.
+
+  Valid To:
+    type: date
+    description: >
+      The date on which the party ceased using this address for the stated purpose. A null value indicates the address is currently in use. Closed associations must not be deleted — Valid To must be set to preserve address history for regulatory audit.
+```
+
+```yaml
+constraints:
+  One Primary Per Purpose:
+    check: >
+      COUNT(Contact Address WHERE Party == this.Party
+        AND Address Purpose == this.Address Purpose
+        AND Is Primary == true
+        AND (Valid To IS NULL OR Valid To >= Today)) <= 1
+    description: >
+      A party may have at most one primary Contact Address per Address Purpose
+      at any point in time.
+
+  Valid To After Valid From:
+    check: "Valid To IS NULL OR Valid To > Valid From"
+    description: >
+      The end of the address validity period must be later than the start.
+
+  Verification Date Required When Verified:
+    check: >
+      Verification Status != 'Verified'
+      OR Verification Date IS NOT NULL
+    description: >
+      A Contact Address with a status of Verified must have a Verification
+      Date recorded.
+
+  Residential Required Before Activation:
+    check: >
+      EXISTS (Contact Address WHERE Party == this.Party
+        AND Address Purpose == 'Residential'
+        AND Verification Status == 'Verified')
+    lifecycle_stage: Onboarding
+    description: >
+      An individual party must have at least one verified Residential Address
+      before any designated service is provided. Required for identification
+      under the AML/CTF Act 2006 Part B individual identification program.
+```
+
+```yaml
+governance:
+  pii: true
+  classification: Highly Confidential
+  retention: 10 years
+  retention_basis: Domain default retention aligned to AML/CTF record-keeping obligations
+  description: >
+    Address association records must be retained for 7 years from Valid To
+    date, aligned to AUSTRAC and RBNZ record-keeping obligations. Records
+    must never be deleted — closure via Valid To is the only permitted
+    termination mechanism.
+  access_role:
+    - FINANCIAL_CRIME_ANALYST
+    - KYC_OFFICER
+    - COMPLIANCE_OFFICER
+    - RELATIONSHIP_MANAGER
+  compliance_relevance:
+    - AUSTRAC AML/CTF Act 2006 — Part B address identification obligations
+    - AUSTRAC AML/CTF Amendment Act 2024
+    - RBNZ AML/CFT Act 2009 — section 14
+    - FATF Recommendation 10 — Customer Due Diligence
+```
+
+## Relationships
+
+### Contact Address References Address
+
+Each Contact Address references exactly one canonical Address record.
+
+```yaml
+source: Contact Address
+type: references
+target: Address
+cardinality: many-to-one
+granularity: atomic
+ownership: Contact Address
+```