Why 90% of Account Designs Fail: Decoupling Business Logic from Ledger Systems

01 A Confusing Design Logic

When designing accounts, the flow of business states and the handling of finances often cause confusion. A single transaction requires an entry in the "in‑transaction" state and another when it becomes successful, making it easy to mistake the process.

Once this pitfall is entered, it’s hard to escape.

A common scenario is mixing transaction states into the account ledger, tightly coupling business status with account records, which makes the logic difficult to untangle.

02 Where Did We Fall?

When a transaction moves from "in‑transaction" to "successful", the frozen balance must be unfrozen to the available balance, and the ledger entry status changes accordingly. The available and frozen balances of the related ledger line also need to be updated, which can become a massive workload if millions of records exist.

03 Basic Recognitions

Facts are immutable: accounting records immutable business facts, just like a ledger entry that becomes a final state once recorded.

Non one‑to‑one strong correspondence: business documents and account entries may be one‑to‑many, many‑to‑one, or many‑to‑many, so a transaction should not be equated directly with a single ledger line.

Understand accounting events: each change of transaction state constitutes an accounting event; the account should record a new entry for each event rather than modifying existing entries.

04 Solution

Remove transaction state from the account to keep the account "pure". The account no longer tracks business state flow but only processes each accounting request as a final, immutable entry.

We abstract accounting types such as "freeze" and "unfreeze". A transaction’s state change maps to multiple ledger entries.

During the transaction, record a type‑02 "income" entry that adds the amount to the frozen balance.

After success, record a type‑04 "unfreeze" entry; total balance stays the same, frozen balance decreases, and available balance increases.

If the transaction fails, the type‑04 entry becomes an expense that reduces the frozen balance.

05 Anti‑Coupling Design Principle

Isolate business logic from the account system; the account system does not care about business state transitions but only handles each accounting request. Business modules trigger accounting requests at relevant events, while the account system provides various accounting services.