diff --git a/README.md b/README.md new file mode 100644 index 0000000..b3e8a24 --- /dev/null +++ b/README.md @@ -0,0 +1,25 @@ +# WASL (وَصْل) Digital Wallet + +WASL is a bank-grade, secure P2P and merchant digital wallet platform tailored for Syria. + +## Tech Stack +- **Backend**: Laravel 11 + Laravel Octane (Swoole driver) +- **Mobile**: Flutter 3.x (Clean Architecture + BLoC/Cubit) +- **Database**: PostgreSQL 16 (with transaction audit ledgers) +- **Cache / Queue**: Redis 7 +- **Storage**: MinIO (S3-compatible secure private storage) +- **Deployment**: Docker Compose + +## Architectural Core Principles +- **ACID Compliance**: Ensuring complete database integrity for all financial mutation queries. +- **Double-Entry Ledger**: Every transaction produces exactly 2 balancing ledger entries (debit and credit). +- **Strict Minor Units**: All monetary values stored and processed as `BIGINT` minor units (e.g. SYP is stored as minor units to avoid floating-point inaccuracies). +- **Pessimistic Locking**: `SELECT ... FOR UPDATE` with deterministic resource locking order to prevent deadlocks. +- **Data Encryption**: AES-256 field-level encryption for sensitive PII (Phone number, National ID). +- **Audit Logging**: Immutable ledger tracking all authentication, registration, and transfer activities. + +## Directory Structure +- `Backend/`: The Laravel API and administrator control panel. +- `Mobile App/`: The Flutter application codebase. +- `wasl_concept.md`: Complete details of the 4 phase implementation prompts. +- `deploy.sh`: Shell script to stage, commit, and push changes to the repository. diff --git a/index.php b/index.php new file mode 100644 index 0000000..c746562 --- /dev/null +++ b/index.php @@ -0,0 +1,303 @@ + + + + + + وَصْل | المحفظة الرقمية الآمنة - WASL Wallet + + + + + + + + + + + +
+ + + المستودع البرمجي +
+ + +
+

المحفظة الرقمية الأكثر أماناً وموثوقية

+

بوابتك المالية المتكاملة للدفع الرقمي وخدمات النظير للنظير (P2P) في سوريا، مصممة بأعلى معايير الحماية وموثوقية المعاملات المالية.

+ استكشف مميزات وَصْل +
+ + +
+

لماذا محفظة وَصْل؟

+
+ +
+
🔒
+

أمان بمستوى بنكي

+

تشفير البيانات الحساسة وثنائية التحقق مع تتبع كامل وجرد فوري ومقاوم للاحتيال.

+
+ +
+
💸
+

تحويل فوري (P2P)

+

أرسل واستقبل الأموال فورياً برقم الهاتف، وبشكل فوري وبأقل عمولة ممكنة.

+
+ +
+
📊
+

قيد مزدوج (Double-Entry)

+

كل معاملة مالية تقيد بدقة لضمان توازن الحسابات والشفافية التامة في النظام المالي.

+
+
+
+ + + + + + diff --git a/wasl_concept.md b/wasl_concept.md new file mode 100644 index 0000000..b58191a --- /dev/null +++ b/wasl_concept.md @@ -0,0 +1,48 @@ +# 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.