> ## 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.
# General Ledger Overview
> Understanding Agatabo's double-entry accounting system, journal entries, ledger accounts, and financial reporting foundation
## What is the General Ledger?
The general ledger is Agatabo's core accounting system that tracks all financial transactions using **double-entry bookkeeping**. Every deposit, loan disbursement, payment, expense, dividend, and reserve allocation creates journal entries that automatically maintain balanced accounts.
**Automatic accounting**: Most journal entries are created automatically when you perform business operations. You record transactions (deposits, loans, expenses), and Agatabo handles the accounting behind the scenes.
## Key Concepts
### Double-Entry Bookkeeping
Every transaction affects at least two accounts:
* **Debit** side: Increases assets/expenses, decreases liabilities/income/equity
* **Credit** side: Increases liabilities/income/equity, decreases assets/expenses
* **Balance requirement**: Total debits must always equal total credits
**Example:**
```
Member deposits 100,000 RWF to savings:
DEBIT: Cash +100,000 RWF (asset increases)
CREDIT: Member Savings +100,000 RWF (liability increases)
```
[Learn double-entry basics →](/tontines/general-ledger/understanding-double-entry)
***
### Journal Entries
A journal entry is a record of a financial transaction consisting of:
* **Kind**: Type of transaction (e.g., SAVINGS\_DEPOSIT, LOAN\_DISBURSEMENT, DIVIDEND\_DISTRIBUTION)
* **Transaction date**: When the transaction occurred
* **Status**: DRAFT or POSTED
* **Lines**: Debit and credit lines that must balance
* **Metadata**: Title, description, documents, idempotency key
* **References**: Links to specific entities (organizationUser, loan, reserve, etc.)
**Journal entry structure:**
```typescript theme={null}
{
id: string,
kind: journal_entry_kind,
transactionDate: Date,
status: 'DRAFT' | 'POSTED',
title: string | null,
description: string | null,
idempotencyKey: string | null,
lines: [
{
side: 'DEBIT' | 'CREDIT',
amount: Decimal,
ledgerAccount: {
id: string,
role: string,
type: 'ASSET' | 'LIABILITY' | 'EQUITY' | 'INCOME' | 'EXPENSE',
name: string,
scopeKey: string
}
},
...
]
}
```
***
### Journal Entry Kinds
Agatabo supports the following transaction types:
**Savings & Deposits:**
* **SAVINGS\_DEPOSIT**: Member deposits funds to savings account
* **ENTRY\_FEE**: Initial membership fee payment
**Loans:**
* **LOAN\_DISBURSEMENT**: Loan principal disbursed to member
* **LOAN\_PAYMENT**: Member makes loan payment (principal + interest)
* **LOAN\_PENALTY**: Late payment penalty applied
* **LOAN\_DEFAULT**: Loan written off as bad debt
* **INTEREST\_PAID\_IN\_ADVANCE**: Upfront interest payment
**Expenses:**
* **EXPENSE\_PAYMENT**: Operating expense payment
* **BANK\_CHARGE**: Bank fees and charges
**Reserves:**
* **RESERVE\_TOP\_UP**: Allocate funds from retained earnings to reserves
* **RESERVE\_RELEASE**: Release funds from reserves back to retained earnings
* **RESERVE\_EXPENSE**: Expense paid directly from reserve funds
**Dividends:**
* **DIVIDEND\_DISTRIBUTION**: Distribute retained earnings to member savings accounts
**Fixed Assets:**
* **ASSET\_CASH\_PURCHASE**: Purchase asset with cash
* **ASSET\_COLLATERAL**: Acquire asset as loan collateral
* **ASSET\_GIFT**: Receive donated asset
* **ASSET\_DISPOSAL**: Sell or dispose of asset
* **CASH\_OPENING**: Opening cash balance
**Administrative:**
* **REVERSAL**: Reverse a previous journal entry
* **PERIOD\_CLOSE**: Close accounting period and transfer net income to retained earnings
***
### Journal Entry Status
**DRAFT:**
* Entry created but not yet finalized
* Can be edited or deleted
* Does not affect account balances
* Not included in financial reports
* Used for preparing entries before posting
**POSTED:**
* Entry finalized and locked
* Cannot be edited or deleted (permanent)
* Affects account balances immediately
* Included in all financial reports
* Creates audit trail
**Status transition:**
```
DRAFT → POSTED (one-way, irreversible)
```
**Most entries are POSTED automatically**: When you record a transaction (deposit, loan payment, dividend distribution), Agatabo creates and posts the journal entry immediately. Manual entries can be created as drafts for review before posting.
***
### Ledger Accounts
Ledger accounts are categorized by **type** and **role**.
**Account types** (5 categories):
* **ASSET**: Resources owned (Cash, Loans Receivable, Fixed Assets)
* **LIABILITY**: Obligations owed (Member Savings, Borrower Surplus)
* **EQUITY**: Retained Earnings, Reserves, Opening Equity
* **INCOME**: Revenue sources (Interest, Fees, Penalties)
* **EXPENSE**: Costs incurred (Operating Expenses, Bad Debt, Bank Charges)
**Account roles** (specific purposes):
**Assets:**
* **CASH**: Cash on hand or in bank
* **LOAN\_RECEIVABLE**: Principal amount of loans outstanding
* **INTEREST\_RECEIVABLE**: Accrued interest not yet paid
* **PENALTY\_RECEIVABLE**: Accrued penalties not yet paid
* **FIXED\_ASSET**: Equipment, furniture, buildings
**Liabilities:**
* **SAVINGS**: Member savings balances (one account per member)
* **BORROWER\_SURPLUS\_LIABILITY**: Overpayments from borrowers
**Equity:**
* **RETAINED\_EARNINGS**: Accumulated profits
* **RESERVE\_ALLOCATION**: Designated reserves (one account per reserve)
* **OPENING\_EQUITY**: Initial capital
* **OTHER\_EQUITY**: Miscellaneous equity
**Income:**
* **INTEREST\_INCOME**: Interest earned on loans
* **PENALTY\_INCOME**: Late payment penalties
* **ENTRY\_FEE\_INCOME**: Membership fees
* **DISBURSEMENT\_FEE\_INCOME**: Loan processing fees
* **BAD\_DEBT\_RECOVERY\_INCOME**: Recovered bad debt
* **OTHER\_INCOME**: Miscellaneous income
**Expenses:**
* **OPERATING\_EXPENSE**: General operating costs
* **BANK\_CHARGE\_EXPENSE**: Bank fees
* **BAD\_DEBT\_EXPENSE**: Loan write-offs
[View all ledger roles →](/tontines/general-ledger/ledger-roles)
***
### Scope Keys
Scope keys link ledger accounts to specific entities.
**Format:**
```
{entity_type}:{entity_id}
```
**Examples:**
```
organizationUser:abc-123 → Member's SAVINGS account
reserve:xyz-789 → Specific reserve's RESERVE_ALLOCATION account
loan:def-456 → Specific loan's LOAN_RECEIVABLE account
organization:org-001 → Organization-wide CASH account
```
**Purpose:**
* Allows multiple accounts with same role (e.g., one SAVINGS account per member)
* Links accounts to specific members, loans, reserves, or organization
* Enables querying all accounts for a specific entity
* Supports per-member, per-loan, per-reserve accounting
**Scope patterns:**
* **Organization-scoped**: `organization:{orgId}` (CASH, RETAINED\_EARNINGS, INTEREST\_INCOME, etc.)
* **Member-scoped**: `organizationUser:{userId}` (SAVINGS)
* **Loan-scoped**: `loan:{loanId}` (LOAN\_RECEIVABLE, INTEREST\_RECEIVABLE, PENALTY\_RECEIVABLE)
* **Reserve-scoped**: `reserve:{reserveId}` (RESERVE\_ALLOCATION)
* **Asset-scoped**: `fixedAsset:{assetId}` (FIXED\_ASSET)
***
## How Transactions Create Journal Entries
### Example 1: Member Deposits 500,000 RWF
**Transaction:** Member Alice deposits 500,000 RWF to her savings account
**Journal entry created:**
```
Kind: SAVINGS_DEPOSIT
Status: POSTED
Transaction Date: 2026-06-12
Lines:
DEBIT: Cash (organization:org123) +500,000 RWF
CREDIT: Savings (organizationUser:alice123) +500,000 RWF
```
**Result:**
* Cash balance increases by 500,000
* Alice's savings balance increases by 500,000
* Entry is balanced (debit = credit)
***
### Example 2: Loan Disbursed 2,000,000 RWF
**Transaction:** Member Bob receives a 2,000,000 RWF loan
**Journal entry created:**
```
Kind: LOAN_DISBURSEMENT
Status: POSTED
Transaction Date: 2026-06-12
Lines:
DEBIT: Loan Receivable (loan:bob-loan-123) +2,000,000 RWF
CREDIT: Cash (organization:org123) -2,000,000 RWF
```
**Result:**
* Loan receivable increases by 2,000,000 (asset)
* Cash decreases by 2,000,000
* Loan balance tracked in dedicated account
***
### Example 3: Dividend Distribution 5,000,000 RWF
**Transaction:** Distribute 5,000,000 RWF dividend to 50 members
**Journal entry created:**
```
Kind: DIVIDEND_DISTRIBUTION
Status: POSTED
Transaction Date: 2026-06-12
Lines:
DEBIT: Retained Earnings (organization:org123) -5,000,000 RWF
CREDIT: Savings (organizationUser:alice) +100,000 RWF
CREDIT: Savings (organizationUser:bob) +100,000 RWF
CREDIT: Savings (organizationUser:carol) +100,000 RWF
... (50 members total)
```
**Result:**
* Retained earnings decreases by 5,000,000
* Each member's savings increases by their dividend share
* One journal entry with multiple credit lines
***
### Example 4: Reserve Allocation 1,000,000 RWF
**Transaction:** Allocate 1,000,000 RWF from retained earnings to emergency fund reserve
**Journal entry created:**
```
Kind: RESERVE_TOP_UP
Status: POSTED
Transaction Date: 2026-06-12
Lines:
DEBIT: Reserve Allocation (reserve:emergency-fund) +1,000,000 RWF
CREDIT: Retained Earnings (organization:org123) -1,000,000 RWF
```
**Result:**
* Emergency fund reserve balance increases by 1,000,000
* Retained earnings decreases by 1,000,000
* Both are equity accounts (internal transfer within equity section)
***
## Viewing Journal Entries
Click **General Ledger** → **Journal Entries** in sidebar
Filter by kind, date range, status, or search
Click on entry to see all lines and metadata
Use for audit trail, reconciliation, or reporting
[Learn how to view journal entries →](/tontines/general-ledger/viewing-journal-entries)
***
## Creating Manual Journal Entries
Most journal entries are automatic, but you can create manual entries for:
* Adjustments and corrections
* Accruals and deferrals
* One-time transactions not supported by standard features
* Testing or data migration
**Manual entries require accounting knowledge**: Ensure you understand double-entry accounting before creating manual journal entries. Incorrect entries can make your books unbalanced.
[Learn how to create manual entries →](/tontines/general-ledger/manual-journal-entries)
***
## Accounting Period Constraints
Journal entries are subject to accounting period rules:
**Rules:**
* Cannot post entries with transaction date in a **closed accounting period**
* Transaction date must be in an open period
* Once a period is closed, all entries with dates in that period are locked
* Prevents backdating transactions or altering historical records
**Example:**
```
Closed periods: Jan 1 - Mar 31, 2026
Current open period: Apr 1 - Jun 30, 2026
Valid transaction dates: Apr 1, 2026 or later
Invalid: Mar 31, 2026 or earlier (period closed)
```
[Learn about accounting periods →](/tontines/concepts/accounting-periods)
***
## Idempotency
Journal entries support idempotency to prevent duplicate transactions:
**How it works:**
* Supply an `idempotencyKey` when creating a journal entry
* If same key used twice, second request returns the existing entry (no duplicate)
* Safe to retry failed requests without creating duplicates
**Example:**
```
POST /journal-entries
Headers:
x-idempotency-key: unique-key-123
If network fails and request is retried with same key:
→ Returns existing entry created by first request
→ No duplicate entry created
```
**Use cases:**
* Dividend distributions (prevent double-distribution)
* Reserve allocations
* Bulk operations
* API retries after network failures
***
## Best Practices
**General ledger best practices:**
**For Non-Accountants:**
* Trust the automatic journal entries (they're correct)
* Review journal entries periodically to understand cash flow
* Don't create manual entries unless necessary
* Ask an accountant if unsure about manual entries
* Use trial balance to verify books balance
**For Accountants:**
* Review journal entries regularly for accuracy
* Use manual entries sparingly (only when necessary)
* Always document manual entries with clear descriptions
* Verify trial balance before closing accounting periods
* Export journal entries for external audit
* Monitor for unbalanced entries (should never occur)
**Audit Trail:**
* All journal entries are permanent once posted
* Cannot delete or modify posted entries
* Use REVERSAL entries to correct mistakes
* Keep idempotency keys for distributed operations
* Document reasons for manual adjustments
**Reconciliation:**
* Run trial balance monthly
* Reconcile bank accounts with CASH ledger account
* Verify member savings balances match SAVINGS account totals
* Check that loans outstanding match LOAN\_RECEIVABLE total
* Investigate any discrepancies immediately
***
## Common Operations
Accounting basics for non-accountants
Complete list of account roles and types
Review transaction records and audit trail
Create manual accounting adjustments
Detect and resolve accounting discrepancies
***
## For Different User Types
### For Non-Accountants (Treasurers, Administrators)
**What you need to know:**
* Journal entries are created automatically when you record transactions
* You don't need to understand debits/credits for day-to-day operations
* Review journal entries to understand where money is going
* Use reports (Balance Sheet, Income Statement) instead of raw journal entries
* Trust the system to handle accounting correctly
**When to involve an accountant:**
* Before creating manual journal entries
* When reconciling discrepancies
* Before closing accounting periods
* For audit preparation
* When interpreting complex transactions
***
### For Accountants
**What you need to know:**
* System uses proper double-entry accounting throughout
* All automatic entries are balanced and validated
* Journal entry kinds map to specific business transactions
* Scope keys enable per-entity accounting (member, loan, reserve)
* All entries should always balance (report issues if not)
* Manual entries available for adjustments and corrections
* Export capabilities for external audit
**Key responsibilities:**
* Review ledger accounts before period close
* Verify reconciliation regularly
* Create manual entries when needed (with documentation)
* Prepare financial statements
* Audit journal entries for accuracy
* Train non-accounting staff on basic concepts
***
## Related Topics
View assets, liabilities, and equity
View revenue and expenses
Understand period closure and constraints
How profits accumulate in equity