🇸🇩 سودانا — بوابة المطورين

1. Client → AI → Bank Flow

2. Payment Flow — Dual (Offline + Gateway)

Invoice Created (reference_code UNIQUE)
         │
    ┌────┴────┐
    │         │
OFFLINE    GATEWAY
    │         │
Transfer   Gateway
Bank Proof  Webhook
    │         │
Admin       Signature
Review       Verify
    │         │
    └────┬────┘
         │
FinancialAgent::confirmPayment()
  ├── 4 Ledger entries (DEBIT=CREDIT)
  ├── Wallet balance updated
  ├── Receipt generated (RCP-YYYYMMDD-NNNNNN)
  └── Email → finance@sudanna.ai
         │
EventBus("payment.confirmed")
  └── Queue → Worker → TaskEngine
        ├── notification to user
        └── kpi_daily updated

3. Decision Gate — AI Pipeline

Request (amount + user_id)
    │
    ├── RiskEngine.assess()     → risk_level: low/medium/high/critical
    ├── FraudGraph.check()      → is_fraud: true/false
    ├── SmartLimits.check()     → allowed: true/false
    └── CashFlowEngine.canAfford() → can_afford: true/false
                │
    MOST RESTRICTIVE WINS
                │
    ┌───────────┴───────────┐
  BLOCK                  ALLOW
(403)                  (200)
                          │
                    Execute Service

4. Reconciliation — Bank ↔ System ↔ Ledger

Daily at 2:30 AM (cron)
        │
ReconciliationEngine::run(date)
  ├── System: SELECT paid invoices WHERE DATE=?
  ├── Ledger: SUM(debit), SUM(credit) WHERE DATE=?
  └── Bank: BankAdapter::getStatement(from, to)
        │
  ┌─────┴─────┐
PASS         FAIL
  │           │
  ├── Log     ├── Alert Admin (notification)
  │           ├── BLOCK all payouts for date
  │           └── Log audit_logs (immutable)
  │
Settlement ALLOWED (3:00 AM)
  └── SettlementEngine::processDate(date)
        ├── ReconciliationEngine::isPassed(date) → GATE
        ├── provider_earnings WHERE status=pending
        ├── BankAdapter::initiatePayout()
        └── Ledger: DEBIT Provider(2002) CREDIT Cash(1001)

5. Accounting — Double-Entry Ledger

Payment Received (1000 SDG):
  DEBIT  Cash(1001)           1000  ← money enters
  CREDIT UserLiability(2001)  1000  ← owed to user
  DEBIT  UserLiability(2001)  1000  ← settling
  CREDIT UserWallet(1002)     1000  ← wallet funded
  ─────────────────────────────────
  SUM(debit) = 2000 = SUM(credit) ✅

Settlement Payout (900 SDG to provider):
  DEBIT  ProviderLiability(2002) 900 ← paying out
  CREDIT Cash(1001)              900 ← money leaves
  ─────────────────────────────────
  BALANCED ✅ — Sudanna never holds

6. Revenue Streams — All Through Ledger

Stream              Rate    Ledger Account    Trigger
────────────────────────────────────────────────────
Service Commission  10%     Revenue(4001)     booking.completed
Payment Fee         0.5%    Revenue(4001)     payment.confirmed
Subscription        Fixed   Revenue(4002)     subscription.paid
API Usage           /call   Revenue(4002)     api_engine.used
Provider Listing    Fixed   Revenue(4001)     listing_boost

ALL revenue:
  ✔ goes through ledger
  ✔ linked to invoice_id
  ✔ reconciled with bank
  ✔ auditable (trace_id)

7. Production API Endpoints

8. System Principles + SLA

Principle          Definition
──────────────────────────────────────────────────────
NO_CUSTODY         Sudanna never holds money (shadow ledger only)
DEBIT_ONLY         No credit/loans ever extended
BANK_SOURCE        Bank statement wins on any mismatch
IDEMPOTENT         Every operation safe to retry
EVENT_DRIVEN       All state changes via EventBus
AI_CONTROLLED      AI gates every payment decision
AUDITABLE          trace_id on every action, immutable logs

SLA
──────────────────────────────────────────────────────
Decision check     < 100ms
Webhook confirm    < 2s
Full payment       < 5s
Email dispatch     < 10s
Reconciliation     < 5min (daily)
Settlement         after reconciliation PASS