ShiwakeDocs

Accounting Primer

Double-entry accounting for developers who have never touched a ledger before.

If you've never worked on a financial system, the vocabulary is the hard part. "Debit" and "credit" don't mean what they mean at an ATM. "Liability" sounds bad but describes a customer's wallet balance. This page fixes that before you touch any code.

You do not need an accounting degree to use Shiwake. You need about fifteen minutes and the five or six ideas below.

The payoff for learning this: you can never quietly lose track of money. Every movement is recorded twice, and the two halves are forced to agree. When they don't, the system refuses the write instead of silently drifting. That guarantee is the whole reason double-entry has outlived every accounting fad for 500 years.

The mental model

A ledger is a list of facts about money that has already moved. It is not a bank account, not a balance, not a wallet. It is a log. Balances are computed from the log, not stored as the source of truth.

Every fact in the log must explain both sides of a money movement: where it came from and where it went. That's the whole idea behind double-entry. You cannot record "money appeared" without also recording "money disappeared from somewhere else."

If money always moves from somewhere to somewhere, the total amount "from" and the total amount "to" must be equal. That is the only rule of double-entry. Everything else is terminology for that rule.

The ledger is an append-only log; balances are computed from it

The core terms

Account

An account is just a label you stick on money so you can ask "how much is here?" and get one number back. Nothing more.

The trick is: you make a separate account for every question you want to answer separately.

  • "How much cash does the company hold right now?" → make an account for that. Call it PLATFORM-FLOAT.
  • "How much do we owe Alice?" → make an account for that: CLIENT-42.
  • "How much do we owe Bob?" → that's a different question, so it's a different account: CLIENT-99.
  • "How much have we earned in fees this whole time?" → another account: FEE-REVENUE.

That's why a real product has thousands of accounts: one for the company's cash, one per customer wallet, one for fees, one for taxes owed, and so on. Each one just answers its own "how much?" question.

The word "account" is unfortunate: forget your bank account. A better mental image is a labeled jar. Money movements drop coins into jars or take them out, and the account is simply the running count in one jar. You never store that count; you get it by counting the jar (summing the log) whenever someone asks.

An account is a labeled jar: one per question you want to answer, and its balance is just the running count

In Shiwake, every account has just four things:

  • a code: the unique handle you refer to it by, like CLIENT-42
  • a name: a human label, like "Alice's wallet"
  • a type: one of the five kinds below (Asset, Liability, …), which decides whether debits grow it or shrink it
  • a currency: an account only ever holds one currency

Journal entry

A journal entry is one complete story of a single money movement. "Alice deposited 500" is one journal entry. "We paid out a refund of 200" is another. Each entry is one row in the log, and it never gets edited or deleted once written.

But a story needs at least two characters, where the money came from and where it went to. So an entry isn't just one number; it's a small container holding:

  • a description ("Alice deposit") and a timestamp, and
  • two or more lines: the actual pieces that say which jars moved.

Think of the entry as an envelope and the lines as the slips of paper inside it. The envelope is the event; the slips are the details. You always post the whole envelope at once, never a lone slip.

Entry line

A line is one slip inside the envelope. It says exactly three things:

  1. which account moved (CLIENT-42),
  2. how much (50000), and
  3. which side: a debit or a credit.

That's it. One line touches exactly one account. A minimum entry has two lines (one debit, one credit: the "from" and the "to"). Bigger entries can have more: splitting a payment into principal + fee + tax might have four or five lines. The only unbreakable rule is that, added up, the debit lines and the credit lines must total the same amount. That's what "the envelope balances" means.

A journal entry is an envelope; its lines are the slips inside, each naming one account, one amount, and one side

Debit and credit

Here is the sentence to tattoo on your brain:

Debit and credit are just "left side" and "right side" of the ledger. They are not "money in" and "money out."

Whether a debit means "the account grew" or "the account shrank" depends on the type of account. That's what "normal balance" means below.

Forget everything your bank statement taught you. In a bank statement, a "debit" takes money from you, because the statement is written from your perspective, but to the bank, that same transaction is a credit (their liability to you went down). Double-entry keeps one side in one column and the other side in the other, consistently, across the entire ledger.

Debit is the left side and credit is the right side of the ledger, not money out and money in

Account types and normal balances

There are five kinds of accounts. Each one has a side it "grows on" (called its normal balance):

TypeGrows onShrinks onExample
AssetDebitCreditThe cash the company holds
LiabilityCreditDebitMoney the company owes customers
EquityCreditDebitThe owners' stake
RevenueCreditDebitFees and interest the company earns
ExpenseDebitCreditCosts the company incurs

One way to remember it: assets and expenses grow on the debit side; everything else grows on the credit side.

Cheat sheet: screenshot this.

  • DEbit-normal (grow on debit): Assets, Expenses
  • Credit-normal (grow on credit): Liabilities, Equity, Revenue
  • Same-side entry → the account grows. Opposite side → it shrinks.
  • Every entry: total debits = total credits. No exceptions.

The five account types and the side each one grows on

Another way: debits and credits are just labels. What matters is that the rule "debits = credits" holds for every entry.

Working an example, very slowly

We'll follow one customer, Alice, through three events in a row (a deposit, a withdrawal, and a fee) and watch her wallet balance move after each one. That running balance is the whole point of the page: nobody stores it, it just falls out of summing the entries.

Event 1: Alice deposits GHS 500 into her wallet. There are two accounts involved:

  • PLATFORM-FLOAT: the company's cash pile. This is an Asset.
  • CLIENT-42: the customer's wallet. This is a Liability (the company owes them 500 now).

Why is a customer's wallet a "liability"? Because the ledger is written from the company's perspective, not the customer's. Money sitting in Alice's wallet is money the company owes back to Alice. A debt it must be able to pay out on demand. Her asset is the company's liability. Get this one reframe and the entire normal-balance table suddenly makes sense.

Here is the journal entry:

AccountTypeDebitCredit
PLATFORM-FLOATAsset50000
CLIENT-42Liability50000
5000050000

Let's read it out loud:

  • PLATFORM-FLOAT is debited 50000. It's an asset, and assets grow on debits. So the company's cash pile grew by 500.
  • CLIENT-42 is credited 50000. It's a liability, and liabilities grow on credits. So what the company owes the customer grew by 500.
  • Debits equal credits (50000 = 50000). The entry balances. It can be posted.

Both sides make sense. Cash came in; a debt to the customer came into existence. The books are still in balance because both sides grew by the same amount.

Alice's wallet balance after Event 1: 50000 (one credit of 50000, no debits yet).

Deposit: PLATFORM-FLOAT debited and CLIENT-42 credited, both by 50000

The number 50000 here is not "fifty thousand cedis." It's GHS 500.00 in pesewas: minor units. Everything in Shiwake is minor units, always. GHS 1.00 is 100, USD 1.00 is 100, JPY 1 is 1.

Event 2: Alice withdraws

Event 2: Alice withdraws GHS 200. Same two accounts as before, but now both sides shrink:

AccountTypeDebitCredit
CLIENT-42Liability20000
PLATFORM-FLOATAsset20000
2000020000
  • CLIENT-42 is debited 20000. Liabilities shrink on debits. The company owes the customer 200 less now.
  • PLATFORM-FLOAT is credited 20000. Assets shrink on credits. The company's cash pile is 200 smaller.

Alice's wallet balance after Event 2: 30000 (credits 50000 − debits 20000). Nobody wrote "30000" anywhere. It's just the credits minus the debits so far.

Notice how the debit/credit labels flipped sides compared to the deposit. That's the whole point. The same pair of accounts can move in either direction depending on which side you put them on.

The same two accounts, with debit and credit flipped between deposit and withdrawal

Event 3: Alice pays a fee

Event 3: Alice pays a GHS 5 fee out of her wallet. A new account appears. The fee doesn't go back to the float, it becomes the company's revenue:

AccountTypeDebitCredit
CLIENT-42Liability500
FEE-REVENUERevenue500
500500
  • CLIENT-42 is debited: the customer's wallet shrinks.
  • FEE-REVENUE is credited: the company's revenue grows.

Still balanced. This is a single journal entry with two lines, just like the others. The only thing that changed is which accounts are involved.

Alice's wallet balance after Event 3: 29500 (credits 50000 − debits 20500).

Here's the whole story in one view: three entries, one running balance, never stored anywhere:

After eventEntryCLIENT-42 running balance
Start0
1. Deposit GHS 500credit 5000050000
2. Withdraw GHS 200debit 2000030000
3. Fee GHS 5debit 50029500

Sum the credits (50000), subtract the debits (20000 + 500), and you get 29500 every time, no matter what order you replay the log in.

Why "debits = credits" is load-bearing

Because every fact in the log balances, the sum of all debits across the whole ledger always equals the sum of all credits. If those two numbers ever disagree, something is broken at a very deep level. The trial balance endpoint computes exactly those two numbers and tells you whether they match.

This is also why Shiwake rejects unbalanced entries at post time. The engine literally cannot let you write a broken fact into the log, because one broken fact would permanently poison the ledger.

Trial balance: the engine rejects any entry where total debits do not equal total credits

Running balances are derived

Notice that nothing in Alice's three events said "store the wallet balance somewhere." The balance is whatever falls out of summing the log. CLIENT-42 has a balance of 29500 because its credits sum to 50000 and its debits sum to 20500. If you ever doubt the balance, you can recompute it from scratch from the entry lines. That's what verify-balances does.

Shiwake does cache balances for performance (reading a wallet shouldn't have to sum millions of rows), but the cache is subordinate to the log. The log is the truth.

Reversing, not deleting

Suppose the deposit was wrong: the customer actually sent GHS 500 to the wrong account and you need to undo it. You do not delete the journal entry. You post a reversal. A new entry with the debits and credits swapped, pointing back at the original:

AccountDebitCredit
CLIENT-4250000
PLATFORM-FLOAT50000

The original entry still exists. The reversal also exists. Both are in the log forever. The net effect on balances is zero, but the history of what actually happened. "we posted a deposit, then we undid it": is preserved. An audit trail that can be edited is not an audit trail.

A reversal appends a mirrored entry pointing back at the original; nothing is ever deleted

One more idea: holds

Sometimes you need to reserve money without moving it yet, like an authorization on a card before the final charge lands. That's a hold: it lowers the available balance so the money can't be spent twice, but it posts no journal entry and doesn't touch the actual balance. When the real transaction settles, you release the hold and post a normal entry.

The takeaway for now: a hold is a promise, not a movement. Only journal entries move money. Holds get their own page later. This is just so the word isn't a surprise in the glossary below.

Glossary

TermMeaning
LedgerThe log of all journal entries. The source of truth
AccountA named bucket whose balance is computed from the log
Journal entryA single atomic fact in the log, with ≥2 lines
LineOne side of one entry: an account, an amount, and a debit/credit flag
Debit / creditLeft side / right side of the ledger. Not "in" and "out"
Normal balanceThe side (debit or credit) an account type grows on
AssetSomething the company owns (cash, receivables). Grows on debit
LiabilitySomething the company owes (wallets, deposits). Grows on credit
EquityOwnership stake. Grows on credit
RevenueIncome earned (fees, interest). Grows on credit
ExpenseCosts incurred. Grows on debit
Trial balanceSum of all debits vs sum of all credits. Must be equal
ReversalA new entry that cancels an earlier one. Never a delete
HoldA reservation against available balance without moving money
Minor unitsThe smallest unit of a currency. 1 cedi = 100 pesewas

Where to go next

Edit on GitHub

Last updated on

On this page