Skip to content

Facility component self-service
ID MOD-164
System SD08
Repo bank-app
Build status Not started
Deployed No

Purpose

Provides the customer-facing self-service interface in the bank app for managing components within a Flexible Loan Facility (PRD-024). Exposes four primary flows: facility overview, component rollover, add component, and partial prepayment. All state-changing flows involving a fixed-rate component require a binding break-cost disclosure acknowledgement via MOD-050 before the action is submitted.

Context

The product research document (Section 4.3, Phase 2) identifies self-service component management as the feature that differentiates the FLF from a simple fixed-rate loan. BNZ retail customers commonly operate in this mode; NAB Business Markets Loan customers rely on it for cost-effective rate management. Without in-app self-service, every component rollover requires a banker-assisted interaction — operationally expensive and a poor customer experience for what should be a routine event.

This module is the app layer only. No component data is stored here; everything reads from MOD-162 and the break-cost service MOD-163. State changes are submitted to MOD-162 APIs. The module's own scope is the UI flows, the disclosure gate wiring, and the break-cost display logic.

Flows

Facility and component overview

The landing screen for a customer's Flexible Loan Facility shows:

  • Total facility limit and expiry date
  • Current outstanding balance (sum of all active component principals)
  • Principal-weighted effective interest rate (from MOD-162)
  • Each active component as a card: component type (FIXED/FLOATING), principal, rate (or benchmark + margin), maturity date (FIXED only), days to maturity, indicative break cost (fetched from MOD-163 on screen load — displayed as a cost or benefit)
  • A call-to-action per component: Roll component (approaching maturity), Add component (from floating), Prepay (fixed components)

Indicative break-cost figures on the overview screen are informational only — no acknowledgement is required to view them. They are refreshed on each screen load from MOD-163.

Rollover flow

Available from 90 days before a fixed component's maturity date, and at any time for early rollover.

  1. Customer selects a fixed component and taps Roll.
  2. The app displays the current indicative break cost (if rolling early) and the available rate menu for the replacement component (fixed terms and current rates from MOD-162 configuration).
  3. Customer selects rate type, term, and principal allocation for the new component.
  4. If rolling early (before maturity): the app calls MOD-163 for a binding break-cost calculation. MOD-050's requireDisclosure() gate is invoked with the binding calculation ID. The customer must acknowledge the break-cost disclosure before proceeding.
  5. If rolling at maturity: no break cost applies. MOD-050 issues a rate-election disclosure (new rate and terms) that must be acknowledged before confirmation.
  6. On confirmation, the rollover instruction is submitted to MOD-162 (update-component-status + create-component).

If no rollover is elected before maturity, the component automatically converts to the floating residual (handled by MOD-162's daily maturity sweep). The app sends a notification via MOD-063 at 90, 60, and 30 days before maturity.

Add component

Allows the customer to convert a portion of the floating residual into a new fixed-rate component.

  1. Customer taps Add component from the facility overview.
  2. App shows the available floating residual balance and the rate menu.
  3. Customer selects principal amount, rate, and term. The principal must be ≥ the configured minimum component size and must not exceed the current floating residual balance.
  4. MOD-050 requireDisclosure() is invoked for the new component terms (rate, total interest, break-cost mechanics). Customer acknowledges.
  5. On confirmation, the instruction is submitted to MOD-162 (create-component), which reduces the floating residual and recomputes the effective rate.

Partial prepayment

Allows the customer to reduce the principal of a fixed-rate component early (or repay it in full).

  1. Customer selects a fixed component and taps Prepay.
  2. Customer enters the prepayment amount (partial or full).
  3. App calls MOD-163 for a binding break-cost calculation on the nominated amount.
  4. MOD-050 delivers the break-cost disclosure and captures acknowledgement. The disclosure must present: the break cost or benefit amount, the formula inputs (contracted rate, current market rate, remaining term), and a plain-language explanation of what the break cost represents.
  5. On acknowledgement, the prepayment instruction is submitted to MOD-162 (update-component-status), which reduces the component principal and increases the floating residual. If full prepayment, the component status transitions to PREPAID.
  6. Funds for any break cost are collected at the time of prepayment via MOD-001. A break benefit is credited to the customer's nominated account.

Notifications

MOD-063 is invoked by this module (or by MOD-162 events) to dispatch:

  • 90/60/30-day pre-maturity alerts prompting the customer to elect a rollover
  • Rollover confirmation notification after a component is successfully rolled
  • Prepayment confirmation including break cost amount paid or break benefit received
  • Effective-rate change notification when the principal-weighted rate shifts

Implementation notes

All break-cost figures displayed in the UI must originate from MOD-163 — no client-side approximation. The indicative figure shown on the overview screen and the binding figure confirmed in a change flow must use the same formula and the same market rate source. A visual discrepancy between the two (due to rate movements between screen load and confirmation) must be explained to the customer rather than silently updating the figure.

The add-component and rollover flows must handle the concurrent-edit case: if a second device or a background system event changes the floating residual between the customer seeing the available balance and submitting the component creation, the MOD-162 handler must reject with a LIMIT_EXCEEDED or INSUFFICIENT_FLOATING error and the app must prompt the customer to refresh and retry.

Rate quotes in the add-component and rollover flows have a validity window (configured in MOD-162, default 15 minutes). If the customer takes longer than the validity window, the quote must be refreshed before the instruction can be submitted.

Module dependencies

Depends on

Module Title Required? Contract Reason
MOD-162 Loan facility & component manager Required — All facility and component data — limit, component details, effective rate, maturity dates, outstanding principals — is sourced from the loan facility component manager APIs.
MOD-163 Break-cost calculator Required — Indicative and binding break-cost quotations are obtained from the break-cost calculator before any rollover, add-component, or partial prepayment flow is confirmed.
MOD-050 Disclosure enforcement module Required — Break-cost disclosure acknowledgement gate is enforced via the disclosure enforcement library before any state-changing component action is submitted to MOD-162.
MOD-068 Authentication & session management Required — JWT access token issued by MOD-068 carries customer_id and jurisdiction claims required for component data retrieval and break-cost calculation authorisation.
MOD-103 Neon database platform bootstrap Required — Neon database connection parameters provisioned by MOD-103 are required for read operations on facility and component data.
MOD-104 AWS shared infrastructure bootstrap Required — AWS shared infrastructure provisioned by MOD-104 (SSM parameters, IAM roles, Lambda execution role) is required before this module can be deployed.

Required by

(No modules in this wiki currently declare a dependency on this module.)

Policies satisfied

Policy Title Mode How
CON-005 Fee & Pricing Transparency Policy GATE Prepayment and rollover flows in the self-service UI route through MOD-050 for binding break-cost acknowledgement before any fixed-rate component change is submitted — no UI path completes a fixed-rate component change without a confirmed acknowledgement record.
CRE-009 Fixed-Rate Component Break-Cost Methodology Policy LOG On-demand indicative break-cost quotes are accessible to any authenticated customer with an active facility at any time via the component detail screen, satisfying the on-demand quotation transparency requirement without requiring a formal change request.

Capabilities satisfied

(No capabilities mapped)

Part of SD08 — Customer App & Back Office Platform Compiled 2026-05-22 from source/entities/modules/MOD-164.yaml