dbis_core/docs/accounting/CHART_OF_ACCOUNTS.md

# General Ledger Chart of Accounts

**Status:** ✅ **Deployable and Ready**

---

## Overview

The DBIS Core system includes a comprehensive General Ledger Chart of Accounts that is compliant with both **USGAAP** (US Generally Accepted Accounting Principles) and **IFRS** (International Financial Reporting Standards).

---

## Account Structure

### Account Categories

| Code Range | Category | Normal Balance | Description |
|------------|----------|----------------|-------------|
| **1000-1999** | Assets | DEBIT | Resources owned by the entity |
| **2000-2999** | Liabilities | CREDIT | Obligations owed by the entity |
| **3000-3999** | Equity | CREDIT | Owner's equity and reserves |
| **4000-4999** | Revenue | CREDIT | Income and gains |
| **5000-6999** | Expenses | DEBIT | Costs and losses |
| **7000-9999** | Other | Varies | Special purpose accounts |

---

## Account Hierarchy

### Level 1: Main Categories
- `1000` - ASSETS
- `2000` - LIABILITIES
- `3000` - EQUITY
- `4000` - REVENUE
- `5000` - EXPENSES

### Level 2: Sub-Categories
- `1100` - Current Assets
- `1200` - Non-Current Assets
- `2100` - Current Liabilities
- `2200` - Non-Current Liabilities
- `3100` - Capital
- `3200` - Retained Earnings
- `3300` - Reserves
- `4100` - Operating Revenue
- `4200` - Non-Operating Revenue
- `5100` - Operating Expenses
- `5200` - Non-Operating Expenses

### Level 3+: Detail Accounts
- `1110` - Cash and Cash Equivalents
- `1111` - Cash on Hand
- `1112` - Cash in Banks
- `1120` - Accounts Receivable
- `1130` - Settlement Assets
- `1140` - CBDC Holdings
- `1150` - GRU Holdings
- etc.

---

## USGAAP Compliance

### Classification Mapping

| Account | USGAAP Classification |
|---------|----------------------|
| `1110` | Cash and Cash Equivalents |
| `1120` | Trade Receivables |
| `1122` | Allowance for Doubtful Accounts |
| `1210` | Property, Plant and Equipment |
| `1211` | Accumulated Depreciation |
| `2110` | Accounts Payable |
| `2120` | Short-term Debt |
| `2210` | Long-term Debt |
| `3100` | Stockholders Equity |
| `3200` | Retained Earnings |
| `4110` | Interest Income |
| `5110` | Interest Expense |
| `5160` | Provision for Credit Losses |

---

## IFRS Compliance

### Classification Mapping

| Account | IFRS Classification |
|---------|---------------------|
| `1110` | Cash and Cash Equivalents |
| `1120` | Trade Receivables |
| `1122` | Impairment of Receivables |
| `1210` | Property, Plant and Equipment |
| `1211` | Accumulated Depreciation |
| `2110` | Trade Payables |
| `2120` | Financial Liabilities |
| `2210` | Financial Liabilities |
| `3100` | Share Capital |
| `3200` | Retained Earnings |
| `3300` | Reserves |
| `4110` | Interest Income |
| `5110` | Finance Costs |
| `5160` | Expected Credit Losses |

---

## Key Features

### ✅ Implemented

1. **Hierarchical Structure**
   - Parent-child relationships
   - Multi-level account hierarchy
   - Tree navigation support

2. **Dual Standard Support**
   - USGAAP classifications
   - IFRS classifications
   - Both standards supported simultaneously

3. **Account Coding**
   - 4-digit account codes
   - Logical numbering system
   - Extensible structure

4. **Normal Balance Tracking**
   - DEBIT accounts (Assets, Expenses)
   - CREDIT accounts (Liabilities, Equity, Revenue)
   - Automatic validation

5. **System Accounts**
   - Pre-defined system accounts
   - Custom account creation
   - Active/inactive status

---

## Deployment

### Step 1: Add Prisma Model

The `ChartOfAccount` model has been added to the Prisma schema.

### Step 2: Run Migration

```bash
cd dbis_core
npx prisma migrate dev --name add_chart_of_accounts
```

Or manually run the SQL migration:
```bash
psql -d dbis_core -f prisma/migrations/add_chart_of_accounts.sql
```

### Step 3: Initialize Chart of Accounts

```typescript
import { chartOfAccountsService } from '@/core/accounting/chart-of-accounts.service';

// Initialize standard accounts
await chartOfAccountsService.initializeChartOfAccounts();
```

Or via API:
```bash
POST /api/accounting/chart-of-accounts/initialize
```

### Step 4: Verify

```typescript
// Get all accounts
const accounts = await chartOfAccountsService.getChartOfAccounts();

// Get by category
const assets = await chartOfAccountsService.getAccountsByCategory(AccountCategory.ASSET);

// Get hierarchy
const assetHierarchy = await chartOfAccountsService.getAccountHierarchy('1000');
```

---

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/accounting/chart-of-accounts` | Get all accounts |
| `POST` | `/api/accounting/chart-of-accounts/initialize` | Initialize standard accounts |
| `GET` | `/api/accounting/chart-of-accounts/:accountCode` | Get account by code |
| `GET` | `/api/accounting/chart-of-accounts/category/:category` | Get by category |
| `GET` | `/api/accounting/chart-of-accounts/:parentCode/children` | Get child accounts |
| `GET` | `/api/accounting/chart-of-accounts/:rootCode/hierarchy` | Get account hierarchy |
| `POST` | `/api/accounting/chart-of-accounts` | Create new account |
| `PUT` | `/api/accounting/chart-of-accounts/:accountCode` | Update account |
| `GET` | `/api/accounting/chart-of-accounts/:accountCode/balance` | Get account balance |

---

## Account Examples

### Assets

```typescript
{
  accountCode: '1110',
  accountName: 'Cash and Cash Equivalents',
  category: 'ASSET',
  normalBalance: 'DEBIT',
  usgaapClassification: 'Cash and Cash Equivalents',
  ifrsClassification: 'Cash and Cash Equivalents',
  level: 3
}
```

### Liabilities

```typescript
{
  accountCode: '2140',
  accountName: 'CBDC Liabilities',
  category: 'LIABILITY',
  normalBalance: 'CREDIT',
  usgaapClassification: 'Digital Currency Liabilities',
  ifrsClassification: 'Financial Liabilities',
  level: 3
}
```

### Revenue

```typescript
{
  accountCode: '4110',
  accountName: 'Interest Income',
  category: 'REVENUE',
  normalBalance: 'CREDIT',
  usgaapClassification: 'Interest Income',
  ifrsClassification: 'Interest Income',
  level: 3
}
```

---

## Integration with Ledger

The Chart of Accounts integrates with the existing ledger system:

```typescript
// Post entry using chart of accounts
await ledgerService.postDoubleEntry(
  ledgerId,
  '1112', // Cash in Banks (from chart of accounts)
  '4110', // Interest Income (from chart of accounts)
  amount,
  currencyCode,
  assetType,
  transactionType,
  referenceId
);
```

---

## Compliance Features

### USGAAP Features
- ✅ Standard account classifications
- ✅ Depreciation methods
- ✅ Allowance for doubtful accounts
- ✅ Provision for credit losses
- ✅ Stockholders equity structure

### IFRS Features
- ✅ IFRS-compliant classifications
- ✅ Revaluation reserves
- ✅ Expected credit losses (IFRS 9)
- ✅ Share capital structure
- ✅ Comprehensive income tracking

---

## Files Created

1. ✅ `src/core/accounting/chart-of-accounts.service.ts` - Service implementation
2. ✅ `src/core/accounting/chart-of-accounts.routes.ts` - API routes
3. ✅ `prisma/migrations/add_chart_of_accounts.sql` - Database migration
4. ✅ Prisma schema updated with `ChartOfAccount` model

---

## Next Steps

1. **Run Migration:**
   ```bash
   npx prisma migrate dev --name add_chart_of_accounts
   ```

2. **Initialize Accounts:**
   ```bash
   # Via API or service
   POST /api/accounting/chart-of-accounts/initialize
   ```

3. **Link to Ledger:**
   - Update ledger service to use chart of accounts
   - Map bank accounts to chart of accounts codes
   - Generate financial statements using chart of accounts

4. **Generate Reports:**
   - Balance Sheet (Assets = Liabilities + Equity)
   - Income Statement (Revenue - Expenses = Net Income)
   - Statement of Cash Flows
   - Statement of Changes in Equity

---

## Status

✅ **Chart of Accounts is deployable and ready for use!**

The system includes:
- ✅ Complete account structure
- ✅ USGAAP compliance
- ✅ IFRS compliance
- ✅ Hierarchical organization
- ✅ API endpoints
- ✅ Database schema
- ✅ Service implementation

---

**Ready for deployment and integration with the General Ledger system.**