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

# Permissions Matrix

> Complete reference of all permissions and role mappings

## Overview

This matrix shows all permissions in Agatabo, what actions they control, and which roles typically have them.

## Permission Format

**Format**: `resource:action`

**Example**: `savings:write` = permission to write (create/modify) savings records

**Scopes**:

* **SELF**: Access only own data
* **ANY**: Access all organization data

***

## Complete Permissions List

### Organization Users

| Permission                      | Scope | Description      | Actions Allowed                                       |
| ------------------------------- | ----- | ---------------- | ----------------------------------------------------- |
| `organization_users:read`       | SELF  | View own profile | See own name, email, phone, join date, roles          |
| `organization_users:read`       | ANY   | View all members | See member list, profiles, contact info, join dates   |
| `organization_users:write`      | ANY   | Manage members   | Invite, edit, deactivate members; update contact info |
| `organization_user_roles:write` | ANY   | Assign roles     | Grant/revoke roles and permissions to users           |

### Savings & Deposits

| Permission      | Scope | Description                 | Actions Allowed                                                  |
| --------------- | ----- | --------------------------- | ---------------------------------------------------------------- |
| `savings:read`  | SELF  | View own savings            | See own deposit history, current balance                         |
| `savings:read`  | ANY   | View all savings            | See all members' deposits, balances, transaction history         |
| `savings:write` | ANY   | Record deposits/withdrawals | Create deposits, process withdrawals, edit unposted transactions |

### Loans

| Permission    | Scope | Description          | Actions Allowed                                               |
| ------------- | ----- | -------------------- | ------------------------------------------------------------- |
| `loans:read`  | SELF  | View own loans       | See own loan details, installment schedules, payment history  |
| `loans:read`  | ANY   | View all loans       | See all members' loans, portfolio reports, delinquency status |
| `loans:write` | SELF  | Apply for loans      | Submit loan applications for self (if self-service enabled)   |
| `loans:write` | ANY   | Manage all loans     | Create, approve, modify, disburse loans for any member        |
| `loans:write` | ANY   | Record loan payments | Post payments against loans, allocate to principal/interest   |
| `loans:write` | ANY   | Apply penalties      | Add late fees and penalties to delinquent loans               |

### Expenses

| Permission       | Scope | Description       | Actions Allowed                                      |
| ---------------- | ----- | ----------------- | ---------------------------------------------------- |
| `expenses:read`  | SELF  | View own expenses | See expense claims submitted by self (if applicable) |
| `expenses:read`  | ANY   | View all expenses | See all organization expenses, categories, history   |
| `expenses:write` | ANY   | Record expenses   | Create expense records, categorize, attach receipts  |

### Fixed Assets

| Permission     | Scope | Description     | Actions Allowed                                 |
| -------------- | ----- | --------------- | ----------------------------------------------- |
| `assets:read`  | SELF  | View own assets | See assets associated with self (rare use case) |
| `assets:read`  | ANY   | View all assets | See asset register, acquisition details, values |
| `assets:write` | ANY   | Manage assets   | Add assets, update values, record disposals     |

### Reserves

| Permission       | Scope | Description           | Actions Allowed                                   |
| ---------------- | ----- | --------------------- | ------------------------------------------------- |
| `reserves:read`  | SELF  | View own reserve data | Limited use (reserves are organization-level)     |
| `reserves:read`  | ANY   | View reserves         | See reserve balances, allocation history          |
| `reserves:write` | ANY   | Manage reserves       | Create reserves, allocate (top-up), release funds |

### Dividends

| Permission        | Scope | Description        | Actions Allowed                                                     |
| ----------------- | ----- | ------------------ | ------------------------------------------------------------------- |
| `dividends:read`  | SELF  | View own dividends | See dividend amounts received, distribution history                 |
| `dividends:read`  | ANY   | View all dividends | See dividend pools, member allocations, distribution history        |
| `dividends:write` | ANY   | Manage dividends   | Create dividend pools, calculate distributions, mark as distributed |

### General Ledger & Accounting

| Permission     | Scope | Description              | Actions Allowed                                                       |
| -------------- | ----- | ------------------------ | --------------------------------------------------------------------- |
| `ledger:read`  | SELF  | View own ledger account  | See own savings account statement (member view)                       |
| `ledger:read`  | ANY   | View all ledger accounts | Access chart of accounts, account balances, statements, trial balance |
| `ledger:write` | ANY   | Post journal entries     | Create manual journal entries, post adjustments, corrections          |

### Reports

**Note**: Reports generally don't have specific permissions. Access depends on underlying data permissions.

**Examples**:

* Balance Sheet: Requires `ledger:read` (ANY)
* Loans Outstanding: Requires `loans:read` (ANY)
* Member savings statement: Requires `savings:read` (SELF or ANY)

### Settings & Administration

| Permission        | Scope | Description                | Actions Allowed                                           |
| ----------------- | ----- | -------------------------- | --------------------------------------------------------- |
| `settings:read`   | ANY   | View organization settings | See org name, currency, timezone, settings                |
| `settings:write`  | ANY   | Edit organization settings | Update org name, notification preferences, configurations |
| `settings:write`  | ANY   | Update rates & configs     | Modify interest rates, contribution schedules, policies   |
| `audit_logs:read` | ANY   | View audit trail           | Access complete activity log, filter by actor/action      |

***

## Common Role Mappings

<Warning>
  **Note on Roles**: The role mappings below are suggested configurations, not pre-defined system roles. Agatabo provides `admin` and `member` as protected default roles. Organizations create additional custom roles and assign permissions as needed to match their operational structure.
</Warning>

### Administrator (Full Access)

| Permission                      | Scope |
| ------------------------------- | ----- |
| `organization_users:read`       | ANY   |
| `organization_users:write`      | ANY   |
| `organization_user_roles:write` | ANY   |
| `savings:read`                  | ANY   |
| `savings:write`                 | ANY   |
| `loans:read`                    | ANY   |
| `loans:write`                   | ANY   |
| `loans:write`                   | ANY   |
| `loans:write`                   | ANY   |
| `expenses:read`                 | ANY   |
| `expenses:write`                | ANY   |
| `assets:read`                   | ANY   |
| `assets:write`                  | ANY   |
| `reserves:read`                 | ANY   |
| `reserves:write`                | ANY   |
| `dividends:read`                | ANY   |
| `dividends:write`               | ANY   |
| `ledger:read`                   | ANY   |
| `ledger:write`                  | ANY   |
| `settings:read`                 | ANY   |
| `settings:write`                | ANY   |
| `settings:write`                | ANY   |
| `audit_logs:read`               | ANY   |

**Can do**: Everything

***

### Treasurer

| Permission                | Scope |
| ------------------------- | ----- |
| `organization_users:read` | ANY   |
| `savings:read`            | ANY   |
| `savings:write`           | ANY   |
| `expenses:read`           | ANY   |
| `expenses:write`          | ANY   |
| `ledger:read`             | ANY   |

**Can do**: Record deposits, record expenses, view financial reports

**Cannot do**: Create loans, assign roles, change settings

***

### Loan Officer

| Permission                | Scope                      |
| ------------------------- | -------------------------- |
| `organization_users:read` | ANY                        |
| `savings:read`            | ANY (to check eligibility) |
| `loans:read`              | ANY                        |
| `loans:write`             | ANY                        |
| `loans:write`             | ANY                        |
| `loans:write`             | ANY                        |

**Can do**: Create/manage loans, record payments, apply penalties

**Cannot do**: Record deposits/expenses, post journal entries, assign roles

***

### Accountant

| Permission                | Scope                 |
| ------------------------- | --------------------- |
| `organization_users:read` | ANY                   |
| `savings:read`            | ANY                   |
| `loans:read`              | ANY                   |
| `expenses:read`           | ANY                   |
| `assets:read`             | ANY                   |
| `reserves:read`           | ANY                   |
| `dividends:read`          | ANY                   |
| `ledger:read`             | ANY                   |
| `ledger:write`            | ANY (for adjustments) |
| `audit_logs:read`         | ANY                   |

**Can do**: View all financial data, run reports, post adjusting entries, view audit trail

**Cannot do**: Record operational transactions (deposits, loans), assign roles, change settings

***

### Member (Basic)

| Permission                | Scope |
| ------------------------- | ----- |
| `organization_users:read` | SELF  |
| `savings:read`            | SELF  |
| `loans:read`              | SELF  |
| `ledger:read`             | SELF  |
| `dividends:read`          | SELF  |

**Can do**: View own savings, loans, account statement, dividends

**Cannot do**: View other members' data, record transactions, access settings

***

## Permission Inheritance

**Multiple roles**:

* If user has multiple roles, permissions are **cumulative** (union)
* Example: User with both Treasurer + Loan Officer can record deposits AND create loans

**Scope precedence**:

* If same permission granted with different scopes, **ANY scope wins**
* Example: User has `savings:read` SELF from Member role + `savings:read` ANY from Treasurer role = user gets ANY scope

***

## Special Cases

### Self-Service Loan Applications

* Member with `loans:write` (SELF scope) can submit loan applications
* Requires administrator to configure self-service feature
* Applications still need approval from loan committee

### Restricted Journal Entries

* `ledger:write` permission allows creating manual journal entries
* Some entry types may be restricted (e.g., closing entries) even with permission
* System prevents creating entries in closed periods regardless of permission

### Organization-Level Settings

* `settings:write` is powerful - grants ability to change currency, timezone, etc.
* Should only be given to trusted administrators
* Changes affect entire organization and all users

***

## Permission Checks in Agatabo

**Where permissions are checked**:

1. **UI**: Buttons/menus hidden if insufficient permission
2. **API**: Server validates permission before executing action
3. **Reports**: Filtered based on scope (SELF vs ANY)

**Error messages**:

* "You don't have permission to perform this action" = Missing permission entirely
* "You can only access your own data" = Have permission but with SELF scope, trying to access others' data

***

## Need Help?

<CardGroup cols={2}>
  <Card title="Understanding Permissions" icon="shield" href="/settings/permissions">
    Detailed permission guide
  </Card>

  <Card title="Member Roles" icon="users" href="/organization-users/roles">
    Managing roles
  </Card>
</CardGroup>