Synthetic transaction engine

ID	MOD-159
System	SD07
Repo	bank-platform
Build status	Deployed
Deployed	Yes
Last commit	ed31838579b1d40b7fefc77a1acfd61ddb56993b

---

Purpose

MOD-159 generates synthetic banking activity on a schedule, making dev and UAT environments look and behave like a bank that is actively operating rather than a set of deployed modules against an empty database. It gives confidence that independently-deployed modules are continuously working together — if the engine runs successfully, the ledger, balance engine, account state machine, payment validation, audit trail, and notification modules are all functioning end-to-end.

The commercial reason is stakeholder and operator confidence. Any stakeholder logging into UAT on any given day should see accounts with recent transactions, current balances, and notification history — a realistic simulation of customer activity.

Architecture

EventBridge Scheduler
  └── triggers synthetic-transaction-generator Lambda
        │
        ├── reads seed customer list from DynamoDB (written by MOD-158)
        ├── reads current balances from MOD-003 (Neon read-replica)
        ├── reads account states from MOD-007 (Neon)
        │
        └── for each active account with sufficient balance:
              └── publishes PaymentInstructionRequested event to EventBridge
                    └── standard payment processing pipeline
                          MOD-020 (validation)
                          → MOD-001 (posting)
                          → MOD-003 (balance update)
                          → MOD-022 (audit trail)
                          → MOD-063 (notification)

The engine does not write to the database directly. All transactions flow through the same EventBridge events that real customer transactions use, exercising the full pipeline on every run.

Schedule and volume

Stage	Schedule	Runs/day	Transactions/run	Daily total
dev	Tue and Thu, 09:00 NZST	~0.3	50	~15 avg
uat	08:30 and 16:30 NZST	2	~200	~400
prod	Disabled	—	—	—

Dev volume is deliberately light to avoid interfering with integration tests that assert specific account balances.

Transaction mix

Per run, the engine generates a realistic mix across the seed customer population:

Type	Proportion	Description
Retail payment (outbound)	40%	Utilities, subscriptions, merchant payments
P2P transfer (intra-bank)	20%	Customer to customer within the platform
Inbound credit	25%	Simulated payroll (Friday runs), rental income, refunds
Savings transfer	10%	Everyday → savings account sweep
Fee debit	5%	Monthly account fee (triggered on first run of month)

Payroll credits are generated only on the Thursday or Friday schedule run nearest to the 15th and last day of the month.

Constraints

The engine enforces these rules before submitting any transaction:

• Balance check: debit amount must not exceed 90% of current balance (leaves buffer for fees and interest)
• Account state: only Active accounts receive transactions; Dormant, Restricted, and Pending accounts are skipped
• Daily limit: no account receives more than 3 synthetic transactions per calendar day
• Idempotency: a synthetic_run_id composed of date + account_id + sequence is embedded in the payment reference; MOD-001's idempotency key rejects duplicates if the engine runs twice in a day

Reproducibility

The random selections (amount, counterparty, transaction type) are seeded by SHA256(stage + ISO-date + customer_id), truncated to a uint32. This means the same customer generates the same transactions on the same day regardless of which Lambda invocation runs — useful for debugging mismatches between environments.

Activation gate

The engine's EventBridge schedule is created in DISABLED state. It is enabled via sst deploy only after all mandatory dependencies (MOD-001, MOD-003, MOD-007, MOD-020) are confirmed deployed in the target stage. The CI workflow for MOD-159 verifies these SSM output paths exist before enabling the schedule.

---

Module dependencies

Depends on

Module	Title	Required?	Contract	Reason
MOD-158	Test seed data loader	Required	—	Seed customers and accounts must be loaded before the engine can generate transactions against them.
MOD-001	Double-entry posting engine	Required	—	All synthetic transactions are submitted as EventBridge payment instruction events that route through the double-entry posting engine; MOD-001 must be deployed and accepting events.
MOD-003	Real-time balance engine	Required	—	The engine reads current balances from the balance engine before generating debit transactions to avoid overdrawing seed accounts.
MOD-007	Account state machine	Required	—	The engine checks account state before submitting transactions; accounts in non-Active states are skipped.
MOD-020	Pre-payment validation suite	Required	—	Synthetic payment instructions pass through the pre-payment validation suite; MOD-020 must be deployed in the target stage.
MOD-062	Workflow orchestration engine	Optional	—	Workflow orchestration is used for complex synthetic scenarios (e.g. term deposit maturity, notice period withdrawals) but simple payment generation works without it.

Required by

Module	Title	As	Contract
MOD-160	Cross-module acceptance suite	Optional enhancement	—

---

Policies satisfied

(No policies assigned)

---

Capabilities satisfied

(No capabilities mapped)

---

Part of SD07 — Data Platform & Governance Infrastructure Compiled 2026-05-22 from source/entities/modules/MOD-159.yaml