Archetype 7 — Critical Transaction Process #
What this archetype is #
A correctness-critical transaction moves value or money. The main concerns are atomic commit, idempotency, external side effects, and reconciliation.
Examples: payments, ledger transfers, wallet debit/credit.
We will use wallet transfer as the running example.
Layer 1: Entities and Postgres table design #
TransactionState
MovementState
create table transactions (
transaction_id uuid primary key,
idempotency_key uuid unique,
from_account bigint not null,
to_account bigint not null,
amount numeric(18,2) not null,
status text not null,
created_at timestamptz not null default now()
);
create table ledger_entries (
entry_id bigserial primary key,
transaction_id uuid not null references transactions(transaction_id),
account_id bigint not null,
direction text not null,
amount numeric(18,2) not null,
created_at timestamptz not null default now()
);
create table transaction_outbox (
outbox_id bigserial primary key,
transaction_id uuid not null,
effect_type text not null,
payload jsonb not null,
created_at timestamptz not null default now(),
delivered_at timestamptz
);
Layer 2: Write path mechanics #
Commit transfer atomically #
begin;
insert into transactions (
transaction_id, idempotency_key, from_account, to_account, amount, status
) values ($1, $2, $3, $4, $5, 'COMMITTED');
insert into ledger_entries (transaction_id, account_id, direction, amount)
values
($1, $3, 'DEBIT', $5),
($1, $4, 'CREDIT', $5);
insert into transaction_outbox (
transaction_id, effect_type, payload
) values (
$1, 'SEND_TRANSFER_WEBHOOK', $6
);
commit;
This is the Postgres equivalent of TransactWriteItems.
Layer 3: Fault tolerance #
- duplicate commit
- invalid transition
- crash after commit before side effect
- retry ambiguity against provider
- reconciliation drift
Controls:
- unique idempotency key
- one DB transaction for internal truth
- outbox for external effects
- reconciliation against provider reports or webhooks
Layer 4: Scale #
Default hotspots:
- synchronous commit-path latency
- provider bottleneck
- retry amplification
- idempotency-store hotspot
Common mitigations:
- keep commit path narrow
- batch external side-effect delivery asynchronously
- shard by account or tenant if needed