Product deal engine

ID	MOD-109
System	SD08
Repo	bank-app
Build status	Not started
Deployed	No

---

What it does

MOD-109 manages agent-initiated bespoke product deals. When an agent is speaking with a customer (via call, chat, or in-branch) and determines that a personalised arrangement would retain or acquire the customer, they propose specific deal terms through the back-office UI (MOD-083). MOD-109 validates those terms, routes them through the appropriate authorisation tier, presents the accepted deal to the customer, and logs the full lifecycle immutably.

Deal vs offer distinction

• MOD-108 product offer — system-initiated; generated without agent involvement; terms derived algorithmically; no authorisation workflow; sent to customer via app or automated channel.
• MOD-109 product deal — agent-initiated; triggered by a direct customer interaction; terms may include bespoke rate reductions, fee waivers, or enhanced limits; requires authorisation if outside the agent's self-approval tolerance.

Why it exists

Direct customer interactions are the bank's highest-conversion sales channel. When a retention conversation is in progress, the agent needs the ability to propose a competitive deal in real time — without a multi-day approval process that causes the customer to leave. MOD-109 provides the authorisation workflow and audit trail that make this operationally possible while maintaining the governance and consistent-treatment obligations of CON-006 and CON-001.

Authorisation tiers

Three tiers with configurable tolerance bands:

Tier	Who	Rate reduction tolerance	Fee waiver tolerance	Limit increase tolerance
1 — Agent self-approve	Frontline agent	≤ 25 bps	≤ $500	≤ $2,000
2 — Team manager	Team manager (back-office role)	≤ 50 bps	≤ $2,000	≤ $10,000
3 — Product/pricing committee	Senior approval (product governance role)	Any	Any	Any

All tolerance values are configurable in the deal_authorisation_config table — the tier structure is fixed but the numbers are IaC-managed.

Deal lifecycle

PROPOSED (agent submits deal terms)
  → SELF_APPROVED (within Tier 1 tolerance — proceeds immediately to PRESENTED)
  → PENDING_APPROVAL (exceeds Tier 1 — routed to Tier 2 approver queue)
    → APPROVED (Tier 2 approver confirms)
    → REFERRED (Tier 2 refers to Tier 3 product/pricing committee)
      → APPROVED
      → DECLINED (deal outside policy; agent notified with reason)
  → PRESENTED (approved deal terms communicated to customer)
    → ACCEPTED (customer agrees; triggers application or account modification)
    → REJECTED (customer declines)
    → EXPIRED (customer did not respond within validity window — default 48 hours for deals)

Data model

-- app.product_deals (Postgres — bank_app)
CREATE TABLE app.product_deals (
  deal_id               uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  party_id              uuid NOT NULL,
  product_id            text NOT NULL,
  jurisdiction          text NOT NULL CHECK (jurisdiction IN ('NZ','AU')),
  proposed_terms        jsonb NOT NULL,        -- rate, limit, fee waiver as proposed
  approved_terms        jsonb,                 -- may differ if approver modifies terms
  approval_tier         int NOT NULL CHECK (approval_tier IN (1,2,3)),
  proposed_by           text NOT NULL,         -- staff_id of proposing agent
  approved_by           text,                  -- staff_id of approver (null if tier 1 self-approved)
  approval_rationale    text,
  status                text NOT NULL CHECK (status IN (
                          'PROPOSED','PENDING_APPROVAL','APPROVED','DECLINED',
                          'PRESENTED','ACCEPTED','REJECTED','EXPIRED')),
  interaction_id        uuid,                  -- links to MOD-054 call or chat session
  proposed_at           timestamptz NOT NULL DEFAULT now(),
  approved_at           timestamptz,
  presented_at          timestamptz,
  responded_at          timestamptz,
  expires_at            timestamptz NOT NULL,
  created_at            timestamptz NOT NULL DEFAULT now()
);

-- app.deal_events (append-only lifecycle log)
CREATE TABLE app.deal_events (
  event_id    uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  deal_id     uuid NOT NULL REFERENCES app.product_deals(deal_id),
  event_type  text NOT NULL,
  actor_id    text NOT NULL,   -- staff_id or 'system'
  event_at    timestamptz NOT NULL DEFAULT now(),
  detail      jsonb
);

Events

• product.deal_approved — on Tier 1 self-approval or Tier 2/3 approval; triggers presentation to customer.
• product.deal_accepted — customer accepts; triggers account modification or new application workflow in the relevant system domain.
• product.deal_declined — approval tier declined; carries decline reason for agent feedback.

---

Module dependencies

Depends on

Module	Title	Required?	Contract	Reason
MOD-105	Product eligibility engine	Required	—	Customer must be eligible for the product before any deal can be proposed — eligibility is verified at deal creation time.
MOD-083	Agent assist & compliance coaching panel	Required	—	Agent assist provides the interface through which deals are proposed; deal creation is embedded in the agent interaction workflow.
MOD-047	Agent action logger	Required	—	Every deal proposal and authorisation is an agent action logged via the agent action logger.
MOD-104	AWS shared infrastructure bootstrap	Required	—	AWS shared infrastructure provisioned by MOD-104 is required before this module can be deployed.
MOD-103	Neon database platform bootstrap	Required	—	Neon database provisioned by MOD-103 must exist before this module can read or write Postgres.

Required by

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

---

Policies satisfied

Policy	Title	Mode	How
CON-006	Product suitability and governance	GATE	Agent-proposed deal terms are validated against product floor/ceiling rules and eligibility constraints before being presented to the customer — no deal outside configured tolerance can be authorised without the required approval tier.
CON-004	Product Disclosure & Sales Practice Policy	LOG	Every deal proposal, authorisation decision, and customer acceptance or rejection is logged immutably in the deal audit trail with the agent ID, authoriser ID, terms, and timestamp.
CON-001	Customer Fairness & Conduct Policy	LOG	Deal audit trail enables periodic review for consistent treatment — agents cannot offer materially different deals to similarly situated customers without an auditable reason.

---

Capabilities satisfied

(No capabilities mapped)

---

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