> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nyumbazetu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Glossary

> Precise definitions for the terms Nyumba Zetu uses across billing, collections and accounting.

Terms are defined the way the *system* uses them. Where a word is commonly used loosely (wallet,
prepaid, void), the precise meaning matters — it changes what the numbers mean.

## Property & tenancy

**Organisation** — your company on the platform. Owns branches, settings, branding and users.

**Branch** — an operating unit of the organisation (a region, an office, a scheme). The scope for
almost every list, KPI and report.

**Block** — a building or estate holding units.

**Unit** — the billable physical place. Carries unit type, size, occupancy type and, optionally,
an owner.

**Lease** — the contract between the organisation and a resident for a unit, with dates, rent,
charges and deposit. A lease is a separate record from the unit it occupies; a unit can have many
leases over time.

**Resident** — a person attached to a lease. Residents carry a role per unit: tenant, owner, next
of kin, or other contact.

**Occupancy** — whether a unit currently has an active lease. Derived from lease status, never
typed in.

**Portfolio** — a grouping of units or blocks used for reporting and assignment, cutting across
blocks.

## Billing

**Service type** — the catalogue entry for a billable thing (rent, water, service charge, deposit,
late fee). Maps to an income account in the chart of accounts and carries the tax treatment. Every
invoice line references one.

**Invoice** — a bill issued against a lease. Carries lines, tax, due date and a balance.

**Recurring invoice** — a rule on a lease that generates an invoice every cycle. Also called a
recurring charge.

**Charge escalation** — a schedule that raises a recurring charge over time (for example annual
rent increases), with projections you can review before they take effect.

**Adjustment** — a credit note or debit note that changes an invoice balance without receiving or
paying money.

**Void** — cancelling an issued invoice; the system reverses its ledger posting.

**Write-off** — accepting that a debt is uncollectable. The invoice stays for history; the
receivable is removed as bad debt. Not the same as a void.

**Tax exclusive** — the platform applies tax **on top of** the line amount, everywhere. A line of
KES 10,000 at 16% bills KES 11,600.

## Money received

**Payment** — money received (or, for payables, money sent), with a method, a date and a
reference.

**Allocation** — the act of applying a payment against one or more invoices. Until money is
allocated, the invoice is still outstanding even though cash has arrived.

**Wallet amount** — money received against a lease that has **not** been allocated to any invoice
yet. It is unapplied cash, and it is the only figure that can be netted off a balance.

**Prepaid amount** — an invoice's already-settled portion. It is *already inside* the invoice's due
amount; it is not additional money sitting somewhere. Prepaid attributes to the **invoice's** unit;
wallet attributes to the **payment's** unit.

**Due amount** — what remains payable on an invoice.

**Suspense** — received money that cannot yet be matched to a lease or a payer.

**Refund** — money returned to a payer, tracked as its own ledger with over-refund and bank
guards.

## Collections

**Case** — the recovery workflow for one indebted lease. One open case per lease at a time; a new
recovery cycle after closure opens a fresh case linked to the previous one.

**Debt item** — the breakdown of a case's debt by service type or invoice, refreshed from the
ledger. Read-only.

**Collectability score** — a 0–100 score (higher = more collectable) computed from aging mix,
debt-to-rent ratio, payment recency and regularity, partial-payment behaviour, promise history and
contact responsiveness. Bands **A** (80+) to **E** (\<20).

**Strategy (dunning ladder)** — the ordered list of steps applied to a case: reminders, demand
letter, IoT disconnect link, penalty, handover, agent task — each with a trigger delay, band
range, and whether it needs approval.

**Treatment state** — what is happening on the case: active, promise, dispute, hardship, legal
flagged. Tracked separately from case status (open / on hold / closed).

**Contact state** — not contacted, contacted, unreachable, or right party.

**Promise to Pay** — a recorded commitment from a resident to pay by a date, optionally split into
instalments, evaluated as kept, partially kept, missed, or renegotiated.

**Shadow mode** — the engine computes, scores and *stages* actions but sends nothing until a human
confirms. The default for anything that touches money or reaches a resident.

**Aging bucket** — how old the debt is: current, 1–30, 31–60, 61–90, 90+ days.

## Accounting

**Chart of accounts** — the account tree that every posting lands in.

**Journal** — the double-entry record generated from an operational event (invoice, payment,
allocation, expense, refund).

**Accounting period** — a month (or defined period) that can be open or closed. Closing prevents
further posting into history.

**Trial balance** — every account's debit and credit totals as at a date; the check that the books
balance.

**Profit & loss** — income and expenses over a date range.

**Balance sheet** — assets, liabilities and equity as at a date.

## Tax & compliance

**eTIMS** — the Kenya Revenue Authority's electronic tax invoice management system. Invoices are
submitted for certification.

**DigiTax** — the integration provider the platform submits through. Credentials are configured
per business.

**Tax class** — the KRA classification applied to a service type. The platform default is
**D (Non-VAT)**; VAT-rated items are mapped explicitly.

**Certified receipt** — the KRA-stamped result of a successful submission, including the QR code
and fiscal details, shown on the invoice.

**Re-file** — resubmitting an already-accepted invoice. Use with care: it reports the invoice to
KRA a second time.

## Ownership plans (TPS)

**TPS** — Tenant Purchase Scheme. A resident buys the unit over time under a contract.

**Amortisation schedule** — the instalment plan of principal and interest over the contract term.

**At-risk contract** — a contract in arrears against its schedule.

**Ownership progress** — how much of the purchase price has been settled.

**Certificate** — the document issued when ownership conditions are met.

## Utilities & IoT

**Smart meter** — a connected water, electricity or gas meter polled by a vendor integration.

**Reading** — a raw meter value at a point in time.

**Consumption** — the difference between two readings, after quality checks.

**Tariff** — the rate structure that converts consumption into money.

**Billing run** — the batch that turns a period's consumption into invoices, with per-unit run
items you can inspect before and after posting.

**Valve command** — a disconnect or reconnect instruction sent to a meter.

**IoT arrears enforcement** — the warn → disconnect → reconnect ladder driven by unpaid balances.

## Platform mechanics

**Setting** — a configuration value resolved through a scope chain: lease → unit → block → branch →
organisation → platform default. The most specific scope wins.

**Feature flag** — a switch that turns a module or behaviour on for a scope. Used to roll new
modules out branch by branch.

**Approval** — a routed decision on a high-impact action, handled in the approvals inbox.

**Audit event** — an append-only record of who changed what, when, and why.

**Job** — a scheduled background process (recurring invoices, allocation, penalties, collections
sweep, IoT polling). Jobs are individually switchable and default to off outside production.