> ## 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.

# Collections overview

> The debt collection console — arrears exposure, aging, case flow, collection rate and enforcement, in one screen.

**Finance → Collections → `/collections/overview`** <sup>Beta</sup>

Collections turns debt from *a report somebody reads* into *a queue somebody works*:

> debt detected → case opened → scored and prioritised → assigned → contacted → commitment
> recorded → payment monitored → escalated or closed.

The **overview console** is the module's landing page. It answers three questions before you open
a single case: how much is owed, how old it is, and whether the team is keeping up.

<Note>
  Collections is an **orchestrator over the accounting ledger, not a second ledger**. Invoices,
  payments, allocations and balances stay authoritative in the core ledger; Collections manages the
  recovery *process*. That is why a case, the debt-aging report and a tenant statement always agree.
</Note>

## What the console shows

| Panel                   | What it tells you                                                                                                        |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Arrears exposure**    | Total amount in arrears for the branch, split into *in arrears* vs *not yet due*, with the oldest overdue date.          |
| **Ageing**              | The arrears book broken into buckets — current, 1–30, 31–60, 61–90, 90+ days.                                            |
| **Arrears book**        | The composition of debt, filterable by service type so you can see whether the problem is rent, water or service charge. |
| **Billed vs collected** | Billing performance over the period, by service type: what fell due, what was collected, and what is still outstanding.  |
| **Collection rate**     | Collected ÷ billed, to date.                                                                                             |
| **Case flow**           | Cases opened vs cases closed over the period — whether the book is being worked down or is growing.                      |
| **Risk**                | Distribution of cases across collectability bands A–E.                                                                   |
| **Officer activity**    | Contact and interaction volume, so managers can see who is actually working their queue.                                 |
| **Penalties**           | Late-fee assessment activity and value. See [Penalties](/guides/collections/penalties).                                  |
| **Legal register**      | Open matters, claim values and costs incurred. See [Legal register](/guides/collections/legal-register).                 |

Each panel has a **How these are calculated** disclosure that states the exact definition used, so
a number on the console can be reconciled against the underlying report.

## How debt reaches the console

The engine sweeps arrears on a schedule (and re-evaluates a single lease immediately when a
payment or allocation lands, so cases clear promptly).

<Steps>
  <Step title="Balance read">
    Per-lease balances are read from the ledger with the same semantics as the debt-aging report:
    gross due, wallet (unallocated cash), net balance, bucket amounts, oldest due date and last
    payment date — plus a per-service-type breakdown.
  </Step>

  <Step title="Entry test">
    A lease enters collections when it crosses the configured thresholds — minimum balance,
    minimum age in days, and which debt counts (all, rent only, or utilities only).
  </Step>

  <Step title="Case open">
    A case is opened for the lease and the resolved strategy and thresholds are **snapshotted onto
    it**, so later config changes never rewrite an in-flight case.
  </Step>

  <Step title="Score">
    A collectability score (0–100, bands A–E) is computed and stored with the feature values that
    produced it.
  </Step>

  <Step title="Stage the next action">
    The next step on the dunning ladder is *staged*, not sent.
  </Step>
</Steps>

<Warning>
  **Gross due and wallet are always shown separately.** Netting unallocated cash into the balance is
  correct for triggers, but it can mask contractual debt if that is all you look at. The console
  deliberately shows both.
</Warning>

## Shadow mode

Phase 1 runs **recommend-only**. The engine computes, scores, assigns and stages actions — a human
confirms every send, disconnect and fee. Autonomy is earned per branch through the enforcement-mode
setting, never by a global switch.

This is the same convention the IoT arrears engine and the Boma Yangu dispatcher follow: nothing
that touches money or reaches a resident goes out unattended until it has been proven in shadow.

## The pieces of the module

<Columns cols={2}>
  <Card title="Worklist & cases" icon="list-check" href="/guides/collections/worklist-and-cases">
    The ranked queue and the case workspace where the work actually happens.
  </Card>

  <Card title="Strategies" icon="stairs" href="/guides/collections/strategies">
    The dunning ladders that decide what happens next, and when.
  </Card>

  <Card title="Promise to Pay" icon="handshake" href="/guides/collections/promise-to-pay">
    Recorded commitments, instalments, and kept/broken evaluation.
  </Card>

  <Card title="Penalties" icon="triangle-exclamation" href="/guides/collections/penalties">
    Late-fee policies and the assessments they produce.
  </Card>

  <Card title="Legal register" icon="gavel" href="/guides/collections/legal-register">
    Matters, hearings, parties and costs once a case leaves internal recovery.
  </Card>

  <Card title="Debt aging" icon="hourglass-half" href="/guides/collections/debt-aging">
    The underlying arrears report, by lease and by service type.
  </Card>
</Columns>

## Configuration checklist

Before Collections is useful in a branch, an administrator sets:

1. **Feature flag** — the collections module enabled for the branch.
2. **Entry thresholds** — minimum balance, minimum age, debt scope, exit hysteresis.
3. **Strategy** — which dunning ladder applies, resolved through the settings scope chain
   (lease → unit → block → branch → organisation → default).
4. **Templates** — the message templates the ladder's reminder and demand-letter steps render.
5. **Assignment rules** — manual, round-robin, by branch, or by balance band.
6. **Enforcement mode** — shadow (default) or autonomous, per branch.

See [Settings](/guides/settings) and [Feature flags](/guides/feature-flags).

## Reading the numbers correctly

* **Net balance** = gross due − wallet. Used for triggers and exit tests.
* **Priority** ≈ net balance × (100 − score). Big debt owed by an unlikely payer floats up.
* **Delinquency bucket** and **recovery state** are *derived from the ledger on read*, never stored
  — they cannot drift from the accounts.
* **Disputed amounts** (where enabled) are excluded from collectible balance and from ladder
  triggers; recovery continues on the undisputed remainder.