wasl/wasl_concept.md

WASL Digital Wallet — Core Reference Document & Prompts

This document contains the core principles, architecture definitions, and reference prompts for the 4 implementation phases of WASL (وَصْل).

---

Core Principles (Non-Negotiable)

1. ACID Compliance: Enforced on all financial operations.
2. BIGINT Minor Units Only: No float, no decimal for money.
3. Idempotency: Enforced on all mutation endpoints (client-supplied UUID keys).
4. Double-Entry Bookkeeping: Every balance change produces exactly 2 ledger entries (debit + credit).
5. Audit Trail: Every sensitive action logged (who, what, when, where, IP, device).
6. Pessimistic Locking: SELECT ... FOR UPDATE on wallet balance updates.
7. AES-256 Encryption: Encrypt PII (phone, national_id, card numbers).
8. 6-Layer Security: User → App → Transport → Edge → Backend → Database.

---

Implementation Phases

Phase 1: Foundation & Authentication

• Initialize Laravel 11 + Octane (Swoole).
• Migrations: users, wallets, transactions, transaction_entries, user_devices, otp_codes, audit_logs, kyc_documents, fraud_alerts.
• Authentication flow: OTP registration/verification, argon2id PIN setup, JWT access tokens (RS256/custom).
• AuditService & EncryptionService implementations.
• Flutter structure (Clean Architecture, BLoC/Cubit, flutter_secure_storage, dio interceptors).

Phase 2: Wallet & Transactions

• WalletService: balance checks, limit checking, freezing.
• LedgerService: debit/credit ledger entries.
• TransferService: idempotent money transfers, pessimistic locking with ordering.
• Reconciliation Job: daily balance check verifying sum(entries) == wallet.balance_minor.
• Flutter Wallet UI & Transfer Flow.

Phase 3: Merchants & QR Payments

• Merchant and QR database schema.
• Signed base64 QR code payload validation.
• MerchantPaymentService: commission calculations, platform fee logic.
• Settlement Engine: daily batch settlements.
• Flutter scanner & Merchant dashboard.

Phase 4: KYC, Advanced Security & Launch

• 3-tier KYC system (Phone → ID → Selfie + Manual Review).
• Fraud Detection Engine (rules engine evaluating rapid transfers, new devices, transaction sizes).
• Device fingerprinting and MFA for sensitive actions.
• Performance optimization (e.g. eager loading, caching, pg_stat_statements).
• k6 load testing scripts.
• Flutter UI polish, accessibility, offline support.