Ledger System Design

Part 1: Financial Foundations

10-15 minutes

Before diving into distributed systems complexities, you need to speak the language of finance. Interviewers at Stripe expect you to understand why accounting systems work the way they do, not just how to build them.

Why Double-Entry Accounting Exists

Double-entry bookkeeping was formalized in 1494 by Luca Pacioli, but its brilliance is timeless: every transaction affects at least two accounts, and the sum of all debits must equal the sum of all credits. This isn't bureaucratic overhead—it's an error-detection mechanism built into the data model itself.

Consider what happens without double-entry: if you simply track account balances, a bug that adds $100 to one account without removing it from another is invisible until external reconciliation catches it—potentially months later.

Debits vs Credits: The Mental Model

The debit/credit system confuses many engineers because the words seem backwards. Here's the model that actually makes sense:

Practical example at Stripe: When a customer pays $100 for a merchant's product:

Journal → Ledger → Trial Balance

Financial systems process transactions through a specific flow:

Balance Computation: Stored vs Computed

This is your first major architectural decision. How do you answer "What's the balance of account X?"

SELECT balance
FROM accounts
WHERE id = 'acct_123';

SELECT SUM(CASE
    WHEN type='debit' THEN amount
    ELSE -amount END)
FROM entries
WHERE account_id = 'acct_123';

Why Immutability is Non-Negotiable

In financial systems, you never delete or modify records. This isn't just good practice—it's often legally required.

• Audit trail: Regulators and auditors must be able to reconstruct any historical state
• Error correction: Mistakes are fixed by adding reversing entries, not by changing history
• Dispute resolution: When a customer disputes a charge, you need the original record
• Forensics: If fraud occurs, you need an unbroken chain of events

INSERT INTO entries (account_id, amount, type, reverses_entry_id)
VALUES ('acct_revenue', 100, 'debit', 1001);

Part 2: Core Data Model Design

10-15 minutes

With financial concepts understood, let's design the schema. The data model you propose in an interview reveals whether you truly understand the domain.

Account Hierarchies and Chart of Accounts

A Chart of Accounts (COA) is the complete listing of all accounts in a ledger, organized hierarchically. At Stripe-scale, this hierarchy serves multiple purposes:

• Aggregation: Roll up balances from child accounts to parents
• Access control: Permissions at different hierarchy levels
• Reporting: Different views for different stakeholders

Transaction vs Entry: A Critical Distinction

This distinction trips up many engineers. In accounting:

• Transaction: A business event (e.g., "Customer paid merchant $100")
• Entry: A single debit or credit line within a transaction

A transaction always contains two or more entries. The entries must balance (sum to zero).

Schema Design with PostgreSQL

-- Core tables for a production ledger

CREATE TABLE accounts (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    parent_id       UUID REFERENCES accounts(id),
    code            VARCHAR(50) UNIQUE NOT NULL,  -- e.g., 'assets.cash.stripe_balance'
    name            VARCHAR(255) NOT NULL,
    type            VARCHAR(20) NOT NULL CHECK (type IN ('asset', 'liability', 'equity', 'revenue', 'expense')),
    currency        CHAR(3) NOT NULL DEFAULT 'USD',
    normal_balance  VARCHAR(6) NOT NULL CHECK (normal_balance IN ('debit', 'credit')),
    is_leaf         BOOLEAN NOT NULL DEFAULT true,  -- Only leaf accounts can hold entries
    metadata        JSONB DEFAULT '{}',
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),

    CONSTRAINT leaf_or_parent CHECK (is_leaf OR parent_id IS NOT NULL)
);

CREATE TABLE transactions (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    idempotency_key VARCHAR(255) UNIQUE,  -- Prevents duplicate processing
    description     TEXT,
    metadata        JSONB DEFAULT '{}',

    -- Temporal fields (see explanation below)
    event_time      TIMESTAMPTZ NOT NULL,      -- When the business event occurred
    processed_at    TIMESTAMPTZ NOT NULL DEFAULT now(),  -- When we recorded it
    effective_date  DATE NOT NULL,             -- When it affects balances

    created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE entries (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    transaction_id  UUID NOT NULL REFERENCES transactions(id),
    account_id      UUID NOT NULL REFERENCES accounts(id),
    entry_type      VARCHAR(6) NOT NULL CHECK (entry_type IN ('debit', 'credit')),
    amount          BIGINT NOT NULL CHECK (amount > 0),  -- Always positive, in smallest unit
    currency        CHAR(3) NOT NULL,

    created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- Ensure transactions balance
CREATE OR REPLACE FUNCTION check_transaction_balance()
RETURNS TRIGGER AS $$
BEGIN
    IF (
        SELECT SUM(CASE WHEN entry_type = 'debit' THEN amount ELSE -amount END)
        FROM entries
        WHERE transaction_id = NEW.transaction_id
    ) != 0 THEN
        RAISE EXCEPTION 'Transaction % does not balance', NEW.transaction_id;
    END IF;
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

-- Indexes for common queries
CREATE INDEX idx_entries_account_id ON entries(account_id);
CREATE INDEX idx_entries_transaction_id ON entries(transaction_id);
CREATE INDEX idx_transactions_effective_date ON transactions(effective_date);
CREATE INDEX idx_transactions_idempotency ON transactions(idempotency_key) WHERE idempotency_key IS NOT NULL;

Multi-Currency Considerations

Two approaches exist for handling multiple currencies:

Option 1: Currency per Account

Each account holds one currency. Cross-currency transfers require conversion entries.

Option 2: Multi-denomination Accounts

Single account holds multiple currency balances. Simpler for some use cases, but complicates aggregation.

-- Alternative: store currency with each entry, allow mixed currencies per account
SELECT currency, SUM(CASE WHEN entry_type = 'debit' THEN amount ELSE -amount END) as balance
FROM entries
WHERE account_id = 'acct_123'
GROUP BY currency;

The Three Timestamps

Financial systems need three distinct temporal concepts. Getting this wrong causes subtle, hard-to-debug issues.

*Effective date may be set at creation and adjusted for settlements, but the adjustment itself is recorded.

Part 3: Consistency & Correctness

15-20 minutes

This is where financial systems get hard. Anyone can build a ledger that works when everything goes right. The challenge is ensuring correctness when things go wrong—and in distributed systems, things always go wrong.

The "Balance Can Never Go Negative" Constraint

For many account types (e.g., a user's spending account), you must guarantee the balance never drops below zero. This seemingly simple constraint has profound architectural implications.

Approach 1: Pessimistic Locking

Lock the account before reading, hold lock through write.

BEGIN;

-- Acquire exclusive lock on the account row
SELECT * FROM accounts
WHERE id = 'acct_123'
FOR UPDATE;

-- Compute current balance (or read cached balance)
SELECT COALESCE(SUM(
    CASE WHEN entry_type = 'debit' THEN amount ELSE -amount END
), 0) AS balance
FROM entries
WHERE account_id = 'acct_123';

-- If balance >= requested amount, insert entries
INSERT INTO entries (...) VALUES (...);

COMMIT;

Approach 2: Optimistic Locking with Version Check

Read balance, attempt write with version check, retry on conflict.

-- Add version column to accounts table
ALTER TABLE accounts ADD COLUMN version BIGINT DEFAULT 0;
ALTER TABLE accounts ADD COLUMN cached_balance BIGINT DEFAULT 0;

-- Optimistic update pattern
UPDATE accounts
SET
    cached_balance = cached_balance - 8000,  -- $80.00 in cents
    version = version + 1
WHERE id = 'acct_123'
    AND version = 42  -- Expected version from read
    AND cached_balance >= 8000;  -- Balance check

-- Check rows affected: 0 = conflict, retry; 1 = success

Idempotency Keys: Design and Implementation

Network failures mean clients may retry requests. Without idempotency, retries can cause duplicate transactions. This is critical for financial systems.

CREATE TABLE idempotency_keys (
    key             VARCHAR(255) PRIMARY KEY,
    request_hash    BYTEA NOT NULL,      -- Hash of request parameters
    response        JSONB,                 -- Cached response
    transaction_id  UUID REFERENCES transactions(id),
    status          VARCHAR(20) NOT NULL DEFAULT 'processing',
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    expires_at      TIMESTAMPTZ NOT NULL   -- Typically 24-72 hours
);

CREATE INDEX idx_idempotency_expires ON idempotency_keys(expires_at);

The Idempotency Flow

Distributed Transactions: Patterns for Multi-Account Operations

What happens when a transaction touches accounts on different database shards? Or when you need to coordinate with external systems?

Pattern 1: Two-Phase Commit (2PC)

Pattern 2: Saga with Compensating Transactions

For long-running or cross-service transactions, Sagas break the operation into steps, each with a compensating action.

Pattern 3: Transactional Outbox

The outbox pattern ensures reliable event publishing alongside database changes.

-- Within the same database transaction:
BEGIN;

-- 1. Write to ledger
INSERT INTO entries (...) VALUES (...);

-- 2. Write event to outbox table
INSERT INTO outbox (event_type, payload, created_at)
VALUES ('TransactionCompleted', '{"txn_id": "..."}', now());

COMMIT;

-- Separate process polls outbox and publishes to message queue
-- Deletes from outbox after confirmed delivery

Handling Partial Failures Gracefully

In distributed systems, you must handle scenarios where some operations succeed and others fail.

Part 4: Scale & Performance

20-25 minutes

Critical Section

This is the section interviewers care most about. The hardest question in ledger design: How do you scale writes while maintaining strong consistency guarantees?

4a: Single-Primary Optimization

The Hot Account Problem

Not all accounts are equal. A merchant settlement account at Stripe might see thousands of transactions per second, while most user accounts see one per day. This creates hot spots.

Vertical Scaling Limits

Before distributing, exhaust single-node optimizations:

• Connection pooling: PgBouncer or similar to multiplex connections
• Prepared statements: Reduce parse overhead
• Batch inserts: Group entries into single INSERT statements
• SSD/NVMe storage: Faster IOPS for transaction log
• Increased RAM: Keep working set in memory

Practical PostgreSQL limits on modern hardware (2024):

• ~50,000 simple transactions/second on high-end hardware
• Write-heavy workloads often hit ~10,000-20,000 TPS
• Lock contention on hot rows is usually the bottleneck before raw throughput

Read Replicas and Consistency Windows

-- Route balance checks to replica (eventual consistency OK for display)
-- postgresql.conf on replica: hot_standby_feedback = on

-- Application routing logic:
if query.is_read_only and not query.requires_strong_consistency:
    connection = replica_pool.get_connection()
else:
    connection = primary_pool.get_connection()

4b: Beyond Single Primary - Distributed Consistency

This is what Stripe interviews probe deeply

When a single PostgreSQL primary can't handle your write volume, you have three main options:

Option 1: Application-Level Sharding

Partition accounts across multiple database instances. Each shard is a fully independent PostgreSQL cluster.

Cross-shard transaction strategies:

1. Saga with compensating transactions: Accept eventual consistency between shards
2. Two-phase commit: Coordinate across shards (latency cost)
3. Avoid cross-shard transactions: Design shard keys to keep related accounts together

-- Shard key design: Use merchant_id as shard key
-- All accounts for a merchant live on same shard

def get_shard(account_id):
    merchant_id = account_to_merchant[account_id]
    return hash(merchant_id) % NUM_SHARDS

-- Payment: customer → merchant (same merchant = same shard = local txn)
-- Settlement: merchant → Stripe bank (cross-shard, can be async)

Option 2: Distributed SQL (Spanner, CockroachDB, TiDB)

These databases provide the abstraction of a single logical database while distributing data across nodes.

Option 3: Partition by Account with Careful Boundary Design

The key insight: most transactions don't need to be atomic across accounts. Design your system so that cross-partition transactions are rare or can be eventually consistent.

-- Account "ownership" model
-- Each transaction type has a natural owner

-- Payment: owned by merchant (merchant's shard handles atomically)
INSERT INTO entries VALUES
    ('customer_funds_held', -100),  -- Stripe's liability to customer
    ('merchant_receivable', +97),   -- What we owe merchant
    ('stripe_revenue', +3);         -- Our fee

-- The customer's balance update happens on customer's shard
-- via async message, with idempotency guarantee

The Stripe Approach (Public Knowledge)

Based on Stripe's published engineering content:

• Primary architecture: PostgreSQL with application-level sharding
• Sharding strategy: By merchant (keeps most transactions local)
• Cross-shard transactions: Saga pattern with careful idempotency
• Hot accounts: Special handling for platform accounts (batching, dedicated capacity)
• Consistency: Strong consistency within shard, eventual across shards with reconciliation

4c: Caching and Async Processing

Balance Caching: When It's Safe

-- Materialized balance with staleness tracking
CREATE TABLE balance_cache (
    account_id      UUID PRIMARY KEY,
    balance         BIGINT NOT NULL,
    last_entry_id   UUID NOT NULL,  -- Last entry included in balance
    computed_at     TIMESTAMPTZ NOT NULL,

    -- Verify cache freshness
    CONSTRAINT balance_not_stale CHECK (
        computed_at > now() - INTERVAL '5 minutes'
    )
);

-- Async worker keeps cache updated
-- On cache miss or staleness, compute from entries

What Can Be Eventual vs Synchronous

Part 5: Auditability & Compliance

10-15 minutes

Financial systems face regulatory scrutiny that most software doesn't. Understanding these requirements shows interview maturity.

Immutable Audit Trails

Every change must be traceable. The append-only design of ledgers naturally supports this, but you need additional metadata.

CREATE TABLE audit_log (
    id              BIGSERIAL PRIMARY KEY,
    event_type      VARCHAR(50) NOT NULL,
    entity_type     VARCHAR(50) NOT NULL,
    entity_id       UUID NOT NULL,

    -- Who/what made the change
    actor_type      VARCHAR(20) NOT NULL,  -- 'user', 'system', 'api_key'
    actor_id        VARCHAR(255) NOT NULL,

    -- What changed
    old_value       JSONB,
    new_value       JSONB,

    -- Context
    ip_address      INET,
    user_agent      TEXT,
    request_id      UUID,

    created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- Write-once: no updates or deletes allowed
CREATE RULE audit_log_no_update AS ON UPDATE TO audit_log DO INSTEAD NOTHING;
CREATE RULE audit_log_no_delete AS ON DELETE TO audit_log DO INSTEAD NOTHING;

Reconciliation Systems

Reconciliation verifies that your internal records match reality. There are two types:

Internal Reconciliation

Verify internal consistency: Do cached balances match computed balances? Do all transactions balance?

-- Daily internal reconciliation job

-- 1. Verify all transactions balance (debits = credits)
SELECT t.id,
       SUM(CASE WHEN e.entry_type = 'debit' THEN e.amount ELSE 0 END) as total_debits,
       SUM(CASE WHEN e.entry_type = 'credit' THEN e.amount ELSE 0 END) as total_credits
FROM transactions t
JOIN entries e ON e.transaction_id = t.id
GROUP BY t.id
HAVING SUM(CASE WHEN e.entry_type = 'debit' THEN e.amount ELSE -e.amount END) != 0;
-- Should return 0 rows

-- 2. Verify cached balances match computed
SELECT bc.account_id,
       bc.balance as cached,
       SUM(CASE WHEN e.entry_type = 'debit' THEN e.amount ELSE -e.amount END) as computed
FROM balance_cache bc
JOIN entries e ON e.account_id = bc.account_id
GROUP BY bc.account_id, bc.balance
HAVING bc.balance != SUM(CASE WHEN e.entry_type = 'debit' THEN e.amount ELSE -e.amount END);

External Reconciliation

Match your records against external systems (banks, card networks, payment processors).

Point-in-Time Balance Queries

Regulators and auditors need to know account balances at any historical point. This is called "time travel" querying.

-- Balance as of a specific date/time
CREATE FUNCTION balance_at(
    p_account_id UUID,
    p_as_of TIMESTAMPTZ
) RETURNS BIGINT AS $$
    SELECT COALESCE(SUM(
        CASE WHEN e.entry_type = 'debit' THEN e.amount ELSE -e.amount END
    ), 0)
    FROM entries e
    JOIN transactions t ON t.id = e.transaction_id
    WHERE e.account_id = p_account_id
      AND t.effective_date <= p_as_of::date;
$$ LANGUAGE SQL STABLE;

-- Usage: What was merchant_123's balance on Dec 31, 2023?
SELECT balance_at('merchant_123', '2023-12-31 23:59:59');

Regulatory Requirements Overview

Soft Deletes and Corrections

Nothing is ever truly deleted. "Deletions" are reversing entries.

-- "Voiding" an incorrect transaction
INSERT INTO transactions (idempotency_key, description, event_time, effective_date)
VALUES (
    'void_txn_12345',
    'Void: Original transaction 12345 entered in error',
    now(),
    CURRENT_DATE
);

-- Insert reversing entries (opposite direction of original)
INSERT INTO entries (transaction_id, account_id, entry_type, amount, currency)
SELECT
    'new_void_txn_id',
    account_id,
    CASE WHEN entry_type = 'debit' THEN 'credit' ELSE 'debit' END,
    amount,
    currency
FROM entries
WHERE transaction_id = 'original_txn_12345';

Part 6: Advanced Architectural Patterns

10-15 minutes

These patterns come up in senior interviews. Know when to use them and when they're overkill.

Event Sourcing for Ledgers

Event sourcing stores state as a sequence of events rather than current values. Ledgers are naturally event-sourced—the journal IS the event log.

CQRS: Separating Read and Write Models

Command Query Responsibility Segregation uses different models for writes (commands) and reads (queries).

Multi-Region Deployments

For global availability and latency, you may need ledgers in multiple regions. This introduces consistency challenges.

Strategies:

1. Single primary, global replicas: Writes go to one region, reads can be local. Simplest, but write latency for distant users.
2. Active-passive failover: Secondary region takes over on primary failure. Potential data loss during failover.
3. Active-active with partitioning: Each region owns certain accounts. Cross-region transactions need coordination.
4. Distributed SQL (Spanner): Automatic multi-region with strong consistency. Highest latency, simplest programming model.

Testing Strategies for Financial Correctness

-- Property-based testing: Every transaction must balance
def test_transactions_always_balance(transaction):
    entries = create_transaction(transaction)
    debits = sum(e.amount for e in entries if e.type == 'debit')
    credits = sum(e.amount for e in entries if e.type == 'credit')
    assert debits == credits, f"Unbalanced: {debits} != {credits}"

-- Invariant checking: Balance never negative (for certain accounts)
def test_balance_never_negative():
    for account in get_non_credit_accounts():
        balance = compute_balance(account)
        assert balance >= 0, f"{account} has negative balance: {balance}"

-- Reconciliation test: Cached = Computed
def test_cache_consistency():
    for account in sample_accounts(1000):
        cached = get_cached_balance(account)
        computed = compute_balance_from_entries(account)
        assert cached == computed, f"Cache drift: {cached} vs {computed}"

Testing Categories

• Unit tests: Individual functions (balance calculation, entry validation)
• Integration tests: Full transaction flow through database
• Property tests: Invariants hold for all generated inputs
• Chaos tests: Correct behavior under failures (network partitions, crashes)
• Reconciliation tests: Internal consistency checks as tests
• Load tests: Verify concurrency control under contention

Part 7: Interview Execution Strategy

10 minutes

Knowing the material isn't enough. You need to present it effectively under interview pressure.

Structuring Your 45-60 Minute Answer

The "Stripe Framework"

A mental model for structuring financial system design:

1. Requirements: What operations? What scale? What consistency guarantees?
2. Data Model: Accounts, transactions, entries. Schema design.
3. Correctness: How do you ensure money is never created/destroyed? Concurrency control?
4. Scale: What's the bottleneck? How do you scale past it?
5. Operations: How do you detect problems? Recover from failures?

What L6 Interviewers Look For (vs L5)

Red Flags and Common Mistakes

Sample Interview Dialogue

Appendices

Appendix A: Glossary of Financial Terms

Appendix B: Quick Reference Schema

-- Minimal production ledger schema

CREATE TABLE accounts (
    id              UUID PRIMARY KEY,
    code            VARCHAR(50) UNIQUE NOT NULL,
    type            VARCHAR(20) NOT NULL,  -- asset/liability/equity/revenue/expense
    currency        CHAR(3) NOT NULL,
    normal_balance  VARCHAR(6) NOT NULL   -- debit/credit
);

CREATE TABLE transactions (
    id              UUID PRIMARY KEY,
    idempotency_key VARCHAR(255) UNIQUE,
    event_time      TIMESTAMPTZ NOT NULL,
    effective_date  DATE NOT NULL,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE entries (
    id              UUID PRIMARY KEY,
    transaction_id  UUID NOT NULL REFERENCES transactions(id),
    account_id      UUID NOT NULL REFERENCES accounts(id),
    entry_type      VARCHAR(6) NOT NULL,   -- debit/credit
    amount          BIGINT NOT NULL,        -- smallest currency unit
    currency        CHAR(3) NOT NULL
);

CREATE INDEX idx_entries_account ON entries(account_id);
CREATE INDEX idx_entries_txn ON entries(transaction_id);

Appendix C: Stripe-Specific Context

Based on publicly available information (engineering blog, conference talks):

• Scale: Processes hundreds of billions of dollars annually
• Database: PostgreSQL-based, heavily customized
• Sharding: Application-level, primarily by merchant
• Consistency: Strong within shard, eventual across with reconciliation
• Engineering culture: Move fast, but money must always be correct
• Key challenges: Hot accounts, multi-currency, global availability

Relevant Stripe engineering posts:

• "Designing robust and predictable APIs with idempotency"
• "Scaling your API with rate limiters"
• "How we built Stripe Radar"
• "Online migrations at scale"

Appendix D: Practice Questions

1. Basic: Design a schema for a simple double-entry ledger. Walk through a payment transaction.
2. Intermediate: How do you prevent overdrafts with concurrent transactions? Compare pessimistic vs optimistic approaches.
3. Advanced: A merchant's settlement account is receiving 50,000 transactions/second. How do you handle this hot spot?
4. Systems: Design idempotency handling for a payment API. What happens on network timeout?
5. Scale: Your ledger needs to support 1M TPS globally. Walk through your architecture.
6. Edge case: Two transactions are submitted simultaneously, each spending the full balance. How do you ensure only one succeeds?
7. Operations: How do you detect and recover from ledger inconsistencies?
8. Compliance: How do you design for GDPR's right-to-erasure while maintaining an immutable audit trail?