# Kashu POS — Entity Relationship Diagram

```mermaid
erDiagram
    agents ||--o{ agent_sessions : has
    agents ||--o{ float_logs : has
    agents ||--o{ transactions : performs
    agents ||--o{ commissions : earns
    agents ||--o{ products : owns
    agents ||--o{ orders : creates
    agents ||--o{ notifications : receives
    agents ||--o{ salary_batches : uploads

    transactions ||--o| airtime_sales : detail
    transactions ||--o| utility_payments : detail
    transactions ||--o| school_fee_payments : detail
    transactions ||--o| tax_payments : detail
    transactions ||--o| mobile_money_transactions : detail
    transactions ||--o| agent_banking : detail
    transactions ||--o| orders : settles
    transactions ||--o| commissions : generates
    transactions ||--o| salary_payments : settles

    orders ||--o{ order_items : contains
    products ||--o{ order_items : referenced_by

    salary_batches ||--o{ salary_payments : contains

    agents {
        bigint id PK
        string agent_code UK
        string full_name
        string email UK
        string phone UK
        string pin "bcrypt"
        string password "bcrypt"
        decimal float_balance
        decimal commission_balance
        enum status "active|suspended|pending"
        boolean is_verified
        timestamp deleted_at "soft delete"
    }

    transactions {
        bigint id PK
        bigint agent_id FK
        string transaction_ref UK "KSH-TXN-YYYYMMDD-XXXXXX"
        enum type
        string provider
        decimal amount
        decimal fee
        decimal commission
        decimal net_amount
        enum status "pending|processing|success|failed|reversed"
        string idempotency_key
        string receipt_number UK
    }

    float_logs {
        bigint id PK
        bigint agent_id FK
        enum type "topup|deduction|commission|reversal"
        decimal amount
        decimal balance_before
        decimal balance_after
        string reference UK
    }

    commissions {
        bigint id PK
        bigint agent_id FK
        bigint transaction_id FK
        string type
        decimal amount
        decimal rate
        enum status "pending|paid|cancelled"
    }

    commission_rates {
        bigint id PK
        string service_type UK
        decimal rate
        decimal flat_fee
        boolean is_active
    }

    mobile_money_transactions {
        bigint id PK
        bigint transaction_id FK
        bigint agent_id FK
        enum provider "MTN|Airtel|Mpesa"
        enum operation
        decimal amount
        string provider_ref
        json callback_data
        enum status
    }

    orders {
        bigint id PK
        bigint transaction_id FK
        bigint agent_id FK
        string order_ref UK
        decimal total
        decimal amount_paid
        decimal change_given
        enum payment_method
        enum status
    }

    salary_batches {
        bigint id PK
        bigint agent_id FK
        string batch_ref UK
        decimal total_amount
        int total_records
        enum status "draft|processing|completed|partial|failed"
    }
```

## Table summary (20 domain tables)

| Table | Purpose |
|-------|---------|
| `agents` | Agent accounts, float & commission balances, auth (soft delete) |
| `agent_sessions` | Device/session tracking for issued tokens |
| `float_logs` | Immutable ledger of every float movement |
| `transactions` | Parent record for every financial operation |
| `airtime_sales` | Airtime purchase detail |
| `utility_payments` | UMEME/NWSC/DStv etc., incl. electricity token + units |
| `school_fee_payments` | School fee detail |
| `tax_payments` | URA / PRN tax detail |
| `mobile_money_transactions` | MTN/Airtel/M-Pesa send/withdraw/receive detail |
| `agent_banking` | Bank deposit/withdraw/transfer detail |
| `products` | Agent POS catalogue (soft delete) |
| `orders` | POS checkout orders |
| `order_items` | Line items per order |
| `salary_batches` | Bulk salary disbursement batches |
| `salary_payments` | Individual salary payments |
| `commissions` | Commission earned per transaction |
| `commission_rates` | Configurable per-service rates |
| `audit_logs` | Audit trail of state-changing requests |
| `notifications` | In-app notifications |
| `system_settings` | Key/value app configuration |
```