ADR-020: Customer financial automation rules engine¶
| Status | Accepted |
| Date | 2026-04-10 |
| Deciders | CTO, Head of Product |
| Affects repos | bank-app, bank-core, bank-payments |
Status¶
Accepted — 2026-04-10
Context¶
Customers who set up automation rules have significantly higher retention and deposit growth than those who don't. Automation rules reduce cognitive load — the customer configures their financial behaviour once and the bank executes it reliably. For the bank, automation rules increase deposit stability and reduce transaction support costs.
The question is whether to build a rules engine in-house or use a third-party rules platform. Given the tight integration required with the real-time ledger, EventBridge domain events, and the payment validation pipeline, this is a clear in-house build.
Decision¶
Build a customer-configurable automation rules engine as part of the bank-core and bank-app repositories. Rules are stored in Postgres, evaluated on EventBridge events and scheduled triggers, and executed through the standard payment and transfer services — subject to the same pre-payment validation gates as manual payments.
Rule structure: trigger + condition + action¶
Every automation rule is a combination of three components:
Trigger: What event initiates the rule evaluation? - Income received (salary credit above a threshold) - Balance threshold crossed (above or below) - Scheduled date (day of month, weekly) - Spend category hits a limit - FX rate crosses a level - Any card transaction (for round-up rules)
Condition (optional): Additional filter on the trigger. - "if balance exceeds NZD 2,500 AND has been above for 7 consecutive days" - "if salary amount is greater than NZD 2,000" - "if NZD/AUD rate is greater than 0.930"
Action: What the bank executes when trigger fires and condition passes. - Transfer a fixed amount to a specified account - Transfer a percentage of the triggering amount - Round up to nearest NZD 1 and sweep difference - Send a notification only (no transfer) - Transfer to AU account at current FX rate
The six core rules at launch¶
1. Payday sweep¶
Trigger: Salary/income credit > NZD N Action: Transfer X% to nominated account
Most powerful retention tool. Customers who sweep a percentage of salary to savings immediately after payday have 40% higher 12-month balances than those who don't. The bank benefits from the stable deposit growth. The customer benefits from saving before they can spend.
2. Round-up savings¶
Trigger: Any debit card transaction Action: Round up to nearest NZD 1, sweep difference to savings
Classic micro-savings behaviour. A NZD 47.30 grocery purchase sweeps NZD 0.70. Low individual impact, significant cumulative effect. 84 round-ups in a month = NZD 41 saved automatically. Customers respond well because it feels frictionless.
3. Idle balance sweep¶
Trigger: Everyday balance > NZD N for > 7 consecutive days Action: Transfer excess above buffer to savings
Pairs with the idle cash insight card (ADR-019). The insight card offers to set up the rule; the rule executes the behaviour automatically going forward. Customers who set this up never leave money sitting in the everyday account earning 0%.
4. Low balance safety net¶
Trigger: Everyday balance falls below NZD N Action: Pull NZD M from savings to everyday
Prevents declined payments and overdraft fees. The customer sets their safety net threshold. The rule fires before the balance hits zero, not after. This is a customer-protective rule, not a bank revenue rule.
5. NZD/AUD rate alert sweep¶
Trigger: NZD/AUD rate crosses a customer-set threshold (e.g. > 0.930) Action: Transfer NZD N to AU account at current rate
Customers who regularly move money between NZ and AU benefit from rate-triggered automation. They set the rate at which they want to execute and the amount. When the rate hits their level, the transfer happens automatically — no need to check rates daily.
6. Spend category budget alert¶
Trigger: Spend in category X exceeds NZD N in current calendar month Action: Send notification only (no automatic transfer)
Notification-only rule. Customers who want to track a budget category get an alert when they're approaching or over their self-set limit. This is a phase 1 rule that enables the AI coaching feature in phase 2 (ADR-009).
Technical design¶
Rule storage¶
Rules stored in an automation_rules table in Postgres:
id, customer_id, rule_type, trigger_config (JSONB),
condition_config (JSONB), action_config (JSONB),
status (active/paused/deleted), created_at, last_executed_at,
execution_count, total_transferred
Rule evaluation¶
Event-driven rules (salary credit, balance threshold, card transaction, FX rate): - EventBridge rule in bank-core subscribes to relevant domain events (ADR-029, superseded by ADR-051; see ADR-051 for current EventBridge bus naming convention) - On each event, evaluates applicable rules for the customer - If trigger fires and condition passes, creates an execution task - Execution task goes through the standard payment validation pipeline (MOD-020)
Scheduled rules (day of month, weekly): - Scheduled job in bank-core checks for rules due to fire - Same execution path as event-driven rules
Execution path¶
Every rule execution goes through the same pre-payment validation as a manual payment: - Balance sufficiency check (MOD-020) - Payment limit check (MOD-021) - Sanctions check (MOD-013) - Fraud score check (MOD-023)
A rule cannot bypass any payment gate. If a sweep would overdraw the account, it does not fire — the rule waits for the next evaluation. This is enforced at the execution level, not at the rule configuration level.
Audit trail¶
Every rule execution logged to MOD-051 (financial automation rules engine): - Rule ID, customer ID - Trigger event that fired the rule - Condition evaluation result - Action executed (or reason not executed) - Amount transferred, accounts involved - Timestamp
Customer-visible execution history in the app. They can see every time a rule has run, what triggered it, and what it did.
Customer experience design¶
Rule creation is conversational. The rule creation flow walks the customer through trigger → condition → action in plain language. "When my salary lands, transfer 20% to NZ Savings." No IFTTT syntax, no code, no complex configuration.
Rules are transparent. The rules screen shows every active rule, when it last ran, how much it has transferred in total, and whether it is currently paused. "Payday sweep · Last ran 21 Mar · Moved NZD 760 · Saved NZD 4,940 total this year."
Pause is frictionless. Customers can pause a rule without deleting it. Paused rules can be resumed. No friction in the pause/resume flow — the bank should not make it hard to pause because that drives customers to delete instead.
Failed executions are communicated. If a rule fails (e.g. insufficient balance for a sweep), the customer receives a notification explaining what happened and what threshold was not met.
Principles alignment¶
| Principle | Assessment | Notes |
|---|---|---|
| AP-001 KISS | ✓ | Trigger + condition + action model; JSONB config is flexible without complexity |
| AP-003 Compliance | ✓ | Rules go through the same payment gates as manual payments — no compliance bypass |
| AP-005 Customer driven | ✓ | Rules serve the customer's financial goals, not the bank's |
| AP-007 Evolution | ✓ | New trigger types and action types added without schema changes (JSONB config) |
Perspectives¶
| Perspective | Assessment | Notes |
|---|---|---|
| Performance & Scalability | ✓ | Event-driven evaluation; async execution through payment pipeline |
| Usability | ✓ | Conversational setup; transparent execution history |
| Integration | ✓ | EventBridge-driven; same payment pipeline as manual transfers |
| Resilience & Availability | ✓ | Failed executions are logged and communicated; rules are idempotent |
| Security | ✓ | Rules execute through same gates as manual payments — no privilege elevation |
See perspectives.md for how to use these evaluation lenses.
Relevant viewpoints¶
- Functional viewpoint — Rule creation flow; six core rule types; execution history
- System viewpoint — EventBridge event triggers; rule evaluation engine; payment pipeline execution
- Information viewpoint —
automation_rulestable schema; execution log structure - Operational viewpoint — Failed execution monitoring; rule volume dashboard; edge case handling
See viewpoints.md for guidance on producing these viewpoints.
Signoff record¶
| Date | Name | Role | Status |
|---|---|---|---|
| 2026-04-10 | Ross Millen | CTO | Approved |
| 2026-04-10 | Ross Millen | Head of Architecture | Approved |
| 2026-04-10 | Ross Millen | Head of Data | Approved |
Capabilities¶
| Capability | Description | Relationship |
|---|---|---|
| CAP-006 | Foreign exchange — live rates, rate lock | enabled — NZD/AUD rate-triggered sweep rule executes FX transfer automatically |
| CAP-007 | Scheduled & recurring payments | enabled — scheduled date trigger executes recurring payment rules |
| CAP-053 | Round-up savings (spare change) | enabled — round-up rule is one of the six core rule types |
| CAP-054 | Goal-based savings with target date | enabled — payday sweep rule supports savings goal behaviour |
| CAP-064 | Customer automation rules (sweep, round-up, rate alert, safety net) | enabled — all six core rule types defined and designed here |
Related decisions¶
| ADR | Title | Relationship |
|---|---|---|
| ADR-019 | Intelligent customer home screen and financial intelligence layer | home screen cards suggest and link to rule creation |
| ADR-029 (superseded by ADR-051; see ADR-051 for current EventBridge bus naming convention) | Domain event routing via Amazon EventBridge | event-driven rules subscribe to EventBridge domain events |
All ADRs
Compiled 2026-05-22 from source/entities/adrs/ADR-020.yaml