double-entry-ledger-architecture

Double-Entry Ledger Architecture Skill Guide

This skill governs the design, data structures, and mathematical invariants required to build production-grade double-entry financial ledgers.

---

1. Double-Entry Mathematical Invariants

In double-entry bookkeeping, every financial transaction consists of at least two balanced entries.

$$\sum \text{Debits} = \sum \text{Credits}$$

The fundamental accounting equation must hold true at every millisecond:

$$\text{Assets} = \text{Liabilities} + \text{Equity} + (\text{Revenue} - \text{Expenses})$$

[ Account Classifications & Normal Balances ]
+------------------+------------------+------------------+
| Account Type     | Debit (Dr)       | Credit (Cr)      |
+------------------+------------------+------------------+
| Assets           | Increases (+)    | Decreases (-)    |
| Liabilities      | Decreases (-)    | Increases (+)    |
| Equity           | Decreases (-)    | Increases (+)    |
| Revenue          | Decreases (-)    | Increases (+)    |
| Expense          | Increases (+)    | Decreases (-)    |
+------------------+------------------+------------------+

---

2. Production Database Schema (PostgreSQL)

-- 1. Chart of Accounts
CREATE TYPE account_classification AS ENUM ('ASSET', 'LIABILITY', 'EQUITY', 'REVENUE', 'EXPENSE');

CREATE TABLE accounts (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    account_code VARCHAR(32) NOT NULL UNIQUE, -- e.g. '1010-CASH-USD'
    name VARCHAR(128) NOT NULL,
    classification account_classification NOT NULL,
    currency VARCHAR(3) NOT NULL DEFAULT 'USD',
    is_active BOOLEAN NOT NULL DEFAULT TRUE,
    created_at TIMESTAMPTZ DEFAULT clock_timestamp()
);

-- 2. Journal Transactions (Header)
CREATE TABLE journal_transactions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    reference_id VARCHAR(128) NOT NULL UNIQUE, -- Idempotency key from payment/checkout
    description TEXT NOT NULL,
    posted_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp()
);

-- 3. Journal Entries (Lines: Debits & Credits)
CREATE TABLE journal_entries (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    transaction_id UUID NOT NULL REFERENCES journal_transactions(id) ON DELETE RESTRICT,
    account_id UUID NOT NULL REFERENCES accounts(id) ON DELETE RESTRICT,
    amount NUMERIC(18, 4) NOT NULL CHECK (amount > 0),
    is_debit BOOLEAN NOT NULL,
    entry_sequence INT NOT NULL,
    CONSTRAINT uq_txn_entry_seq UNIQUE (transaction_id, entry_sequence)
);

CREATE INDEX idx_journal_entries_account ON journal_entries(account_id);
CREATE INDEX idx_journal_entries_txn ON journal_entries(transaction_id);