# 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.