# ABC Core Financial Core (Phase 3)

## Overview

The Financial Core is the heart of the banking platform. It consists of four engines and two services that handle all financial operations without exposing banking APIs.

## Components

### 1. Reference Generator (`app/Core/ReferenceGenerator.php`)

Generates unique, human-readable references for all banking entities.

**Supported Types:**
| Method | Prefix | Example |
|--------|--------|---------|
| `generateTransactionReference()` | TXN | TXN-20260702-A1B2C3D4 |
| `generateLedgerReference()` | LED | LED-20260702-E5F6G7H8 |
| `generateReceiptReference()` | RCP | RCP-20260702-I9J0K1L2 |
| `generateReceiptNumber()` | RNO | RNO-20260702-M3N4O5P6 |
| `generateLoanReference()` | LON | LON-20260702-Q7R8S9T0 |
| `generateCardReference()` | CRD | CRD-20260702-U1V2W3X4 |
| `generateNotificationReference()` | NOT | NOT-20260702-Y5Z6A7B8 |
| `generateAuditReference()` | AUD | AUD-20260702-C9D0E1F2 |

**Features:**
- Collision-checked against `ref_registry` table
- Configurable via `app/Config/references.php` (future)
- Stores all generated references for auditability

---

### 2. Balance Engine (`app/Core/BalanceEngine.php`)

The ONLY component allowed to calculate and update account balances.

**Methods:**
| Method | Purpose |
|--------|---------|
| `calculateBalance($accountUuid)` | Sum all CR minus DR from ledger_entries |
| `getAvailableBalance($accountUuid)` | Alias for calculateBalance (holds not implemented) |
| `getLedgerBalance($accountUuid)` | Alias for calculateBalance |
| `rebuildBalance($accountUuid)` | Recalculate and write to accounts.balance |
| `verifyBalance($accountUuid)` | Compare stored vs calculated balance |
| `updateBalance($accountUuid)` | Convenience wrapper for rebuildBalance |

**Principles:**
- No service other than BalanceEngine may update `accounts.balance`
- All balances are derived from `ledger_entries` table
- The Accounts module NEVER calculates balances

---

### 3. Ledger Engine (`app/Core/Ledger.php`)

The ONLY component allowed to create ledger entries.

**Methods:**
| Method | Purpose |
|--------|---------|
| `recordEntry(...)` | Record a single ledger entry with opening/closing balance |
| `recordDoubleEntry(...)` | Record a debit + credit pair for a transaction |
| `reverseEntry(...)` | Create a reversal entry and mark original as REVERSED |
| `verifyDoubleEntry($transactionUuid)` | Verify total DR = total CR for a transaction |
| `getEntriesByTransaction(...)` | Get all ledger entries for a transaction |
| `getEntriesByAccount(...)` | Get all ledger entries for an account |
| `updateBalances(...)` | Update balances for multiple accounts after entries |

**Ledger Entry Fields:**
- UUID, Reference, Transaction UUID, Account UUID
- Amount, Currency, Entry Type, DR/CR Indicator
- Opening Balance, Closing Balance
- Description, Status (POSTED/REVERSED)
- Created By, Created At, Audit Reference

**Principles:**
- All entries are immutable (status only changes to REVERSED)
- Every entry records opening and closing balance for full auditability
- Double-entry verification runs before every transaction commit
- Events dispatched but never interrupt financial processing

---

### 4. Transaction Engine (`app/Modules/Transactions/Services/TransactionService.php`)

Orchestrates all financial transactions through the Ledger.

**Supported Transaction Types:**
| Method | Type | Direction |
|--------|------|-----------|
| `createDeposit()` | DEPOSIT | CR single account |
| `createWithdrawal()` | WITHDRAWAL | DR single account |
| `createTransfer()` | TRANSFER | DR from, CR to |
| `createFee()` | FEE | DR single account |
| `createInterest()` | INTEREST | CR single account |
| `createAdjustment()` | ADJUSTMENT | DR or CR single account |
| `createLoanDisbursement()` | LOAN_DISBURSEMENT | CR single account |
| `createLoanRepayment()` | LOAN_REPAYMENT | DR single account |
| `createCardPayment()` | CARD_PAYMENT | DR single account |
| `createRefund()` | REFUND | CR single account |
| `createReversal()` | REVERSAL | Reverse all entries of original transaction |

**Transaction Lifecycle:**
1. Validate via `FinancialValidationService`
2. Create transaction record (status = PENDING)
3. Create ledger entries via `Ledger::recordEntry()` or `recordDoubleEntry()`
4. Verify double-entry (`Ledger::verifyDoubleEntry()`)
5. Update balances (`BalanceEngine::updateBalance()`)
6. Mark transaction as COMPLETED
7. Create receipt via `ReceiptService`
8. Dispatch events (failure is logged, not thrown)
9. Audit log (failure is logged, not thrown)

**No APIs are exposed** in Phase 3. These methods are called internally by future banking modules.

---

### 5. Financial Validation Service (`app/Modules/Financial/Services/FinancialValidationService.php`)

Validates all financial operations BEFORE money is moved.

**Validation Rules:**
| Rule | Description |
|------|-------------|
| Amount | Positive, non-zero, max 999,999,999,999.99, max 2 decimals |
| Currency | Must be supported (Currencies constant) |
| Account Status | Must be ACTIVE for debits; not CLOSED for credits |
| Currency Match | Account currency must match transaction currency |
| Daily Limit | Daily DR total must not exceed account daily limit |
| Sufficient Balance | Debit operations require sufficient ledger balance |
| Transaction Type | Must be valid (TransactionTypes constant) |

**Principles:**
- Validation ONLY. No money movement.
- Throws `ValidationException` with field-level errors.
- Called by `TransactionService` before every transaction.

---

### 6. Receipt Foundation Service (`app/Modules/Financial/Services/ReceiptService.php`)

Creates and manages receipt records.

**Features:**
- Receipt UUID, Reference, Receipt Number (all unique)
- Linked to Transaction UUID
- Status: PENDING (PDF generation in Phase 4+)
- Audit logging for every receipt action

**No PDF generation in Phase 3.**

---

## Database Schema

### `ledger_entries`
Immutable records of every financial movement.

### `transactions`
Business-level transaction metadata.

### `transaction_metadata`
Key-value pairs linked to transactions.

### `receipts`
Receipt records (PDF generation pending).

### `ref_registry`
Reference registry for collision avoidance.

See migration files for full schema.

---

## Financial Events

| Event | Dispatched When |
|-------|----------------|
| `LedgerEntryCreated` | After every ledger entry is created |
| `TransactionCreated` | After a transaction is completed |
| `BalanceUpdated` | After account balances are updated |
| `TransactionReversed` | After a transaction is reversed |
| `ReceiptCreated` | After a receipt record is created |

All events are dispatched asynchronously (failure is logged, not thrown).

---

## Architecture Principles

1. **Ledger First** — Every financial movement creates ledger entries.
2. **Balance Engine Only** — Only `BalanceEngine` updates `accounts.balance`.
3. **Double-Entry** — Every transaction has at least two entries (DR + CR).
4. **Immutable Ledger** — Entries are never deleted; reversals create new entries.
5. **Validation Before Movement** — `FinancialValidationService` validates before any money moves.
6. **No API Exposure** — No transfer/deposit/withdrawal endpoints in Phase 3.
7. **Events Never Interrupt** — Event failures are logged, never thrown.
8. **Audit Every Action** — All significant actions create audit logs.

---

## Integration Flow

```
Future Controller (Phase 4)
  ↓
TransactionService::createTransfer()
  ↓
FinancialValidationService::validateTransaction()
  ↓
TransactionRepository::create()
  ↓
Ledger::recordDoubleEntry()
  ↓
Ledger::verifyDoubleEntry()
  ↓
BalanceEngine::updateBalance()
  ↓
ReceiptService::create()
  ↓
AuditService::log()
  ↓
EventDispatcher::dispatch()
```

---

## Next Phase (Phase 4)

Phase 4 will expose banking APIs:
- Transfer API
- Deposit API
- Withdrawal API
- Loan API
- Card API
- Notification API
- Statement generation
- Receipt PDF generation