Skip to main content
  1. System Design Components/

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