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

# Ledger Roles

> Complete reference of system-defined account roles and their behaviors

## What are Ledger Roles?

**Ledger roles** are system-defined categories that determine how ledger accounts behave in Agatabo. Each account is assigned a role that controls:

* What types of transactions can affect it
* How it appears in financial statements
* Its normal debit or credit balance
* Its scope (organization-wide, per-member, per-loan, etc.)

<Note>
  **System-defined**: Ledger roles are built into Agatabo and cannot be modified. They ensure accounting consistency and automation.
</Note>

## Why Roles Matter

Roles ensure:

* **Consistency**: Same transaction types always use correct accounts
* **Automation**: Agatabo knows which accounts to debit/credit for each operation
* **Validation**: System prevents invalid account usage (e.g., can't debit income accounts)
* **Reporting**: Accounts grouped correctly in Balance Sheet and Income Statement
* **Scoping**: Enables per-member, per-loan, per-reserve accounting

***

## Complete Role Reference

### Asset Roles

Asset roles track what the organization owns or has a right to collect.

#### CASH

**Purpose**: Cash on hand and bank account balances

**Account type**: ASSET
**Normal balance**: Debit
**Scope**: Organization-wide or per bank account (`organization:{orgId}` or `bankAccount:{id}`)

**Increases (Debit):**

* Member deposits
* Loan payments received
* Revenue collection
* Asset sales

**Decreases (Credit):**

* Loan disbursements
* Expense payments
* Member withdrawals
* Asset purchases

**Example transactions:**

```
Member deposits 100,000 RWF:
  DEBIT: Cash +100,000
  CREDIT: Savings +100,000
```

***

#### LOAN\_RECEIVABLE

**Purpose**: Outstanding loan principal owed to the organization

**Account type**: ASSET
**Normal balance**: Debit
**Scope**: Per loan (`loan:{loanId}`)

**Increases (Debit):**

* Loan disbursements (new loans)

**Decreases (Credit):**

* Loan payments (principal portion only)
* Loan write-offs (bad debt)

**Example transactions:**

```
Disburse 500,000 RWF loan:
  DEBIT: Loan Receivable (loan:abc123) +500,000
  CREDIT: Cash -500,000

Receive 50,000 RWF principal payment:
  DEBIT: Cash +50,000
  CREDIT: Loan Receivable (loan:abc123) -50,000
```

***

#### INTEREST\_RECEIVABLE

**Purpose**: Accrued interest on loans not yet paid

**Account type**: ASSET
**Normal balance**: Debit
**Scope**: Per loan (`loan:{loanId}`)

**Increases (Debit):**

* Interest accrual over time
* Interest charged on loans

**Decreases (Credit):**

* Interest payments received

**Example transactions:**

```
Charge 10,000 RWF interest:
  DEBIT: Interest Receivable (loan:abc123) +10,000
  CREDIT: Interest Income +10,000

Receive interest payment:
  DEBIT: Cash +10,000
  CREDIT: Interest Receivable (loan:abc123) -10,000
```

***

#### PENALTY\_RECEIVABLE

**Purpose**: Late payment penalties and fees owed on loans

**Account type**: ASSET
**Normal balance**: Debit
**Scope**: Per loan (`loan:{loanId}`)

**Increases (Debit):**

* Late payment penalties applied
* Fee charges

**Decreases (Credit):**

* Penalty payments received
* Penalty waivers

**Example transactions:**

```
Charge 5,000 RWF late fee:
  DEBIT: Penalty Receivable (loan:abc123) +5,000
  CREDIT: Penalty Income +5,000
```

***

#### FIXED\_ASSET

**Purpose**: Long-term physical assets (equipment, furniture, vehicles, buildings)

**Account type**: ASSET
**Normal balance**: Debit
**Scope**: Per asset (`fixedAsset:{assetId}`)

**Increases (Debit):**

* Asset purchases
* Asset received as collateral
* Asset received as gift

**Decreases (Credit):**

* Asset sales
* Asset disposal
* Asset write-offs (damage, loss)

**Example transactions:**

```
Purchase 2,000,000 RWF vehicle:
  DEBIT: Fixed Asset (fixedAsset:vehicle123) +2,000,000
  CREDIT: Cash -2,000,000
```

***

### Liability Roles

Liability roles track what the organization owes to others.

#### SAVINGS

**Purpose**: Member savings account balances (funds members have deposited)

**Account type**: LIABILITY
**Normal balance**: Credit
**Scope**: Per member (`organizationUser:{userId}`)

**Increases (Credit):**

* Member deposits
* Dividend distributions
* Interest credited to savings

**Decreases (Debit):**

* Member withdrawals
* Loan disbursements (if from savings)

**Example transactions:**

```
Member deposits 100,000 RWF:
  DEBIT: Cash +100,000
  CREDIT: Savings (organizationUser:alice) +100,000

Member withdraws 50,000 RWF:
  DEBIT: Savings (organizationUser:alice) -50,000
  CREDIT: Cash -50,000

Distribute 10,000 RWF dividend:
  DEBIT: Retained Earnings -10,000
  CREDIT: Savings (organizationUser:alice) +10,000
```

<Warning>
  **Important**: This role is named **SAVINGS**, not "MEMBER\_SAVINGS" or "MEMBER\_EQUITY". Dividends credit SAVINGS accounts (liability), not a separate equity account.
</Warning>

***

#### BORROWER\_SURPLUS\_LIABILITY

**Purpose**: Amount owed to borrower when seized collateral value exceeds outstanding loan balance

**Account type**: LIABILITY
**Normal balance**: Credit
**Scope**: Per member (`organizationUser:{userId}`)

**Increases (Credit):**

* Collateral seizure (excess value over loan balance)

**Decreases (Debit):**

* Payment to borrower of surplus
* Offset against other debts

**Example transactions:**

```
Seize 1,000,000 RWF collateral for 800,000 RWF bad debt:
  DEBIT: Fixed Asset (collateral) +1,000,000
  DEBIT: Bad Debt Expense +800,000
  CREDIT: Loan Receivable -800,000
  CREDIT: Borrower Surplus Liability +200,000
```

***

### Equity Roles

Equity roles track the organization's net worth and retained funds.

#### RETAINED\_EARNINGS

**Purpose**: Accumulated organizational profits (net income over time)

**Account type**: EQUITY
**Normal balance**: Credit
**Scope**: Organization-wide (`organization:{orgId}`)

**Increases (Credit):**

* Net income transferred at period close
* Reversals of previous losses

**Decreases (Debit):**

* Dividend distributions
* Reserve allocations
* Net losses

**Example transactions:**

```
Close period with 5,000,000 RWF net income:
  DEBIT: Income Summary -5,000,000
  CREDIT: Retained Earnings +5,000,000

Distribute 2,000,000 RWF dividend:
  DEBIT: Retained Earnings -2,000,000
  CREDIT: Savings (various members) +2,000,000

Allocate 1,000,000 RWF to reserve:
  DEBIT: Reserve Allocation +1,000,000
  CREDIT: Retained Earnings -1,000,000
```

***

#### RESERVE\_ALLOCATION

**Purpose**: Designated retained earnings set aside for specific future purposes (emergency fund, equipment replacement, building fund, etc.)

**Account type**: EQUITY
**Normal balance**: Debit (contra-equity)
**Scope**: Per reserve (`reserve:{reserveId}`)

**Increases (Debit):**

* Reserve top-ups (allocations from retained earnings)

**Decreases (Credit):**

* Reserve releases (back to retained earnings)
* Reserve-funded expenses

**Example transactions:**

```
Allocate 1,000,000 RWF to emergency reserve:
  DEBIT: Reserve Allocation (reserve:emergency) +1,000,000
  CREDIT: Retained Earnings -1,000,000

Release 500,000 RWF from reserve:
  DEBIT: Retained Earnings +500,000
  CREDIT: Reserve Allocation (reserve:emergency) -500,000
```

<Note>
  **Reserves are equity**: Both RETAINED\_EARNINGS and RESERVE\_ALLOCATION are equity accounts. Allocating to reserves moves funds within equity (internal reclassification), not between account types.
</Note>

***

#### OPENING\_EQUITY

**Purpose**: Initial capital when organization starts or opening balances during system setup

**Account type**: EQUITY
**Normal balance**: Credit
**Scope**: Organization-wide (`organization:{orgId}`)

**Increases (Credit):**

* Initial capital contributions
* Opening balance entries during migration

**Decreases (Debit):**

* Corrections or adjustments

**Example transactions:**

```
Record 5,000,000 RWF opening cash balance:
  DEBIT: Cash +5,000,000
  CREDIT: Opening Equity +5,000,000
```

***

#### OTHER\_EQUITY

**Purpose**: Miscellaneous equity items not fitting other categories (donated capital, capital adjustments)

**Account type**: EQUITY
**Normal balance**: Credit
**Scope**: Organization-wide (`organization:{orgId}`)

**Increases (Credit):**

* Donated assets or funds
* Capital contributions
* Equity adjustments

**Decreases (Debit):**

* Reversals or corrections

**Example transactions:**

```
Receive 500,000 RWF donated equipment:
  DEBIT: Fixed Asset +500,000
  CREDIT: Other Equity +500,000
```

***

### Income Roles

Income roles track revenue earned by the organization.

#### INTEREST\_INCOME

**Purpose**: Interest earned on loans

**Account type**: INCOME
**Normal balance**: Credit
**Scope**: Organization-wide (`organization:{orgId}`)

**Increases (Credit):**

* Interest charged on loans
* Interest payments received

**Decreases (Debit):**

* Reversals or corrections

**Example transactions:**

```
Charge 10,000 RWF interest on loan:
  DEBIT: Interest Receivable +10,000
  CREDIT: Interest Income +10,000
```

***

#### PENALTY\_INCOME

**Purpose**: Late payment penalties and fees collected

**Account type**: INCOME
**Normal balance**: Credit
**Scope**: Organization-wide (`organization:{orgId}`)

**Increases (Credit):**

* Late payment penalties
* Fee charges

**Decreases (Debit):**

* Penalty waivers
* Reversals

**Example transactions:**

```
Charge 5,000 RWF late fee:
  DEBIT: Penalty Receivable +5,000
  CREDIT: Penalty Income +5,000
```

***

#### ENTRY\_FEE\_INCOME

**Purpose**: Membership fees collected when members join

**Account type**: INCOME
**Normal balance**: Credit
**Scope**: Organization-wide (`organization:{orgId}`)

**Increases (Credit):**

* Entry fee payments

**Decreases (Debit):**

* Refunds or reversals

**Example transactions:**

```
Collect 50,000 RWF entry fee:
  DEBIT: Cash +50,000
  CREDIT: Entry Fee Income +50,000
```

***

#### DISBURSEMENT\_FEE\_INCOME

**Purpose**: Fees charged for loan processing and disbursement

**Account type**: INCOME
**Normal balance**: Credit
**Scope**: Organization-wide (`organization:{orgId}`)

**Increases (Credit):**

* Loan processing fees
* Disbursement fees

**Decreases (Debit):**

* Fee refunds

**Example transactions:**

```
Charge 10,000 RWF loan processing fee:
  DEBIT: Cash +10,000
  CREDIT: Disbursement Fee Income +10,000
```

***

#### OTHER\_INCOME

**Purpose**: Miscellaneous revenue not fitting other categories

**Account type**: INCOME
**Normal balance**: Credit
**Scope**: Organization-wide (`organization:{orgId}`)

**Increases (Credit):**

* Asset rental income
* Service fees
* Other revenue sources

**Decreases (Debit):**

* Reversals

***

#### BAD\_DEBT\_RECOVERY\_INCOME

**Purpose**: Recovery of previously written-off loans (collateral seizure value, unexpected payments)

**Account type**: INCOME
**Normal balance**: Credit
**Scope**: Organization-wide (`organization:{orgId}`)

**Increases (Credit):**

* Collateral seizure proceeds
* Recovered payments on defaulted loans

**Decreases (Debit):**

* Reversals

**Example transactions:**

```
Seize 1,000,000 RWF collateral for 800,000 RWF bad debt:
  DEBIT: Fixed Asset +1,000,000
  CREDIT: Bad Debt Recovery Income +800,000
  CREDIT: Borrower Surplus Liability +200,000
```

***

### Expense Roles

Expense roles track costs incurred by the organization.

#### OPERATING\_EXPENSE

**Purpose**: General operational costs (rent, utilities, supplies, salaries, administrative expenses)

**Account type**: EXPENSE
**Normal balance**: Debit
**Scope**: Organization-wide (`organization:{orgId}`) or per expense category

**Increases (Debit):**

* Expense payments
* Accrued expenses

**Decreases (Credit):**

* Reversals or refunds

**Example transactions:**

```
Pay 50,000 RWF rent:
  DEBIT: Operating Expense +50,000
  CREDIT: Cash -50,000
```

***

#### BANK\_CHARGE\_EXPENSE

**Purpose**: Banking fees and charges

**Account type**: EXPENSE
**Normal balance**: Debit
**Scope**: Organization-wide (`organization:{orgId}`)

**Increases (Debit):**

* Bank fees
* Transaction charges
* Account maintenance fees

**Decreases (Credit):**

* Fee reversals or refunds

**Example transactions:**

```
Pay 2,000 RWF bank fee:
  DEBIT: Bank Charge Expense +2,000
  CREDIT: Cash -2,000
```

***

#### BAD\_DEBT\_EXPENSE

**Purpose**: Loans written off as uncollectible

**Account type**: EXPENSE
**Normal balance**: Debit
**Scope**: Organization-wide (`organization:{orgId}`)

**Increases (Debit):**

* Loan defaults and write-offs

**Decreases (Credit):**

* Reversals (if loan subsequently recovered)

**Example transactions:**

```
Write off 800,000 RWF defaulted loan:
  DEBIT: Bad Debt Expense +800,000
  CREDIT: Loan Receivable -800,000
```

***

## Account Scoping with Scope Keys

Agatabo uses **scope keys** to create multiple accounts with the same role for different entities.

### Scope Key Format

```
{entity_type}:{entity_id}
```

### Organization-Scoped Accounts

**Format**: `organization:{organizationId}`

Single account for entire organization:

* CASH (unless separate per bank account)
* RETAINED\_EARNINGS
* RESERVE\_ALLOCATION (per reserve, but using reserve:{id})
* All INCOME roles
* All EXPENSE roles
* OPENING\_EQUITY
* OTHER\_EQUITY

**Example**: `organization:org-123`

***

### Member-Scoped Accounts

**Format**: `organizationUser:{userId}`

Individual account per member:

* **SAVINGS**: Each member has their own savings account
* **BORROWER\_SURPLUS\_LIABILITY**: Tracked per member

**Example**: `organizationUser:alice-456`

***

### Loan-Scoped Accounts

**Format**: `loan:{loanId}`

Separate account per loan:

* **LOAN\_RECEIVABLE**: Principal balance
* **INTEREST\_RECEIVABLE**: Accrued interest
* **PENALTY\_RECEIVABLE**: Accrued penalties

**Example**: `loan:loan-789`

***

### Reserve-Scoped Accounts

**Format**: `reserve:{reserveId}`

Separate account per reserve:

* **RESERVE\_ALLOCATION**: Each reserve has its own equity account

**Example**: `reserve:emergency-fund-123`

***

### Asset-Scoped Accounts

**Format**: `fixedAsset:{assetId}`

Separate account per asset:

* **FIXED\_ASSET**: Each physical asset tracked separately

**Example**: `fixedAsset:vehicle-456`

***

### Bank Account-Scoped Accounts

**Format**: `bankAccount:{bankAccountId}`

Separate CASH account per bank account:

* **CASH**: One account per bank account

**Example**: `bankAccount:bank-789`

***

## How Agatabo Uses Roles

### Example 1: Member Deposit

When you record a deposit for Alice:

1. System finds Alice's **SAVINGS** account via scope key `organizationUser:alice-123`
2. System finds organization's **CASH** account
3. Creates journal entry:
   ```
   DEBIT: Cash (organization:org123) +100,000
   CREDIT: Savings (organizationUser:alice123) +100,000
   ```

***

### Example 2: Loan Disbursement

When you disburse a loan to Bob:

1. System creates new **LOAN\_RECEIVABLE** account with scope `loan:bob-loan-456`
2. System finds **CASH** account
3. Creates journal entry:
   ```
   DEBIT: Loan Receivable (loan:bob-loan-456) +500,000
   CREDIT: Cash (organization:org123) -500,000
   ```

***

### Example 3: Dividend Distribution

When you distribute dividends:

1. System finds organization's **RETAINED\_EARNINGS** account
2. System finds each member's **SAVINGS** account
3. Creates journal entry:
   ```
   DEBIT: Retained Earnings (organization:org123) -5,000,000
   CREDIT: Savings (organizationUser:alice) +100,000
   CREDIT: Savings (organizationUser:bob) +100,000
   CREDIT: Savings (organizationUser:carol) +100,000
   ... (50 members total)
   ```

***

### Example 4: Reserve Allocation

When you allocate to a reserve:

1. System finds specific **RESERVE\_ALLOCATION** account via scope `reserve:emergency-fund`
2. System finds organization's **RETAINED\_EARNINGS** account
3. Creates journal entry:
   ```
   DEBIT: Reserve Allocation (reserve:emergency-fund) +1,000,000
   CREDIT: Retained Earnings (organization:org123) -1,000,000
   ```

***

## Role Summary Table

| Role                         | Type      | Normal Balance | Scope Pattern               | Example Scope Key        |
| ---------------------------- | --------- | -------------- | --------------------------- | ------------------------ |
| CASH                         | ASSET     | Debit          | organization or bankAccount | `organization:org123`    |
| LOAN\_RECEIVABLE             | ASSET     | Debit          | loan                        | `loan:loan123`           |
| INTEREST\_RECEIVABLE         | ASSET     | Debit          | loan                        | `loan:loan123`           |
| PENALTY\_RECEIVABLE          | ASSET     | Debit          | loan                        | `loan:loan123`           |
| FIXED\_ASSET                 | ASSET     | Debit          | fixedAsset                  | `fixedAsset:car456`      |
| SAVINGS                      | LIABILITY | Credit         | organizationUser            | `organizationUser:alice` |
| BORROWER\_SURPLUS\_LIABILITY | LIABILITY | Credit         | organizationUser            | `organizationUser:bob`   |
| RETAINED\_EARNINGS           | EQUITY    | Credit         | organization                | `organization:org123`    |
| RESERVE\_ALLOCATION          | EQUITY    | Debit          | reserve                     | `reserve:emergency`      |
| OPENING\_EQUITY              | EQUITY    | Credit         | organization                | `organization:org123`    |
| OTHER\_EQUITY                | EQUITY    | Credit         | organization                | `organization:org123`    |
| INTEREST\_INCOME             | INCOME    | Credit         | organization                | `organization:org123`    |
| PENALTY\_INCOME              | INCOME    | Credit         | organization                | `organization:org123`    |
| ENTRY\_FEE\_INCOME           | INCOME    | Credit         | organization                | `organization:org123`    |
| DISBURSEMENT\_FEE\_INCOME    | INCOME    | Credit         | organization                | `organization:org123`    |
| OTHER\_INCOME                | INCOME    | Credit         | organization                | `organization:org123`    |
| BAD\_DEBT\_RECOVERY\_INCOME  | INCOME    | Credit         | organization                | `organization:org123`    |
| OPERATING\_EXPENSE           | EXPENSE   | Debit          | organization                | `organization:org123`    |
| BANK\_CHARGE\_EXPENSE        | EXPENSE   | Debit          | organization                | `organization:org123`    |
| BAD\_DEBT\_EXPENSE           | EXPENSE   | Debit          | organization                | `organization:org123`    |

***

## Roles Cannot Be Changed

<Warning>
  **System-defined roles**: Ledger roles are built into Agatabo and cannot be modified, renamed, or deleted. They are set when accounts are created and determine how Agatabo processes all transactions.
</Warning>

**Why roles are fixed:**

* Ensures accounting consistency across all organizations
* Enables automation of journal entries
* Maintains financial statement accuracy
* Prevents accounting errors from misconfigured accounts

**If you need different functionality:**

* Use existing roles creatively (e.g., OPERATING\_EXPENSE for various expense types)
* Contact support for custom requirements
* May require platform enhancement

***

## Best Practices

<Note>
  **Working with ledger roles:**

  **Understanding:**

  * Learn the roles relevant to your work (treasurers focus on CASH, SAVINGS; loan officers on LOAN\_RECEIVABLE)
  * Review this reference when creating manual journal entries
  * Understand scope keys for per-member, per-loan accounting

  **Usage:**

  * Trust automatic role assignment (Agatabo selects correctly)
  * Verify roles when reviewing journal entries
  * Report if transactions use unexpected roles (may indicate bug)
  * Use correct scope keys when querying accounts

  **Manual Entries:**

  * Consult this guide before creating manual entries
  * Verify you're using the right role for your purpose
  * Match role types correctly (ASSET with ASSET, LIABILITY with INCOME, etc.)
  * Include proper scope keys

  **Auditing:**

  * Review role assignments during financial audits
  * Verify scope keys are correct for entity-specific accounts
  * Check that all accounts follow role typing rules
  * Report anomalies to accountant or support
</Note>

***

## Need Help?

<CardGroup cols={2}>
  <Card title="General Ledger Overview" icon="book-open" href="/tontines/general-ledger/overview">
    Understand the accounting system
  </Card>

  <Card title="Understanding Double-Entry" icon="scale-balanced" href="/tontines/general-ledger/understanding-double-entry">
    Learn accounting basics
  </Card>

  <Card title="Viewing Journal Entries" icon="book" href="/tontines/general-ledger/viewing-journal-entries">
    See how roles are used in transactions
  </Card>

  <Card title="Manual Journal Entries" icon="pen-to-square" href="/tontines/general-ledger/manual-journal-entries">
    Create entries using specific roles
  </Card>

  <Card title="Balance Sheet" icon="file-invoice-dollar" href="/tontines/reports/balance-sheet">
    See how roles appear in financial statements
  </Card>
</CardGroup>