49 lines
2.4 KiB
Markdown
49 lines
2.4 KiB
Markdown
# 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.
|