# Core Concepts

Double-entry accounting, tenants, accounts, journal entries, and holds.

URL: https://docs.shiwake.app/docs/getting-started/concepts



This page covers the Shiwake-specific model: tenants, accounts,
entries, balances, and holds as they exist in the engine. If the words
"debit" and "credit" don't feel natural yet, read the
[Accounting Primer](/docs/getting-started/accounting-primer) first: everything below assumes you know what a balanced journal entry is.

Journal entries are immutable [#journal-entries-are-immutable]

Once a journal entry is posted, it never changes. If you need to undo it,
you post a **reversal**: a new journal entry with the debits and credits
swapped, pointing back at the original via `reversalOf`. Both entries live
forever in the ledger. This is not a limitation; it is the point. A ledger
that can be retroactively edited is not an audit trail.

Tenants and isolation [#tenants-and-isolation]

A **tenant** is a complete, isolated set of books. Every account, journal
entry, and hold belongs to exactly one tenant, and tenant-scoped requests
can never see another tenant's data. The filter is enforced at the
database layer by EF Core global query filters, not by application code.

In practice this means:

* One Shiwake deployment can serve many independent products.
* One tenant's rate limit exhaustion cannot affect another.
* Account codes only need to be unique *within* a tenant. Two tenants can
  both have a `CLIENT-42`.
* API keys map one-to-one to tenants. See [Authentication](/docs/api/authentication).

Accounts [#accounts]

An account is a named bucket that holds a balance in a single currency.
Every account has:

* A **code**: stable, human-readable, unique per tenant (e.g. `CLIENT-42`,
  `PLATFORM-FLOAT`). This is what you reference from journal entry lines.
* An **id**: ULID, what the API returns for cross-references.
* A **type**: Asset, Liability, Equity, Revenue, or Expense.
* A **currency**: ISO 4217 code. Fixed at creation.
* A **parent**: optional, for hierarchical reporting.

See [Accounts](/docs/api/accounts) for the full field reference.

Two balances, not one [#two-balances-not-one]

Every account actually has two balances:

* **Ledger balance**: the sum of posted debits and credits. This is the
  "real" accounting balance.
* **Available balance**: `ledger balance − active holds`. This is what the
  engine checks when you try to debit the account.

If a wallet has GHS 500 and you've placed a GHS 200 hold on it, the
ledger balance is still 500 but the available balance is 300. A new debit
of 400 will be rejected with `422 Insufficient balance` even though the
ledger "has the money". The 200 is reserved.

Holds [#holds]

A **hold** reserves an amount on an account's available balance without
moving money. It's the right primitive for authorization flows where you
need to guarantee funds now but settle later (or settle at a different
amount).

Holds have a lifecycle: `Active` → `Captured` (settled by posting a
journal entry) or `Released` (abandoned) or `Expired` (timed out).

See [Holds](/docs/api/holds) for the full API.

What happens when you post an entry [#what-happens-when-you-post-an-entry]

When `POST /ledger/journal-entries` is called, the engine:

1. Verifies the `Idempotency-Key` header is present and not a replay.
2. Loads the referenced accounts, failing with `404` on any unknown code.
3. Checks that debits equal credits *per currency*.
4. Checks that debiting would not drive any account below its available
   balance, failing with `422` and an `InsufficientBalanceDetail` payload.
5. Inserts the entry, the lines, and updates cached balances: all in one
   transaction.

Either everything happens or nothing does. There is no half-posted entry.

Where to go next [#where-to-go-next]

<Cards>
  <Card title="Quickstart" href="/docs/getting-started/quickstart">
    Walk through provisioning a tenant and posting your first entry.
  </Card>

  <Card title="API reference" href="/docs/api">
    Full endpoint documentation for the raw engine.
  </Card>
</Cards>
