Executive summary

Separating couples describe property settlement as gruesome, lawyer-heavy and expensive. The two most painful tasks are listing every asset and debt, and completing financial disclosure with someone they may no longer trust. Lawyers spend expensive hours on both before any negotiation starts.

Settle is a web application that lets one person, or both people together, build the property pool, record what each side thinks each item is worth, and see immediately what different splits look like in practical terms: who keeps the house, who pays whom, whether a superannuation split is needed. It then shows an indicative court outcome as a range, never a single number, produced by a fixed, published, deterministic method with every adjustment explained. A prominent disclaimer sits on the output itself: this is not a legal service, and a family lawyer should finalise any agreement.

What is built today

• Five bounded contexts in TypeScript following domain-driven design: disclosure, asset discovery, settlement modelling, parenting arrangements and identity, plus a shared kernel (Money in integer cents, Result, ids, dates).
• Per-party claimed values on every pool item. An agreed value is derived only when both claims exist and match exactly. Disagreement is a normal state with its own UI, not an error.
• Solo mode (one person enters estimates for the other) and joint mode (partner invited by email, their own figures overwrite the estimates).
• A four-step settlement engine (assessSettlement, ENGINE_VERSION 1.0.0) and a split modeller that turns a percentage into allocations, a balancing payment and, where needed, a suggested super split.
• Anonymous in-browser modelling with no account. Sign-up is required only to save or to invite a partner. Passwordless auth (magic link or six-digit code) via Supabase, Google optional, no Facebook.
• Mocked asset discovery behind a provider port: ASIC, PPSR, state land titles, ATO super and identity verification, gated by a paid 'discovery' tier and, for registries, by verified identity.
• A Postgres schema (Drizzle, migration 0000_calm_triathlon) with tables prefixed by context, including two phase two tables (ph2_documents, ph2_disclosure_flags) that exist as schema only.
• Six deterministic demo scenarios built through the domain constructors.

What is designed but not built Phase two

AI parsing of bank statements, payslips, superannuation statements and tax returns into structured extractions, and a rule-based checker that raises disclosure gaps and inconsistencies for a human to resolve. The AI never sets a value and never decides a split; it only proposes, and a party accepts or dismisses.

Positioning versus amica

amica is the government-backed online tool that helps separated couples reach agreement on money and parenting. It is well built, trusted, and suits couples who are largely amicable, know what they own, and have a simple pool. Settle does not compete for those couples; it should send them to amica.

Positioning statement

For people separating with anything more than a simple pool, Settle is the place to build the full picture of what you both own, see what a fair split looks like in dollars and decisions, and walk into a lawyer's office with the expensive work already done.

Explicit non-goals

• Settle does not give legal advice, draft consent orders or binding financial agreements, or file anything with the court.
• Settle does not compute child support. The parenting context exposes care and cost percentages so the direction of travel can be explained, and stops there.
• Settle does not use AI to produce numbers. The engine is a published heuristic. Phase two AI extracts facts from documents and proposes; humans decide.

Personas and demo scenarios

Three personas drive the design. Each demo scenario in src/demo/scenarios.ts is a complete MatterSnapshot built through the domain constructors with deterministic ids, so seed data can never drift from the invariants. Demo logins are passwordless; the local provider accepts code 123456.

The six demo scenarios

Pool and range figures below were produced by running computeResults against the real scenarios on 16 September 2026. The 'range' column is the indicative percentage for party A.

Demo accounts: demo.jess@example.com, demo.tom@example.com, demo.sarah@example.com, demo.david@example.com, demo.liam@example.com, demo.chloe@example.com, demo.priya@example.com, demo.ben@example.com, demo.kayla@example.com, demo.jordan@example.com, demo.elena@example.com, demo.marcus@example.com. The /demo page lists scenarios via GET /api/demo/scenarios and signs in as A or B via POST /api/demo/:slug/login.

Functional scope

Scope is organised by bounded context. Everything marked built exists in src/ today; the UI pages listed in Section 4 render these capabilities.

User journeys

Journey 1: anonymous solo modelling (free)

1. Land on /, read what the tool does and the disclaimer, press 'Start'.
2. /start: choose marriage or de facto, enter cohabitation start and separation date. An anonymous matter is created in the browser and stored under localStorage['settle.matter.v1'].
3. /matter/you and /matter/partner: enter your own details and your best estimates for the other person. Estimates are stored under role B with source: 'estimate_for_partner'.
4. /matter/children: add children and the nights-per-fortnight pattern per child, or skip.
5. /matter/disclosure: add assets, debts and super. For each item enter your value and your estimate of the other side's value. Agreement chips update as you type.
6. /matter/results: computeResults runs in the browser. Split scenarios are shown first, then the indicative range with the disclaimer attached, then the factor explanations.

Journey 2: save and invite (joint)

1. From results or /matter/share, press 'Save' or 'Invite'. If not signed in, the app sends the person to /sign-in and returns them afterwards.
2. Sign in by email code or magic link (or Google). POST /api/matters stores the snapshot; the creator becomes a member with snapshot.matter.ownerRole.
3. POST /api/matters/:id/invite with the partner's email creates an invitation offering the opposite role and moves the matter to joint mode.
4. The partner opens /invite/[token], signs in with the invited email, and POST /api/invitations/:token/accept adds them to id_matter_members.
5. The partner reviews every item and enters their own figures, which replace the estimates. Items with matching values become agreed; the others are shown as disputed, ranked by gap.

Journey 3: discovery (paid)

1. On /matter/discovery, providers are listed with lock chips explaining what unlocks them: the discovery tier for all registries, and verified identity for land titles and ATO super.
2. Upgrade (mock payment) via POST /api/account/upgrade; verify identity (mock) via POST /api/account/verify-identity.
3. Run a provider for a subject (POST /api/matters/:id/discovery). Findings appear with confidence (exact, probable, possible) and a suggested item.
4. Accept a finding; the disclosure context creates a PoolItem with discoveryRef and the estimated value recorded for the requesting party with source discovery.

flowchart LR
  L["Landing /"] --> S["Start: relationship basics"]
  S --> Y["You"] --> P["Partner (estimates in solo)"] --> C["Children and care"] --> D["Disclosure: items and per-party values"]
  D --> R["Results: splits, then indicative range"]
  R -->|save or invite| SI["Sign in (passwordless)"] --> SH["Share: save + invite"]
  SH --> INV["Partner accepts /invite/token"] --> D
  R -->|deep discovery| DS["Discovery (tier + identity gated)"] -->|accept finding| D
  style R fill:#FBE9DA,stroke:#E97819
    

Information architecture

The App Router page list below is the contract between product and engineering; it matches docs/ARCHITECTURE.md. Every /matter/* page reads and writes the same MatterSnapshot, whether it lives in the browser or in Postgres.

Navigation model

The matter pages form a linear stepper (you, partner, children, disclosure, results) with a persistent progress bar and free movement between completed steps. Results, discovery and share are always one tap away from the stepper once a matter exists. On mobile the stepper collapses to the current step name plus a 'Steps' drawer.

Persistence states

Wireframes: landing and start

Wireframes are CSS mockups, not final visual design. They fix layout priority, copy hierarchy and the behaviours in Section 4. Navy is structure, terracotta is the one primary action per screen.

Wireframes: disclosure list

The disclosure list is the heart of the product. Every row shows both parties' claimed values and an agreement chip derived from agreementState. In solo mode the B column is labelled 'Your estimate for David' and stored with source: 'estimate_for_partner'. In joint mode each person edits only their own column; the other column is read-only with an 'Accept their value' action.

Row behaviours

• Editing your value calls recordValuation; the agreed value and chip are recomputed immediately and never edited directly.
• 'Accept theirs' calls acceptOtherPartyValue, which records their figure as yours with the note 'Accepted other party value' and therefore produces agreement.
• 'Keeps' sets retainedBy and drives the split modeller. Superannuation shows 'Member' and cannot be reassigned here.
• Negative values are rejected with 'Enter debts as positive amounts under liabilities'. Remove item is a destructive action and uses red only in its confirmation.

Wireframes: results

Order is fixed by the product brief and enforced in the design: practical split scenarios first, then the indicative range with the disclaimer attached to it, then the factor explanations. Numbers below are the real family-primary-carer output from Section 8.

Results on a phone

On narrow screens scenarios become a horizontally swipeable card rail with the midpoint card first. The indicative range stacks the two parties. The disclaimer keeps its full text; it is never truncated or collapsed behind a 'read more'.

Wireframes: discovery, sign-in and share

Domain model and bounded contexts

The code is organised as five bounded contexts plus a shared kernel under src/contexts. The rule enforced by convention and review: no context imports another context's infrastructure. Domain types may be imported across contexts where one context is upstream of another; those dependencies are drawn below.

flowchart TB
  SK["Shared kernel: Money (cents), Result, ids, dates"]
  DC["Disclosure: Matter, Party, Child, PoolItem, Valuation, agreedValue rule, DisclosureSummary"]
  PA["Parenting: CareArrangement, care percent, cost percent, primary carer"]
  SM["Settlement modelling: assessSettlement, Factor, Band, modelSplit, standardScenarios"]
  AD["Asset discovery: Provider port, PROVIDER_META, gateDiscovery, runDiscovery, Finding"]
  ID["Identity: User, Session, AuthProvider port, Invitation, membership, Tier"]
  RM["Read model: MatterSnapshot, MatterResults, computeResults (published language)"]
  SK --> DC
  SK --> PA
  SK --> SM
  SK --> AD
  SK --> ID
  DC -->|"upstream: Child type (conformist)"| PA
  DC -->|"upstream: Matter, Party, PoolItem, summariseDisclosure (conformist)"| SM
  PA -->|"upstream: ParentingSummary (conformist)"| SM
  DC -->|"upstream: PoolItemCategory (conformist)"| AD
  AD -->|"Finding is a lead; user accepts, disclosure creates PoolItem with discoveryRef (anti-corruption at the boundary)"| DC
  AD -->|"Tier type (conformist)"| ID
  ID -->|"membership gates access to a Matter"| DC
  DC --> RM
  PA --> RM
  SM --> RM
  RM -->|"same JSON shape in browser, API and DB"| UI["UI, API route handlers, MatterRepository"]
  style RM fill:#FBE9DA,stroke:#E97819
  style SK fill:#EAF0F6,stroke:#103654
    

Aggregates, invariants and agreement states

Key invariants (from ARCHITECTURE.md, enforced in code)

• Money is integer cents everywhere in the domain. recordValuation rejects non-integers and negatives. Formatting happens at the edge with formatAud.
• PoolItem.valuations holds one claimed value per party. agreedValue is derived by deriveAgreedValue and is null unless both claims exist and are exactly equal. It is never set by hand; the repository recomputes it on save.
• In solo mode the user's estimates for the partner are stored under the partner's role with source: 'estimate_for_partner'. Joint mode overwrites them with the partner's own figures (source manual).
• The settlement engine is pure and deterministic. Every adjustment is a Factor with an explanation. The output carries a disclaimer string the UI must render on the result itself.
• Court outcome is always a range. Dollar ranges span both parties' views of the pool.
• Moving from solo to joint is one-way (inviteToJoint rejects an already-joint matter).
• Separation date cannot precede cohabitation start. Nights per fortnight are 0 to 14. Descriptions and names cannot be blank.

Effective value and the two pools

effectiveValue(item, perspective) returns the agreed value first, then the viewer's own claim, then the other party's claim. summariseDisclosure also computes a low pool (for each item the value least favourable to a high total: the smaller asset claim, the larger debt claim) and a high pool (the reverse). The engine's referencePool is the midpoint of the two net totals.

stateDiagram-v2
  [*] --> unvalued : createPoolItem
  unvalued --> awaiting_other : one party records a value
  awaiting_other --> agreed : other party records the same value
  awaiting_other --> disputed : other party records a different value
  awaiting_other --> awaiting_other : same party revises value
  disputed --> agreed : either party revises to match, or acceptOtherPartyValue
  agreed --> disputed : either party revises to a different value
  disputed --> disputed : revise, still different
  agreed --> agreed : both revise to the same new value
  note right of disputed
    Normal state. Shown with a terracotta chip,
    ranked by valuationGap on the disclosure page,
    widens the dollar range on results.
  end note
  note right of agreed
    agreedValue is set and equals both claims.
    Derived by deriveAgreedValue, never edited.
  end note
    

Ubiquitous language

Terms below are used identically in code, UI copy, this document and conversations with the client. Where the UI shows a friendlier label, it is noted.

Architecture: system context

A C4 level-one view. The people, the one system, and the external systems it depends on. Registry adapters are mocked today and are drawn where the real services will sit.

flowchart LR
  subgraph people["People"]
    A["Party A: the person who starts the matter"]
    B["Party B: the former partner, invited later"]
    LW["Family lawyer: receives the summary, finalises the agreement"]
  end
  subgraph sys["Settle (working title)"]
    S["Web application: Next.js on Vercel, modelling in browser and server"]
  end
  subgraph ext["External systems"]
    SBA["Supabase Auth: magic link, email OTP, Google"]
    PG["Postgres: Supabase in production, local in development"]
    ASIC["ASIC registry (mocked)"]
    PPSR["PPSR (mocked)"]
    LT["State land title registries (mocked)"]
    ATO["ATO super via myGov consent (mocked)"]
    IDV["Identity verification vendor (mocked)"]
    LLM["Document extraction model (phase two)"]
  end
  A -->|"models anonymously, saves, invites"| S
  B -->|"accepts invitation, enters own values"| S
  S -->|"exported summary (planned)"| LW
  S -->|"passwordless sign-in"| SBA
  S -->|"Drizzle over pg"| PG
  S --> ASIC
  S --> PPSR
  S --> LT
  S --> ATO
  S --> IDV
  S -.->|"phase two"| LLM
  style S fill:#103654,stroke:#103654,color:#fff
  style LLM stroke-dasharray: 5 5
    

Architectural principles

• Same shape everywhere. The MatterSnapshot JSON is what the browser stores, what the API sends, and what the repository normalises into rows and back. Anonymous to saved needs no conversion.
• Compute where the data is. The engine runs in the browser for anonymous users and in route handlers for saved matters. It is the same pure function.
• Ports for everything external. AuthProvider and DiscoveryProvider are interfaces with local and mock implementations; production adapters are drop-ins.
• Whole-aggregate persistence. MatterRepository.save replaces the aggregate in one transaction. Simple and correct at tens of items per matter.

Components and deployment

flowchart TB
  subgraph browser["Browser"]
    direction LR
    UI["React 19 pages"]
    ENG["computeResults"]
    LS["localStorage settle.matter.v1"]
    UI --> ENG
    UI --> LS
  end
  subgraph vercel["Vercel: one Next.js deployment"]
    direction LR
    RH["Route handlers /api/*"]
    AUTH["AuthProvider port"]
    REPO["MatterRepository (Drizzle, pg Pool)"]
    DISC["runDiscovery + gateDiscovery"]
    RH --> AUTH
    RH --> REPO
    RH --> DISC
  end
  subgraph data["Supabase project or local Postgres"]
    direction LR
    DB[("Postgres: id_ dc_ pa_ ad_ ph2_")]
    SBA["Supabase Auth"]
    STO["Storage bucket (phase two)"]
  end
  subgraph adapters["Registry adapters"]
    direction LR
    MOCK["MockProvider x4 + mockVerifyIdentity"]
    REAL["Real ASIC, PPSR, titles, ATO, KYC (later)"]
  end
  subgraph ph2["Phase two worker"]
    direction LR
    Q["Queue"] --> W["Parsing worker"] --> CHK["Disclosure checker"]
  end
  UI -->|"JSON over HTTPS, settle_session cookie"| RH
  DISC --> MOCK
  DISC -.-> REAL
  MOCK ~~~ Q
  REAL ~~~ Q
  AUTH --> SBA
  REPO --> DB
  RH -.-> STO
  STO -.-> W
  CHK -.-> DB
  style ph2 stroke-dasharray: 5 5
  style REAL stroke-dasharray: 5 5
  style STO stroke-dasharray: 5 5
    

Sequence: anonymous, save, invite, accept

sequenceDiagram
  autonumber
  actor A as Party A (browser)
  participant LS as localStorage
  participant API as Next route handlers
  participant AUTH as AuthProvider
  participant DB as Postgres
  actor B as Party B (browser)
  A->>LS: create matter, parties, items (settle.matter.v1)
  A->>A: computeResults in browser
  A->>API: POST /api/auth/start { email, method }
  API->>AUTH: startEmailSignIn
  AUTH-->>A: email with code or magic link
  A->>API: POST /api/auth/verify { challengeId, code }
  API->>AUTH: verifyEmailCode
  API->>DB: upsert id_users, insert id_sessions
  API-->>A: { user } + Set-Cookie settle_session
  A->>API: POST /api/matters { snapshot }
  API->>DB: MatterRepository.save (one transaction), insert id_matter_members role = ownerRole
  API-->>A: { matterId, role }
  A->>API: POST /api/matters/:id/invite { email }
  API->>DB: insert id_invitations (roleOffered = other role, 14 days), dc_matters.mode = joint
  API-->>A: { invitation, acceptUrl }
  A-->>B: shares link /invite/[token] (email in production)
  B->>API: sign in with the invited email (same auth steps)
  B->>API: POST /api/invitations/:token/accept
  API->>DB: check pending, not expired, email matches, insert id_matter_members role B, invitation accepted
  API-->>B: { matterId, role: B }
  B->>API: GET /api/matters/:id
  API-->>B: { snapshot, role }
  B->>API: PUT /api/matters/:id { snapshot with B valuations, source manual }
  API->>DB: save, recompute agreed_value per item
    

Step 17 uses acceptUrl for local demos. In production the invitation email carries the link and the token is never shown to the inviter.

Data model

The schema is defined in src/db/schema.ts with Drizzle and generated into drizzle/0000_calm_triathlon.sql. Table prefixes make context ownership visible in the database: id_ identity, dc_ disclosure, pa_ parenting, ad_ asset discovery, sm_ reserved (no tables, pure computation), ph2_ phase two. Money columns are bigint cents. All timestamps are timestamptz.

erDiagram
  id_users {
    uuid id PK
    text email UK
    text display_name
    tier tier
    boolean identity_verified
    text auth_subject
  }
  id_sessions {
    text token PK
    uuid user_id FK
    timestamptz expires_at
  }
  id_auth_challenges {
    uuid id PK
    text email
    text method
    text code_hash
  }
  id_matter_members {
    uuid matter_id PK
    uuid user_id PK
    party_role role
  }
  id_invitations {
    uuid id PK
    uuid matter_id FK
    uuid invited_by_user_id FK
    text invited_email
    party_role role_offered
    text token UK
    invitation_status status
    timestamptz expires_at
    uuid accepted_by_user_id FK
  }
  dc_matters {
    uuid id PK
    matter_mode mode
    matter_status status
    relationship_type relationship_type
    date cohabitation_start
    date separation_date
    party_role owner_role
  }
  dc_parties {
    uuid id PK
    uuid matter_id FK
    party_role role
    text display_name
    date date_of_birth
    text occupation
    employment_status employment_status
    bigint annual_income
    boolean health_or_capacity_concern
    boolean primary_homemaker
    bigint initial_contribution
    bigint inheritances_or_gifts
    boolean participating
  }
  dc_children {
    uuid id PK
    uuid matter_id FK
    text first_name
    date date_of_birth
  }
  dc_pool_items {
    uuid id PK
    uuid matter_id FK
    pool_item_kind kind
    text category
    text description
    ownership ownership
    bigint agreed_value
    party_role retained_by
    text discovery_ref
  }
  dc_pool_item_valuations {
    uuid item_id PK
    party_role party_role PK
    bigint value
    valuation_source source
    text note
  }
  pa_care_arrangements {
    uuid child_id PK
    uuid matter_id FK
    smallint nights_with_a_per_fortnight
    text pattern
  }
  ad_discovery_requests {
    uuid id PK
    uuid matter_id FK
    discovery_provider provider
    jsonb subject
    party_role requested_by_role
    discovery_status status
    jsonb findings
    text error
  }
  ph2_documents {
    uuid id PK
    uuid matter_id FK
    party_role uploaded_by_role
    document_kind kind
    text storage_path
    document_status status
    jsonb extraction
    text parser_version
  }
  ph2_disclosure_flags {
    uuid id PK
    uuid matter_id FK
    disclosure_flag_kind kind
    smallint severity
    text message
    uuid related_item_id FK
    uuid source_document_id FK
    disclosure_flag_status status
  }
  id_users ||--o{ id_sessions : "has"
  id_users ||--o{ id_matter_members : "joins"
  dc_matters ||--o{ id_matter_members : "has members"
  dc_matters ||--o{ id_invitations : "invites to"
  id_users ||--o{ id_invitations : "sends"
  dc_matters ||--|{ dc_parties : "two parties"
  dc_matters ||--o{ dc_children : "has"
  dc_matters ||--o{ dc_pool_items : "pool"
  dc_pool_items ||--o{ dc_pool_item_valuations : "claimed per party"
  dc_children ||--o| pa_care_arrangements : "care"
  dc_matters ||--o{ ad_discovery_requests : "runs"
  dc_matters ||--o{ ph2_documents : "uploads"
  dc_matters ||--o{ ph2_disclosure_flags : "flags"
  dc_pool_items o|--o{ ph2_disclosure_flags : "relates to"
  ph2_documents o|--o{ ph2_disclosure_flags : "sourced from"
    

Schema: identity (id_)

Enum types created by the migration: tier (free, discovery), party_role (A, B), invitation_status (pending, accepted, expired, revoked).

id_users

id_sessions

id_auth_challenges

id_matter_members

id_invitations

Schema: disclosure (dc_)

Enums: matter_mode, matter_status, relationship_type, employment_status, pool_item_kind, ownership, valuation_source. Category is stored as text (16 values in KIND_BY_CATEGORY) so new categories do not need a migration.

dc_matters

dc_parties (unique index dc_parties_matter_role_idx on matter_id, role)

dc_children (index dc_children_matter_idx)

id uuid PK; matter_id uuid FK CASCADE; first_name text NOT NULL; date_of_birth date NOT NULL. Age at assessment determines dependency (under 18) and the under-five uplift.

dc_pool_items (index dc_pool_items_matter_idx)

dc_pool_item_valuations: the per-party valuation table

Schema: parenting, discovery, phase two, security

pa_care_arrangements

ad_discovery_requests (index ad_discovery_requests_matter_idx)

ph2_documents Phase two (table exists, only status 'uploaded' is reachable today)

ph2_disclosure_flags Phase two

Indices

Unique: id_users_email_idx, id_invitations_token_idx, id_matter_members_role_idx (matter_id, role), dc_parties_matter_role_idx (matter_id, role). Non-unique: dc_children_matter_idx, dc_pool_items_matter_idx, ad_discovery_requests_matter_idx. Composite primary keys on dc_pool_item_valuations (item_id, party_role) and id_matter_members (matter_id, user_id) double as lookup indices. Recommended additions: id_sessions(user_id), id_invitations(matter_id, status), ph2_documents(matter_id, status), ph2_disclosure_flags(matter_id, status).

Row level security on Supabase

Today all database access goes through Next route handlers using a server connection, and authorisation is a membership check: the handler loads id_matter_members for the session user and the requested matter and returns 403 otherwise. RLS is therefore defence in depth rather than the primary control, and the policies are not yet in migration 0000. Recommended policy shape, applied to every table carrying matter_id:

alter table dc_pool_items enable row level security;
create policy matter_member_rw on dc_pool_items
  for all using (
    exists (
      select 1 from id_matter_members m
      join id_users u on u.id = m.user_id
      where m.matter_id = dc_pool_items.matter_id
        and u.auth_subject = auth.uid()::text
    )
  );
-- dc_pool_item_valuations joins through dc_pool_items.
-- id_users: a user may read and update only their own row.
-- ph2_documents: members may read; only the uploading role may delete.

The server role used by route handlers bypasses RLS, so the membership check in code remains mandatory. If a browser-side Supabase client is introduced later, these policies become the primary control.

Settlement methodology

It follows the four-step approach the Federal Circuit and Family Court of Australia applies under s79 (married) and s90SM (de facto) of the Family Law Act 1975, as restated by the 2024 amendments.

flowchart LR
  S1["Step 1: Identify and value the pool"] --> S2["Step 2: Assess contributions"] --> S3["Step 3: Consider current and future circumstances"] --> S4["Step 4: Just and equitable check"]
  S1 --- N1["summariseDisclosure: low pool, high pool, referencePool = midpoint, disputed items, completeness"]
  S2 --- N2["Factors: INITIAL_CONTRIBUTION, INHERITANCE_GIFT, HOMEMAKER_PARENT. Percent band clamped 25 to 75"]
  S3 --- N3["Factors: INCOME_DISPARITY, CARE_OF_CHILDREN, HEALTH_CAPACITY, AGE_GAP. Points capped at 20"]
  S4 --- N4["Add points to contribution band, clamp 10 to 90, convert to dollars across low and high pool, attach notes, cautions, disclaimer"]
  style S1 fill:#EAF0F6,stroke:#103654
  style S2 fill:#EAF0F6,stroke:#103654
  style S3 fill:#EAF0F6,stroke:#103654
  style S4 fill:#FBE9DA,stroke:#E97819
    

Step 1, in plain English

Add up everything both people own and owe, including superannuation, which is shown separately because courts commonly treat it as its own pool. Where the two people disagree about a value, keep both: a 'low' pool using the values least favourable to a big total, and a 'high' pool using the most favourable. The model runs on the midpoint but reports dollars across the whole span.

Step 2, in plain English

Start at 50/50. Move toward the person who brought more in at the start, but less so the longer the relationship lasted, because early contributions get absorbed into the joint effort. Move toward the person who received an inheritance or gift during the relationship, at a discount because the money was usually spent on the household. Homemaker and parenting contributions are treated as equal in worth to earning income, so they do not move the number on their own; they offset the higher earner's financial contribution.

Step 3, in plain English

Look forward. Who earns less, or nothing? Who has the children most of the time, and are any under five? Does either person have a health problem that limits their capacity? Is one person much older with fewer working years left? Each of these moves the number toward the person with greater need, within a cap so future needs never swamp contributions.

Step 4, in plain English

Add the future needs adjustment to the contributions band, make sure the result stays inside 10% to 90%, convert to dollars across the low and high pool, and attach the notes about what widened the range and the cautions about what is missing. Then attach the disclaimer. The output is always a range.

Exact rules and constants

Constants live in TUNING and are the only numbers a legal reviewer needs to argue with. Points are percentage points of the net pool moving toward party A; negative means toward B. band(low, mid, high) rounds to one decimal.

Step 2 factors (group contributions)

Step 3 factors (group future_needs)

Step 4 arithmetic

lowA  = clamp(contrib.low  + min(fn.low, fn.high), 10, 90)
highA = clamp(contrib.high + max(fn.low, fn.high), 10, 90)
percentA = { low: min(lowA, highA), high: max(lowA, highA) }   // rounded to 0.1
percentB = { low: 100 - percentA.high, high: 100 - percentA.low }
amountA  = { low: max(pool.low.netTotal, 0) x percentA.low / 100,
             high: max(pool.high.netTotal, 0) x percentA.high / 100 }
amountB  = same shape with percentB

Range notes are added when items are disputed, when items have only one figure, and when the relationship is shorter than five years. Cautions are added for a small pool, for unvalued items, and when debts exceed assets on any view. The OUTPUT_DISCLAIMER constant is attached to every result.

Worked example: family-primary-carer

Produced by running computeResults(snapshot, 'A', new Date('2026-09-16')) against the real scenario with npx tsx. Nothing below is estimated. Sarah Whitfield is A, David Whitfield is B. Married, cohabited 1 June 2009, separated 15 March 2026: 16.8 years.

Step 1: the pool

Counts: 8 agreed, 3 disputed, 0 awaiting, 0 unvalued; completeness 1.0. referencePool = (1,644,000 + 1,743,500) / 2 = $1,693,750.

Step 2: contributions

Both initial contributions are zero and both inheritance figures are zero, so INITIAL_CONTRIBUTION and INHERITANCE_GIFT are skipped. HOMEMAKER_PARENT records that Sarah is the primary homemaker with a 0, 0, 0 band. Sum mid is 0, so the narrow band width 2.5 applies. Contributions for Sarah: 47.5% / 50% / 52.5%.

Step 3: future needs

Step 4: result

lowA = 47.5 + 16.5 = 64.0; highA = 52.5 + 20 = 72.5; both inside 10 to 90. David: 27.5% to 36%. Dollars: Sarah $1,052,160 (64% of the low pool) to $1,264,037.50 (72.5% of the high pool); David $452,100 to $627,660. Range note: '3 items have different values from each party, so the dollar range spans both views of the pool.' No cautions.

Split scenarios (perspective A, pool $1,738,000)

The Westpac loan follows the home Sarah keeps ('Follows the property Sarah Whitfield is keeping (refinance into their name)'), so her retained position is net of the mortgage. At an equal split the note reads 'Sarah Whitfield owes a balancing payment larger than their readily available cash. This usually means refinancing a property or selling an asset.' At the lower end David pays from cash or investments; at the midpoint he too would need to refinance or sell; at the upper end his non-super assets run out, so $104,000 is paid from cash-like assets and 'a superannuation splitting order of about $81,050 would move part of the balance'.

Split modelling rules

modelSplit in split-modeller.ts turns a percentage into a practical picture. It uses effectiveValue from the chosen perspective, so the two parties can see slightly different dollar figures until they agree.

Allocation rules, in order

1. Superannuation goes to its member (shared if jointly owned). Reason: 'Superannuation stays with the member unless a splitting order is made'.
2. An item flagged retainedBy goes to that party. Reason: 'X has asked to keep this'.
3. A solely owned item stays with its owner. Reason: 'Solely held, stays with the holder'.
4. A joint mortgage with no retain flag follows the property when every retained real_property item is kept by the same party: it is allocated to that party with the reason 'Follows the property X is keeping (refinance into their name)'. If retained properties are split between the parties, or none is retained, the next rule applies.
5. Jointly owned real estate, or a joint mortgage, with no retain flag is otherwise treated as sold and shared 50/50. Reason: 'Jointly owned, modelled as sold with proceeds shared' or 'Discharged from sale proceeds'. Half the sale value counts as cash-like for the payer.
6. Any other joint item is shared equally.

Balancing the books

• target = splitByPercent(max(poolTotal, 0), percentA); diffA = target.a - A.netRetained. Differences under one dollar are ignored.
• If the payer's cash-like assets (bank accounts and shares allocated to them, plus half of shared real estate) cover the amount: a balancing payment 'from cash, investments or sale proceeds'.
• Else if the payer's non-super net position covers it: a balancing payment, with the note that it usually means refinancing or selling.
• Else: pay what cash-like assets allow, take the rest from the payer's superannuation as a superSplitSuggestion, and if a remainder is still unreachable, say so and suggest revisiting who keeps what.
• Positions after adjustment and percentOfPool are reported for both parties. If the family home was modelled as sold, a note invites the user to mark it as kept to see the refinancing picture.

Standard scenarios

standardScenarios returns equal split (50), the low end, the midpoint and the high end of the indicative range, de-duplicated when two coincide. The results page shows these four first, before the range.

Asset discovery

Deep asset discovery is the paid differentiator. Each registry is a DiscoveryProvider behind a port with one method, search(subject), so the mocks shipped today can be swapped for real adapters without touching the domain or the UI. Findings are leads; a person accepts them into disclosure.

Gating

gateDiscovery(provider, tier, identityVerified) is a pure function: if the provider requires the discovery tier and the user is not on it, the request is blocked_tier; else if it requires verified identity and the user is not verified, blocked_identity; else queued. runDiscovery records the blocked request as-is (so the UI can explain), otherwise calls the adapter and records complete with findings or failed with the error. It never throws for expected outcomes.

sequenceDiagram
  autonumber
  actor U as User (discovery page)
  participant API as POST /api/matters/:id/discovery
  participant G as gateDiscovery
  participant R as runDiscovery
  participant P as Provider adapter (mock or real)
  participant DB as ad_discovery_requests
  participant DC as Disclosure
  U->>API: { provider: land_titles, subjectRole: B }
  API->>API: load session user (tier, identityVerified), check membership
  API->>G: gate(land_titles, tier, identityVerified)
  alt tier is free
    G-->>API: blocked_tier
    API->>DB: insert request status blocked_tier
    API-->>U: DiscoveryRequest (UI shows Upgrade to discovery)
  else identity not verified
    G-->>API: blocked_identity
    API->>DB: insert request status blocked_identity
    API-->>U: DiscoveryRequest (UI shows Verify identity)
  else queued
    API->>R: run(cmd, providers)
    R->>P: search(subject)
    P-->>R: Finding[] with confidence and suggestedItem
    R-->>API: request complete
    API->>DB: insert request with findings jsonb
    API-->>U: DiscoveryRequest with findings
    U->>API: POST .../findings/:findingId/accept
    API->>DC: createPoolItem with discoveryRef, recordValuation for requesting role, source discovery
    API-->>U: { item }
  end
    

Mock versus real integration, tiering and pricing

The mock adapters

MockProvider is deterministic: results depend only on the subject's full name (case-insensitive), so demos and tests are repeatable. Two personas have canned findings, Marcus Delfino (ASIC x3, PPSR x1, land titles x1, ATO super x2, including an SMSF and a lost AMP account) and Priya Raman (land titles x1, an explicit 'no records' from ASIC, ATO super x1). Any other name returns one 'No records found' finding that suggests trying previous names. mockVerifyIdentity verifies anyone with a date of birth. Optional latency simulates a real call.

Real integration notes

Tiering

Tier is a property of the user (id_users.tier), so a discovery-tier user can search on any matter they are a member of. POST /api/account/upgrade is a mock payment today; the roadmap names Stripe Checkout for the real flow.

Identity and authentication

The free tier needs no account. A user record is created only when someone chooses to save or invite. Authentication is delegated to the AuthProvider port; Settle then issues its own session.

Passwordless flows

Anonymous to saved migration

1. The user presses Save or Invite. The app remembers the intent and sends them to /sign-in.
2. After sign-in the app reads localStorage['settle.matter.v1'] and calls POST /api/matters { snapshot }. The server accepts the browser-generated ids, saves the aggregate, and creates a membership with snapshot.matter.ownerRole.
3. The browser keeps working with the same snapshot shape and switches to PUT /api/matters/:id on change. The local copy is kept as a cache until the first successful save, then cleared to avoid two sources of truth.
4. If the user already has matters, the dashboard offers to save the anonymous one as a new matter rather than merging.

Invitations and membership

• createInvitation validates the email, lowercases it, offers the opposite role, generates a UUID token, and sets a 14-day expiry (ttlDays default).
• acceptInvitation fails with INVITATION_NOT_PENDING, INVITATION_EXPIRED or INVITATION_EMAIL_MISMATCH ('Sign in with the email address the invitation was sent to'). Success adds a membership row; the unique (matter_id, role) index prevents two users holding the same role.
• Inviting moves the matter to joint mode permanently (inviteToJoint).
• Sessions are server-side rows with an expiry. Sign-out deletes the row and clears the cookie.

API contract

Route handlers live under src/app/api. All bodies and responses are JSON. Auth is the settle_session httpOnly cookie. Errors are { error: { code, message } } with status 400 (validation or domain error), 401 (no session), 403 (not a member), 404 (not found). user is { id, email, displayName, tier, identityVerified }.

Conventions

• Request bodies are validated with zod at the edge; domain errors (DomainError.code) map to 400 with the domain message, which is written for end users.
• The snapshot is validated as a whole. The server recomputes agreedValue on save and ignores any client-supplied value.
• In joint mode a PUT from role A may only change A's valuations, A's party row, shared structure (items, children, care) and retain flags; B's valuations are preserved from the stored copy. This prevents one side rewriting the other's claims.
• GET /api/demo/scenarios and POST /api/demo/:slug/login exist for demos only. They sign a visitor in as a seeded demo account without a code, so they must be disabled in production behind an environment flag (see Appendix B); the handler returns 404 when the flag is off.
• Phase two endpoints are listed in Section 14 and are not implemented.

UI theme and accessibility

Tokens are exported from src/lib/brand.ts as THEME and mirrored as Tailwind theme values. Red is reserved for warnings and destructive actions; disagreement is never red, because disagreement is normal.

Typography and tone

Plus Jakarta Sans (or the system stack when offline), 16px base, 1.6 line height, generous whitespace. Copy is calm and concrete: 'David pays Sarah $112,054' rather than 'a transfer may be required'. Second person, no jargon without a plain-English gloss, and every legislative term shown with its basis string from the factor.

Accessibility commitments (WCAG 2.2 AA)

• Colour is never the only carrier of meaning: chips carry text, party bars carry labels, the range shows numbers.
• Contrast: navy and ink on white exceed 7:1; terracotta on white is used for text at 18px bold or larger, or paired with an underline for links; body-size terracotta text is avoided.
• All forms have visible labels, described errors (aria-describedby), and the OTP input accepts paste of six digits.
• Keyboard: the stepper, chips with actions and scenario cards are reachable in DOM order; focus rings are visible on the navy palette.
• Money inputs accept whole dollars and format on blur; screen readers hear 'one million four hundred fifty thousand dollars', not digit strings.
• Reduced motion respected for the scenario rail; no auto-advancing content.
• The disclaimer is a landmark region (role="note", aria-label="Important notice") so it is discoverable by rotor.

Mobile and React Native readiness

The client wants a web app that works well on a phone now and a path to a native app later. Both are designed in, and docs/MOBILE.md is the working reference.

The web app is mobile-first

The React Native path

• Platform-agnostic core. src/core/index.ts is a barrel of everything that runs unchanged in the browser, Node and Hermes: the five contexts' domain code (plus runDiscovery), the MatterSnapshot read model and computeResults, the demo scenarios, createApi({ baseUrl, fetchImpl }), format helpers, BRAND and THEME, and the StorageAdapter type. tests/unit/core/platform-agnostic.test.ts walks its transitive imports and fails if any file touches window, document, localStorage, next or react. This is the future @settle/core workspace package.
• Persistence through a port. src/lib/client/storage.ts defines StorageAdapter { getItem, setItem, removeItem } where each method may return a value or a Promise. webLocalStorageAdapter wraps localStorage with try/catch so private mode and quota errors degrade to no-ops; memoryStorageAdapter serves tests and server rendering; an Expo app supplies an AsyncStorage adapter. Anonymous matters use the same key settle.matter.v1 on every platform, so a snapshot moves between web and native with no conversion.
• Same API, one change. The native app points createApi at the deployed Next.js API. The API today trusts the settle_session httpOnly cookie; native clients need it to also accept Authorization: Bearer <Supabase access token> and resolve the user the same way. Route shapes do not change; the mobile app injects the header through fetchImpl.
• Screens mirror the page list. Expo Router screens use the same route names as Section 4: start with a segmented control and native date pickers, children with a 0 to 14 nights slider, disclosure as an assets/debts/super tab bar with card rows and a floating add button, results with collapsed scenario cards and a sticky range bar, share using the native share sheet. Only the UI primitive layer is rewritten; providers and hooks are plain React and port as they are.
• Auth on device. Supabase Auth directly with expo-secure-store as the session store: email OTP through signInWithOtp and verifyOtp with one-time-code autofill, Google through expo-auth-session and a settle://auth/callback scheme, Facebook still unsupported.
• Deep links. Register settle:// and the universal link domain and map /invite/[token] to the invite screen; invitation emails keep the web URL, which opens the app when installed.
• Stays web only. API routes, Postgres and Drizzle, server-side auth providers, the SEO landing page, redirect-based Google sign-in, clipboard fallbacks and the PWA manifest.

flowchart TB
  subgraph core["@settle/core (today src/core/index.ts)"]
    direction LR
    DOM["Five contexts' domain + runDiscovery"]
    RM["MatterSnapshot, computeResults"]
    DEMO["Demo scenarios"]
    API["createApi({ baseUrl, fetchImpl })"]
    FMT["format helpers, BRAND, THEME, StorageAdapter type"]
  end
  subgraph web["apps/web: Next.js"]
    direction LR
    WUI["React pages + Tailwind"]
    WST["webLocalStorageAdapter"]
  end
  subgraph rn["apps/mobile: Expo React Native"]
    direction LR
    RUI["Expo Router screens + RN primitives"]
    RST["asyncStorageAdapter"]
    SEC["expo-secure-store session"]
  end
  SRV["Next.js API on Vercel: cookie session today, plus bearer token for native"]
  DB[("Postgres")]
  WUI --> core
  RUI --> core
  WUI -->|"settle_session cookie"| SRV
  RUI -->|"Authorization: Bearer (Supabase token)"| SRV
  SRV --> DB
  style core fill:#FBE9DA,stroke:#E97819
  style rn stroke-dasharray: 5 5
    

Sequence: extract src/core to packages/core and switch web imports (the guard test moves with it); add bearer-token support to the API auth helper; scaffold apps/mobile with MatterProvider on the AsyncStorage adapter; build screens in the order users meet them, results getting the most design time; then auth, invite deep link, dashboard, discovery and demo.

Testing strategy and coverage

Vitest runs unit and integration tests; Playwright runs a thin end-to-end layer. vitest.config.ts sets the coverage gates for CI: lines 80, functions 80, branches 75, statements 80, measured with v8 over src/contexts, src/read-models, src/demo, src/db, src/lib and src/components, excluding type declarations and the Supabase auth provider (exercised only against a live project).

Video walkthrough

scripts/record-walkthrough.ts (npm run demo:video) drives the app in Playwright, records six captioned chapters (intro, anonymous modelling, joint mode, complex pool and discovery, sign-in and share, mobile) with on-screen title cards and captions, and stitches them with ffmpeg into docs/video/walkthrough.mp4. It is regenerated on each tagged build and is the release artefact for client review.

Rules of the pyramid

• The engine is tested with golden snapshots of all six demo scenarios; a change to TUNING must update the snapshots and bump ENGINE_VERSION.
• Domain tests never touch the database. Repository tests never assert on engine output.
• E2E tests use the local auth provider and the demo login endpoint, never a mail inbox.
• The platform-agnostic guard runs with the unit suite so a stray browser import into the domain fails the build, not the native app.

Phase two: AI document parsing

Financial disclosure is slow because people transcribe documents by hand. Phase two lets a party upload bank statements, payslips, superannuation statements and tax returns; a worker extracts structured facts; a rule-based checker compares those facts with the disclosed pool and raises flags. Everything the AI produces is a proposal a person accepts or dismisses.

sequenceDiagram
  autonumber
  actor U as Party (browser)
  participant API as Route handlers
  participant STO as Supabase Storage (private bucket)
  participant DB as Postgres
  participant Q as Queue
  participant W as Parsing worker
  participant M as Extraction model
  participant C as Disclosure checker (rules)
  U->>API: POST /api/matters/:id/documents (kind, file)
  API->>STO: put object under matters/:id/:docId
  API->>DB: insert ph2_documents status uploaded
  API-->>U: { document }
  U->>API: POST /api/matters/:id/documents/:docId/parse
  API->>DB: status queued
  API->>Q: enqueue { documentId }
  Q->>W: deliver job
  W->>STO: fetch object (signed URL, short lived)
  W->>W: classify kind, OCR if scanned, redact account numbers to last 4 digits
  W->>M: extract with JSON schema for the kind
  M-->>W: extraction JSON + confidence per field
  W->>W: validate against schema, sanity checks (dates, totals reconcile)
  W->>DB: update ph2_documents extraction, parser_version, status parsed (or failed)
  W->>C: run checks for matter
  C->>DB: read dc_parties, dc_pool_items, dc_pool_item_valuations, all parsed extractions
  C->>DB: upsert ph2_disclosure_flags (open), skip duplicates
  U->>API: GET /api/matters/:id/flags
  API-->>U: flags with suggested actions
  U->>API: POST /api/matters/:id/documents/:docId/suggestions/:n/accept
  API->>DB: createPoolItem or recordValuation (source document), flag resolved
    

Components

Extraction schemas per document type

Stored in ph2_documents.extraction. Every money value is integer cents. Every field carries the page it came from and a confidence 0 to 1 in a parallel meta block (omitted below for brevity). Account numbers are kept as last four digits only.

{
  "kind": "bank_statement",
  "institution": "Westpac",
  "accountLast4": "4471",
  "accountType": "transaction",
  "holders": ["Sarah Whitfield", "David Whitfield"],
  "period": { "from": "2026-01-01", "to": "2026-03-31" },
  "openingBalance": 5810000,
  "closingBalance": 6200000,
  "transactions": [
    { "date": "2026-02-01", "description": "Salary BHP",
      "amount": 1245000, "category": "income" },
    { "date": "2026-02-03", "description": "Transfer to 88-2210",
      "amount": -200000, "category": "transfer_out",
      "counterpartyLast4": "2210" },
    { "date": "2026-02-05", "description": "Westpac home loan",
      "amount": -412000, "category": "loan_repayment" }
  ],
  "recurring": [
    { "description": "Transfer to 88-2210", "cadence": "monthly",
      "typicalAmount": -200000 }
  ]
}

{
  "kind": "payslip",
  "employee": "David Whitfield",
  "employer": "BHP Group Ltd",
  "employerAbn": "49004028077",
  "payDate": "2026-03-12",
  "period": { "from": "2026-02-27", "to": "2026-03-12" },
  "gross": 826900,
  "net": 561200,
  "tax": 231400,
  "superContribution": 95100,
  "superFund": "UniSuper",
  "ytd": { "gross": 15310000, "asAt": "2026-03-12",
           "financialYearStart": "2025-07-01" },
  "annualisedGross": 21600000,
  "allowances": [], "deductions": [
    { "description": "Salary sacrifice super", "amount": 50000 }
  ]
}

{
  "kind": "super_statement",
  "member": "David Whitfield",
  "fund": "UniSuper", "fundAbn": "91385943850",
  "memberNumberLast4": "3391",
  "productType": "accumulation",
  "asAt": "2026-06-30",
  "balance": 48600000,
  "preserved": 48600000,
  "insurance": { "death": 50000000, "tpd": 50000000 },
  "contributionsYtd": { "employer": 2050000, "personal": 0 }
}

tax_return (notice of assessment or return summary)

{
  "kind": "tax_return", "taxpayer": "Marcus Delfino", "financialYear": "2025",
  "taxableIncome": 32000000,
  "incomeItems": [
    { "label": "Salary and wages", "amount": 18000000 },
    { "label": "Dividends (franked)", "amount": 2400000, "source": "Delfino Holdings Pty Ltd" },
    { "label": "Trust distributions", "amount": 9500000, "source": "Delfino Family Trust" },
    { "label": "Rental income", "amount": 3600000, "propertyHint": "Bulimba QLD" }
  ],
  "deductions": [{ "label": "Rental property expenses", "amount": 1500000 }],
  "entitiesMentioned": [
    { "name": "Delfino Holdings Pty Ltd", "role": "shareholder" },
    { "name": "Delfino Family Trust", "role": "beneficiary" }
  ],
  "hasBusinessSchedule": true, "hasRentalSchedule": true, "hasCgtEvents": false
}

Gap and inconsistency detection

Rules are deterministic comparisons between extractions and the disclosed pool. Each produces at most one open flag per (rule, subject) pair. Severity: 1 informational, 2 should be resolved, 3 likely undisclosed asset or income.

Human in the loop

• Flags appear to both parties in joint mode, to the uploader only in solo mode. The party the flag concerns can resolve or dismiss; the other party sees the status. Dismissals record who and when.
• Accepting a suggestion goes through the existing domain functions (createPoolItem, recordValuation with source: 'document'). The other party's claim is never touched.
• Low-confidence fields (below 0.7) are shown for confirmation before any suggestion is offered.

Integration points

Security, privacy and compliance

Australian Privacy Principles

Family law and financial services boundaries

• Settle is not a legal practice and does not give legal advice. The OUTPUT_DISCLAIMER is rendered on every result. Marketing copy uses 'modelling' and 'indicative', never 'entitlement' or 'what you will get'.
• Settle does not give financial product advice. It reports balances and splits the user entered; it does not recommend funds, products or investment actions. Super split suggestions are described as an amount that 'would need to move', with the note that a splitting order requires legal process.
• The duty of full and frank disclosure belongs to the parties. Discovery and phase two flags help a party meet it and do not replace formal disclosure or court processes.
• Family violence: the invitation flow never reveals the inviter's location or IP; a party can leave a matter; support links to 1800RESPECT and Family Relationship Advice Line are in the footer. Sensitive data about the other party is limited to what settlement needs.

Application security notes

• Invitation tokens are UUIDs, single use, 14-day expiry, and require the accepting email to match; there is no enumeration endpoint.
• OTP codes are hashed at rest, expire in 10 minutes and are single use; rate limiting on /api/auth/start per email and IP is required before launch.
• Route handlers validate every body with zod and never trust client-supplied agreedValue, tier or identityVerified.
• Destructive actions (remove item, revoke invitation, delete matter, delete document) require confirmation and are the only red interface elements.

Roadmap and open questions

Open questions

Appendix

A. Legal and domain glossary

B. Environment variables

C. Repository layout

src/
  contexts/                    bounded contexts (DDD). No context imports another's infrastructure.
    shared/domain              Money (integer cents), Result, ids, dates
    identity/                  users, sessions, tiers, invitations; AuthProvider port
      infrastructure/          LocalAuthProvider (dev: code 123456), SupabaseAuthProvider (prod)
    disclosure/domain          Matter, Party, Child, PoolItem with per-party valuations, agreedValue rule
    parenting/domain           CareArrangement, care %, cost %, primary carer
    settlement-modelling/      assessSettlement (4-step, deterministic), modelSplit, standardScenarios
    asset-discovery/           domain (port, gating), application (runDiscovery), infrastructure (mock-providers)
  read-models/matter-snapshot  MatterSnapshot = whole matter as one JSON aggregate; computeResults()
  demo/scenarios               six demo scenarios built via domain constructors (deterministic ids)
  db/                          Drizzle schema (prefixes id_, dc_, pa_, ad_, ph2_), client, MatterRepository
  lib/                         brand + theme tokens, server helpers (env, http, repositories)
  app/                         Next.js App Router (UI + /api route handlers)
drizzle/                       0000_calm_triathlon.sql and meta
tests/unit, tests/integration, tests/e2e
docs/ARCHITECTURE.md, docs/spec/

D. Document conventions

Straight quotes throughout. Money in the prose is whole dollars; money in code and the database is integer cents. 'A' and 'B' are roles, never genders. Dates are ISO in code and Australian in prose. This document was generated against the repository state on 16 September 2026 and should be regenerated when ENGINE_VERSION, the schema, or the API table changes.