Property security and LVR management¶


ID	`MOD-115`
System	SD05
Repo	`bank-credit`
Build status	Deployed
Deployed	Yes
Last commit	`19b0610`

Purpose¶

Registers and monitors the property security instrument attached to each residential mortgage. Calculates current loan-to-value ratio (LVR) in real time using the outstanding loan balance (sourced from MOD-003) and the most recent property valuation on record. Enforces LVR policy gates at origination — a loan cannot proceed to settlement unless a registered security instrument is recorded and the calculated LVR falls within policy limits. Monitors ongoing LVR against policy thresholds and emits breach events for credit team review.

Compliance rationale¶

RBNZ BS19 requires the bank to measure, restrict, and report lending in defined LVR bands. Specifically, the bank must not exceed prescribed portfolio concentration limits in high-LVR categories (above 80% for owner-occupier; above 70% for investor). This module provides the per-loan LVR calculation and the daily LVR snapshot table that feeds those portfolio reports.

APRA APS 220 requires ongoing collateral adequacy monitoring for secured credit exposures. The daily LVR snapshot and valuation currency checks in this module satisfy that requirement.

CRE-005 (concentration risk policy) requires that LVR band distribution is tracked at portfolio level and reported to the credit risk committee. This module is the sole source of LVR band data for that report.

REP-002 (prudential reporting policy) requires that LVR band distribution is included in RBNZ and APRA prudential returns. This module's output feeds those returns directly.

Commercial rationale¶

LVR is the primary driver of mortgage pricing. LVR bands map to margin tiers in the rate sheet — a borrower at 70% LVR pays a materially lower rate than a borrower at 85% LVR. Accurate, real-time LVR data is therefore a direct revenue input.

Ongoing LVR monitoring creates two commercial opportunities. When LVR improves (property value rises or balance reduces), the bank can proactively offer a better rate tier — a retention and cross-sell trigger. When LVR deteriorates (property value falls), the bank can act early through a collateral call or rate repricing rather than discovering the problem at default.

Data model¶

-- credit.property_securities
CREATE TABLE credit.property_securities (
  security_id        UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  loan_id            UUID NOT NULL REFERENCES credit.loans(loan_id),
  title_reference    TEXT NOT NULL,
  property_address   JSONB NOT NULL,  -- {street, suburb, city, postcode, country}
  property_type      TEXT NOT NULL CHECK (property_type IN ('residential','rural_residential','apartment','townhouse')),
  registered_at      TIMESTAMPTZ NOT NULL,
  registration_number TEXT,
  status             TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','discharged','suspended')),
  discharged_at      TIMESTAMPTZ,
  created_at         TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- credit.property_valuations
CREATE TABLE credit.property_valuations (
  valuation_id       UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  security_id        UUID NOT NULL REFERENCES credit.property_securities(security_id),
  valuation_date     DATE NOT NULL,
  valuation_amount   NUMERIC(18,2) NOT NULL,
  valuation_type     TEXT NOT NULL CHECK (valuation_type IN ('full','desktop','avm','indexed')),
  valuer_reference   TEXT,
  source             TEXT NOT NULL,  -- 'registered_valuer','avm','index_update'
  created_at         TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- credit.lvr_snapshots (materialised daily)
CREATE TABLE credit.lvr_snapshots (
  snapshot_id        UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  loan_id            UUID NOT NULL,
  security_id        UUID NOT NULL,
  snapshot_date      DATE NOT NULL,
  outstanding_balance NUMERIC(18,2) NOT NULL,
  current_valuation  NUMERIC(18,2) NOT NULL,
  lvr_pct            NUMERIC(7,4) NOT NULL,  -- e.g. 0.7823 = 78.23%
  lvr_band           TEXT NOT NULL,  -- '<60','60-70','70-80','80-90','>90'
  policy_breach      BOOLEAN NOT NULL DEFAULT false,
  created_at         TIMESTAMPTZ NOT NULL DEFAULT now(),
  UNIQUE (loan_id, snapshot_date)
);

Key operations¶

1. Security registration at settlement¶

Called by MOD-116 on drawdown. Inserts a record into credit.property_securities with the title reference, property address, property type, and registration details. Records the origination valuation in credit.property_valuations. Calculates the origination LVR and writes the first credit.lvr_snapshots record. If the calculated LVR exceeds the policy limit configured for the product, the settlement gate is blocked and an error is returned to the calling workflow.

2. LVR calculation¶

lvr = outstanding_balance / current_valuation

Run daily via a scheduled batch job (after MOD-003 end-of-day balance close) and on each valuation update. The result is written to credit.lvr_snapshots. The LVR band is derived from configurable thresholds: <60, 60-70, 70-80, 80-90, >90. Band boundaries are configurable to allow for regulatory threshold changes without a code deployment.

3. LVR breach detection¶

After each LVR calculation, the result is compared against the policy breach threshold for the product (configurable per product, per jurisdiction). If LVR exceeds the threshold, the policy_breach flag is set on the snapshot record and a bank.credit.lvr_breach_detected event is emitted. This event triggers an ALERT in MOD-063 (notification orchestration) to the credit team and flags the loan for review in the back-office queue.

4. AVM index update¶

MOD-085 provides quarterly property price index updates by suburb/region. On receipt of an index update, this module applies the index factor to all credit.property_valuations records with valuation_type = 'indexed' or where the most recent full valuation is older than the index refresh threshold (configurable, default 12 months). A new credit.property_valuations record is inserted with source = 'index_update' and valuation_type = 'indexed'. LVR snapshots are recalculated for all affected loans immediately after index update.

5. Security discharge¶

Called by MOD-116 on loan payoff or external refinance. Sets the status field on credit.property_securities to discharged and records discharged_at. Emits a bank.credit.security_discharged event. MOD-001 posts the security release accounting entry.

Requirements satisfied¶

FR-521 — System shall register a property security instrument against a loan at settlement and prevent drawdown if the security record is absent or LVR exceeds the policy gate threshold.

FR-522 — System shall calculate LVR for each active secured loan daily using end-of-day outstanding balance and the most recent valuation, and store the result in credit.lvr_snapshots.

FR-523 — System shall emit a bank.credit.lvr_breach_detected event and set policy_breach = true on the snapshot record when a loan's LVR exceeds the configured policy threshold.

FR-524 — System shall update property valuations on receipt of AVM index data from MOD-085 and recalculate LVR snapshots for all affected loans within the same batch run.

Module dependencies¶

Depends on¶

Module	Title	Required?	Contract	Reason
MOD-001	Double-entry posting engine	Required	—	Drawdown and security release events are posted via the double-entry engine.
MOD-066	Collateral & security management	Required	—	Collateral and security management provides the security instrument record that this module monitors.
MOD-085	Market rates ingestion & normalisation	Optional	`contract/events/`	v1 ships with manual revaluation only via MOD-066; automated index-driven revaluation deferred until MOD-085 adds a property index feed.

Required by¶

Module	Title	As	Contract
MOD-116	Mortgage servicing engine	Hard dependency	—
MOD-121	Construction loan drawdown engine	Hard dependency	—

Policies satisfied¶

Policy	Title	Mode	How
CRE-001	Credit Risk Management Policy	`GATE`	Loan cannot settle without a registered security instrument recorded and LVR calculated within policy limits.
CRE-005	Concentration Risk Policy	`CALC`	Current LVR is calculated daily and contributes to concentration risk reporting at portfolio level.
CLQ-002	Liquidity Risk Management Policy	`CALC`	Secured loan balances and collateral values are included in liquidity stress calculations via this module's output.
REP-002	Prudential Reporting Policy	`CALC`	LVR band distribution is reported in prudential returns (RBNZ BS19 / APRA APS 220).

Capabilities satisfied¶

(No capabilities mapped)

Part of SD05 — Credit Decisioning & Loan Platform Compiled 2026-05-22 from source/entities/modules/MOD-115.yaml