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

# Creating Reserves

> Set up new reserve allocations for designated savings and specific future purposes

## Overview

Creating a reserve establishes a designated fund within your organization's equity for a specific future purpose. Reserves help you organize and track savings toward goals while keeping funds separate from general retained earnings.

<Note>
  **What happens**: Creating a reserve sets up the tracking structure (metadata + ledger account) but does NOT allocate any funds yet. New reserves start with a **balance of zero** and must be topped up separately.
</Note>

## Before You Begin

<Note>
  **Prerequisites:**

  * You have `reserves:write` permission
  * You have identified a specific purpose for the reserve
  * You have determined target reserve amount (optional but recommended)
  * You've decided on a unique, descriptive name
</Note>

<Warning>
  **Note**: You do NOT need existing retained earnings to create a reserve - only to allocate funds to it later. Creating the reserve is just setting up the structure.
</Warning>

## Step-by-Step Instructions

### Step 1: Navigate to Reserves

<Steps>
  <Step title="Open Reserves section">
    Click **Reserves** in the left sidebar
  </Step>

  <Step title="Click Add Reserve or New Reserve">
    Opens the reserve creation dialog
  </Step>
</Steps>

***

### Step 2: Enter Reserve Details

| Field           | Description                                  | Required | Default       |
| --------------- | -------------------------------------------- | -------- | ------------- |
| **Name**        | Short, descriptive name for the reserve      | Yes      | -             |
| **Description** | Purpose, target amount, and usage guidelines | No       | Empty         |
| **Active**      | Whether reserve can receive allocations      | No       | true (Active) |

***

### Step 3: Choose Reserve Name

Use clear, specific names that indicate purpose:

**Good names:**

* "Emergency Fund"
* "Building Purchase Reserve"
* "Computer Equipment Replacement"
* "Loan Loss Reserve"
* "Member Dividend Reserve 2026"
* "Statutory Reserve"
* "Expansion Fund"

**Poor names:**

* "Reserve 1"
* "Miscellaneous"
* "Money"
* "Savings"

**Naming rules**:

* Must be non-empty string
* Must be **unique within your organization** (cannot duplicate existing reserve name)
* Can be updated later if needed
* Used in ledger account name: "{Name} Reserve Allocation"

<Note>
  **Naming tip**: Include the year if the reserve is time-specific (e.g., "Expansion Fund 2026"). For ongoing reserves, use general names (e.g., "Emergency Reserve").
</Note>

***

### Step 4: Add Description (Optional but Recommended)

Provide details about the reserve's purpose, target amount, and usage rules:

**Example descriptions:**

**Emergency Reserve:**

```
Purpose: Cover unexpected operational expenses and cash flow gaps
Target: 3,000,000 RWF (3 months operating expenses)
Allocation: 200,000 RWF monthly until target reached
Usage: Requires treasurer + chairperson approval for releases
Review: Quarterly balance review
Established: June 2026
```

**Building Fund:**

```
Purpose: Save toward purchasing office space in Kimihurura
Target: 25,000,000 RWF
Timeline: Accumulate over 5 years (2026-2031)
Allocation: 20% of monthly net profit + any large donations
Expected purchase: 2031
```

**Loan Loss Reserve:**

```
Purpose: Cover bad debt from loan defaults
Target: 5% of total outstanding loans (currently 1,500,000 RWF)
Allocation: 50,000 RWF monthly + 5% of new loan disbursements
Usage: Offset loan write-offs and bad debt expenses
Review: Adjust quarterly based on portfolio size and delinquency rates
```

**Equipment Reserve:**

```
Purpose: Replace aging computers and office equipment
Target: 2,000,000 RWF
Equipment list:
  - 5 laptops @ 800,000 RWF each
  - 2 printers @ 300,000 RWF each
Timeline: Purchase in Q4 2027
Allocation: 80,000 RWF monthly for 25 months
```

***

### Step 5: Set Active Status

**Active** (recommended for new reserves):

* Reserve can receive top-ups
* Appears in allocation dialogs and dropdown lists
* Default setting for all new reserves

**Inactive**:

* Reserve cannot receive new allocations or releases
* Use when reserve is fully funded and no longer growing
* Use when reserve purpose is complete but keeping for historical tracking
* Can be toggled back to active later if needed

<Note>
  **When to mark inactive**:

  * After reserve reaches target and no more allocations needed
  * When reserve purpose is obsolete but you want to keep the record
  * For year-specific reserves after the year ends (e.g., "Dividend Reserve 2025" after 2025)
</Note>

***

### Step 6: Submit

<Steps>
  <Step title="Review all fields">
    Verify name is unique, descriptive, and clear<br />
    Check description includes target amount and purpose
  </Step>

  <Step title="Click Save or Create Reserve">
    Reserve is created with zero balance
  </Step>

  <Step title="Confirm creation">
    Reserve appears in reserves list
  </Step>

  <Step title="Allocate initial funds (next step)">
    After creation, navigate to reserve and use "Top Up" to add funds
  </Step>
</Steps>

***

## What Happens During Creation

When you create a reserve, Agatabo automatically:

1. **Creates ReserveAllocationMeta record**
   * Stores reserve metadata (id, name, description, isActive)
   * Links to your organization
   * Generates unique UUID identifier

2. **Creates linked ledger account**
   * Role: RESERVE\_ALLOCATION (equity account type)
   * Scope key: `reserve:{reserveId}` (unique identifier)
   * Account name: "\{Reserve Name} Reserve Allocation"
   * Initial balance: 0 (zero)

3. **Adds to reserves list**
   * Appears in reserve listing pages
   * Available in allocation dropdowns (if active)
   * Queryable via `/reserve-allocations` endpoint

4. **Logs in audit trail**
   * Records who created the reserve
   * Timestamp of creation
   * Initial configuration

<Note>
  **Important**: New reserves start at **zero balance**. After creating a reserve, you must separately allocate funds to it using the "Top Up" or "Adjust Balance" action. Creating the reserve just establishes the tracking structure - no accounting entries are created until you allocate funds.
</Note>

[Learn how to allocate funds →](/tontines/reserves/reserve-allocations)

***

## Common Scenarios

### Setting Up Standard Reserve Set

Many tontines benefit from these core reserves:

<Steps>
  <Step title="Create Emergency Reserve">
    **Name**: "Emergency Fund"<br />
    **Description**: "Cover unexpected operational expenses. Target: 3,000,000 RWF (3 months operating expenses). Allocate 200,000 RWF monthly."<br />
    **Active**: Yes
  </Step>

  <Step title="Create Loan Loss Reserve">
    **Name**: "Loan Loss Reserve"<br />
    **Description**: "Cover bad debt from loan defaults. Target: 5-10% of outstanding loans. Review quarterly."<br />
    **Active**: Yes
  </Step>

  <Step title="Create Equipment Reserve">
    **Name**: "Equipment Replacement"<br />
    **Description**: "Replace aging computers and furniture. Target: Based on equipment lifecycle. Allocate 100,000 RWF monthly."<br />
    **Active**: Yes
  </Step>

  <Step title="Establish allocation policy">
    Document in bylaws: "Allocate 15% of monthly profit to Emergency, 5% to Loan Loss, 10% to Equipment"
  </Step>

  <Step title="Begin monthly allocations">
    After all reserves created, start regular monthly top-ups
  </Step>
</Steps>

***

### Creating Project-Specific Reserve

For one-time goals with specific timelines:

<Steps>
  <Step title="Create reserve with project name">
    **Name**: "Office Building Fund 2026-2030"<br />
    **Description**: "Save toward purchasing 200sqm office space in Kimihurura. Target: 30,000,000 RWF. Purchase planned: December 2030. Allocate 25% of monthly profit."
  </Step>

  <Step title="Set clear timeline">
    Include start and end dates in description
  </Step>

  <Step title="Calculate monthly allocation">
    Target / Number of months = Monthly allocation<br />
    30,000,000 RWF / 60 months = 500,000 RWF/month
  </Step>

  <Step title="Begin aggressive allocations">
    Larger monthly allocations to reach goal by deadline
  </Step>

  <Step title="Mark inactive after use">
    Once funds released and building purchased, mark inactive (or delete if balance is zero)
  </Step>
</Steps>

***

### Creating Year-Specific Reserve

For annual recurring purposes:

<Steps>
  <Step title="Create with year in name">
    **Name**: "Member Dividend Reserve 2026"<br />
    **Description**: "Designated funds for 2026 annual dividend distribution. Target: 5,000,000 RWF. Distribution: December 2026 AGM."
  </Step>

  <Step title="Allocate throughout year">
    Monthly allocations from retained earnings
  </Step>

  <Step title="Release for dividend payment">
    When ready to distribute, release funds and record dividend expense
  </Step>

  <Step title="Mark inactive after year-end">
    After distribution complete, mark inactive
  </Step>

  <Step title="Create next year's reserve">
    In January 2027, create "Member Dividend Reserve 2027"
  </Step>
</Steps>

***

### Replacing or Restructuring Reserve

If you need to rename or restructure:

**Option 1: Update Existing Reserve** (recommended)

<Steps>
  <Step title="Navigate to reserve details">
    Find the reserve you want to update
  </Step>

  <Step title="Click Edit or Update">
    Modify name, description, or active status
  </Step>

  <Step title="Save changes">
    Reserve updated, balance and history preserved
  </Step>
</Steps>

**Option 2: Delete and Recreate** (only if no history)

<Steps>
  <Step title="Check reserve balance">
    Must be exactly zero to delete
  </Step>

  <Step title="Check transaction history">
    Must have no posted journal entries (no top-ups or releases ever recorded)
  </Step>

  <Step title="Delete old reserve">
    Only possible if both conditions met
  </Step>

  <Step title="Create new reserve">
    With updated name and purpose
  </Step>
</Steps>

**Option 3: Transfer and Replace** (if reserve has balance)

<Steps>
  <Step title="Release all funds from old reserve">
    Withdraw entire balance back to retained earnings
  </Step>

  <Step title="Mark old reserve inactive">
    Preserves historical records (cannot delete if has transaction history)
  </Step>

  <Step title="Create new reserve">
    With updated name and structure
  </Step>

  <Step title="Allocate funds to new reserve">
    Transfer funds from retained earnings to new reserve
  </Step>
</Steps>

***

## Validation and Constraints

### Name Validation

**Rules**:

* ✅ Must be non-empty string
* ✅ Must be unique within organization (case-sensitive)
* ❌ Cannot be blank or whitespace only
* ❌ Cannot duplicate existing reserve name

**If name already exists**:

* Error: "A reserve with this name already exists"
* Choose different name
* Or update existing reserve instead of creating new one
* Consider adding year or version (e.g., "Emergency Fund v2")

### Description

**Rules**:

* ✅ Optional field
* ✅ Can be null or empty string
* ✅ No length limit (but keep reasonable for readability)

### Active Status

**Rules**:

* ✅ Optional field
* ✅ Boolean: true (active) or false (inactive)
* ✅ Defaults to true if not specified

### Initial Balance

**Fixed value**:

* All new reserves start with balance = 0
* Cannot set initial balance during creation
* Must use "Top Up" operation after creation to allocate funds

***

## Best Practices

<Note>
  **Reserve setup tips:**

  **Naming:**

  * Use consistent naming conventions (e.g., all end with "Reserve" or "Fund")
  * Include year for time-specific reserves ("Expansion Fund 2026")
  * Use descriptive names that clearly indicate purpose
  * Keep names concise but meaningful (under 50 characters)

  **Quantity:**

  * Limit to 3-7 reserves (too many become difficult to manage)
  * Don't create a reserve unless you intend to actually allocate to it
  * Consolidate similar-purpose reserves rather than creating many small ones

  **Documentation:**

  * Always add detailed description with target amount
  * Include allocation policy (% of profit, fixed monthly amount)
  * Document usage/approval requirements
  * Specify review frequency (monthly, quarterly, annually)

  **Targets:**

  * Set specific, measurable targets in descriptions
  * Emergency fund: 3-6 months operating expenses
  * Loan loss: 5-10% of outstanding loans
  * Equipment: Based on replacement cost and lifecycle
  * Building/expansion: Based on project estimates

  **Governance:**

  * Get member approval for reserve policies (good governance)
  * Document reserve strategy in bylaws or financial guidelines
  * Review reserve structure annually - consolidate or eliminate unused reserves
  * Report reserve balances and targets to members at meetings

  **Management:**

  * Create all planned reserves upfront (don't add ad-hoc)
  * Begin allocations immediately after creation
  * Mark inactive rather than deleting (preserves history)
  * Review descriptions annually and update targets as needed
</Note>

***

## Troubleshooting

### "A reserve with this name already exists"

**Cause**: Reserve names must be unique within your organization

**Solutions**:

1. Choose a different name
2. Add year or version to differentiate (e.g., "Emergency Fund 2026")
3. Check if you meant to update the existing reserve instead
4. View reserves list to see all existing names

***

### Cannot allocate funds after creating reserve

**Cause**: New reserves start with zero balance - creation and allocation are separate operations

**Solution**:

<Steps>
  <Step title="Navigate to reserve details">
    Click on the newly created reserve in the list
  </Step>

  <Step title="Click Top Up or Adjust Balance">
    Opens the balance adjustment dialog
  </Step>

  <Step title="Select Top Up action">
    Choose "TOP\_UP" (not "RELEASE")
  </Step>

  <Step title="Enter amount">
    Amount to allocate from retained earnings (must have sufficient retained earnings)
  </Step>

  <Step title="Confirm">
    Funds transferred from retained earnings to reserve
  </Step>
</Steps>

[Learn about reserve allocations →](/tontines/reserves/reserve-allocations)

***

### Reserve doesn't appear in allocation dropdown

**Possible causes**:

1. **Reserve is inactive**
   * Solution: Edit reserve and set Active = true

2. **Missing permissions**
   * Solution: Ensure you have `reserves:read` permission

3. **Page not refreshed**
   * Solution: Refresh the page to reload reserve list

4. **Frontend filter**
   * Solution: Check if dropdown filters out certain reserves

***

### Cannot delete newly created reserve

**Cause**: Even new reserves with zero balance cannot be deleted if they have ANY transaction history

**Explanation**:

* Creating the reserve creates the ledger account
* But ledger account creation is NOT a transaction
* Reserve is only deletable if it has NEVER had any top-ups or releases
* If you did even one top-up then released it all, cannot delete (has history)

**Solution**:

* Mark the reserve as inactive instead of deleting
* Or use a different name if you must recreate

***

## Permissions Required

| Action         | Permission       | Scope                                   |
| -------------- | ---------------- | --------------------------------------- |
| View reserves  | `reserves:read`  | ANY                                     |
| Create reserve | `reserves:write` | ANY                                     |
| Update reserve | `reserves:write` | ANY                                     |
| Delete reserve | `reserves:write` | ANY (only if zero balance + no history) |

<Note>
  **Typical roles**: Administrators and Accountants have `reserves:write`. Regular members typically have `reserves:read` (view only) or no access.
</Note>

***

## Technical Details

### API Endpoint

```
POST /reserve-allocations

Headers:
  x-organization-id: <organization_id>

Body:
{
  "name": "Emergency Fund",
  "description": "Cover unexpected expenses. Target: 3M RWF.",
  "isActive": true
}

Response:
{
  "id": "<reserve_id>",
  "organizationId": "<organization_id>",
  "name": "Emergency Fund",
  "description": "Cover unexpected expenses. Target: 3M RWF.",
  "isActive": true,
  "balance": 0,
  "createdAt": "2026-06-12T10:30:00Z",
  "updatedAt": "2026-06-12T10:30:00Z"
}
```

### Database Structure

**ReserveAllocationMeta**:

```typescript theme={null}
{
  id: string (UUID)
  organizationId: string
  ledgerAccountId: string (unique, auto-created)
  name: string (unique per organization)
  description: string | null
  isActive: boolean (default: true)
  createdAt: DateTime
  updatedAt: DateTime
}
```

**Linked Ledger Account**:

```typescript theme={null}
{
  id: string (UUID)
  organizationId: string
  roleDefinitionId: string (RESERVE_ALLOCATION role)
  scopeKey: "reserve:{reserveAllocationId}"
  name: "{Reserve Name} Reserve Allocation"
  balance: Decimal (starts at 0)
  accountType: "EQUITY"
}
```

### Scope Key Format

```
reserve:{reserveAllocationId}

Example:
reserve:550e8400-e29b-41d4-a716-446655440000
```

This scope key uniquely identifies the ledger account for this specific reserve allocation.

***

## Related Topics

<CardGroup cols={2}>
  <Card title="Reserves Overview" icon="info" href="/tontines/reserves/overview">
    Understand reserves concept and how they work
  </Card>

  <Card title="Reserve Allocations" icon="arrow-up" href="/tontines/reserves/reserve-allocations">
    Add funds to reserves (Top Up)
  </Card>

  <Card title="Reserve Withdrawals" icon="arrow-down" href="/tontines/reserves/reserve-withdrawals">
    Release funds from reserves
  </Card>

  <Card title="Reserve Reporting" icon="chart-bar" href="/tontines/reserves/reserve-reporting">
    View balances and transaction history
  </Card>

  <Card title="Managing Reserves" icon="pen-to-square" href="/tontines/reserves/managing-reserves">
    Edit or delete reserves
  </Card>

  <Card title="Reserve-Funded Expenses" icon="receipt" href="/tontines/expenses/recording-expenses">
    Spend directly from reserves
  </Card>
</CardGroup>