# Business Requirement vs Implementation Gap Analysis

**Date:** 2026-03-26
**Scope:** Business Requirements (docs/business_requirement.txt) vs Phase 1–10A Implementation
**Status Key:** DONE = fully covered | PARTIAL = foundation exists, gaps remain | GAP = not yet implemented

---

## Summary

| # | Business Requirement Area | Coverage | Phase(s) |
|---|---|---|---|
| 1 | Wallet Onboarding | PARTIAL | 3, 9A-DB, 9B |
| 2 | Funding & Re-loading | PARTIAL | 3, 4, 6 |
| 3 | Beneficiary | PARTIAL | 9B |
| 4 | Request Money | GAP | — |
| 5 | Card Linking | PARTIAL | 10A |
| 6 | Authentication | PARTIAL | 2, 9A |
| 7 | Withdrawals & Transfers | PARTIAL | 3, 4, 6, 9B |
| 8 | Refunds and Returns | PARTIAL | 3 |
| 9 | Account Management | PARTIAL | 3, 9B |
| 10 | Language, Support & Chatbot | GAP | — |
| 11 | Reward & Offers | PARTIAL | 10A |
| 12 | Reconciliation | PARTIAL | 3, 5 |
| 13 | Reporting | GAP | — |
| 14 | Value-Added Services (VAS) | GAP | — |
| 15 | Lending Engine | GAP | Planned 10B |
| 16 | Investment | GAP | — |
| 17 | Notification | PARTIAL | 5 |
| 18 | Acquiring & Merchant Services | GAP | — |
| 19 | Admin Portal | PARTIAL | 9A–9D, 10A |
| 20 | Inward Remittance | GAP | — |

**Overall: 0 DONE | 11 PARTIAL | 9 GAP**

---

## Detailed Requirement-by-Requirement Analysis

### 1. Wallet Onboarding

| Requirement | Status | Implementation | Gap |
|---|---|---|---|
| Wallet application via branch and digital channels | PARTIAL | OnboardingLive (5-step) in Phase 9B | Branch channel integration not implemented; only web channel exists |
| Support KYC-ed customer wallet creation | PARTIAL | wallet_accounts OpenWalletAccount + KycLive for document upload | No integration with external AFEX KYC system; KYC state machine local only |
| Wallet lifecycle states (Pending, Active, Suspended, Frozen, Closed) | PARTIAL | Account has open/frozen/unfrozen states | Missing: Pending, Suspended, Closed states. Current states are simpler than required |
| Centralized customer master data (AFEX, AlfaPay, wallet) | GAP | — | No cross-system profile sync or centralized customer master |
| Real-time sync of customer details from AFEX | GAP | — | No AFEX system integration or event-based profile sync |
| Unique wallet account number | PARTIAL | AccountStore generates IDs | ID format may not meet AFEX account numbering standard |
| Virtual IBAN for funding and settlements | GAP | — | No IBAN generation or banking-system IBAN integration |
| Light KYC onboarding | PARTIAL | KycLive with document upload form | No tiered KYC (Light vs Full) distinction; no external KYC provider integration |

### 2. Funding & Re-loading Wallet

| Requirement | Status | Implementation | Gap |
|---|---|---|---|
| Balance funding through Lean/Checkout/AANI/AFEX Cards/Cash-in | GAP | StripeAdapter (sandbox) in wallet_integrations | No Lean, Checkout, AANI, AFEX Prepaid Card, or branch cash-in adapters |
| Auto-debit for wallet load (periodic/balance-based) | GAP | — | No scheduled auto-debit or balance-trigger mechanism |
| Instant balance update after successful load | PARTIAL | PostingEngine in wallet_ledger provides atomic credit | No real-time funding flow wired end-to-end |
| Configurable transaction and balance limits | DONE | wallet_limits_fees PolicyEngine with tier/currency/type limits | Limit policies exist; UI for admin configuration exists (PoliciesLive) |
| WPS salary credit integration | GAP | — | No WPS adapter or salary credit workflow |

### 3. Beneficiary

| Requirement | Status | Implementation | Gap |
|---|---|---|---|
| Add and delete beneficiary | PARTIAL | BeneficiariesLive with add/remove + confirm modal | Beneficiary store is ETS-only; no persistence layer |
| View existing beneficiary details | PARTIAL | BeneficiariesLive lists beneficiaries | Basic list view only |
| Validate via phone number or QR code | GAP | — | No phone-number lookup or QR code scanning |
| Validate beneficiary account after phone/QR entry | GAP | — | No external account validation service |

### 4. Request Money

| Requirement | Status | Implementation | Gap |
|---|---|---|---|
| P2P request money via phone number | GAP | — | No payment request initiation flow |
| Approve incoming payment request | GAP | — | No payment request approval/decline workflow |
| Generate QR code for receiving money | GAP | — | No QR code generation |

### 5. Card Linking

| Requirement | Status | Implementation | Gap |
|---|---|---|---|
| Link existing AFEX Prepaid/Payroll cards | PARTIAL | wallet_cards LinkedCardStore + LinkExternalCard command | Linking is UI-only; no real card system integration (tokenization, BIN validation) |
| Real-time balance sync between card and wallet | GAP | — | No balance sync mechanism between card issuer and wallet |
| AANI linking for funding and transfers | GAP | — | No AANI adapter |

### 6. Authentication

| Requirement | Status | Implementation | Gap |
|---|---|---|---|
| 6-digit wallet PIN creation during onboarding | GAP | wallet_auth uses PBKDF2 password; no PIN-specific flow | No PIN creation during onboarding; no 6-digit PIN abstraction |
| Biometric authentication (fingerprint/face) | GAP | — | No native biometric integration (requires mobile SDK) |
| In-app push notification for ecomm payment authorization | GAP | — | No push-based payment authorization flow |
| PIN for transaction authorization | GAP | — | PIN-based transaction auth not implemented; current system uses JWT bearer |
| PIN management (reset, change, recover via OTP) | PARTIAL | ResetCardPin command exists; OTP challenge service exists | No wallet-wide PIN reset/change flow; card PIN and wallet PIN are separate concerns |
| PIN complexity, retry limits, lockout | PARTIAL | Rate limiter with login/OTP buckets in wallet_auth | No PIN-specific complexity rules or lockout policy |
| Step-up OTP + PIN/biometric for high-value transactions | PARTIAL | MFA policy in wallet_auth + @mfa_required_actions in Policy | MFA check exists in policy but step-up flow is not wired in customer UX |
| Geo-fencing / location controls | GAP | — | No location-based access control |

### 7. Withdrawals & Transfers

| Requirement | Status | Implementation | Gap |
|---|---|---|---|
| Wallet-to-wallet (P2P) via phone/QR | PARTIAL | wallet_transfers state machine + TransferLive 3-step UI | Transfer uses account IDs, not phone/QR lookup; no QR code support |
| Wallet-to-bank (P2A) via IBAN/account number | GAP | — | No bank transfer adapter or IBAN routing |
| Wallet-to-merchant via phone/QR | GAP | — | No merchant payment flow |
| Split payment | GAP | — | No split payment orchestration |
| Cross-wallet transfer | PARTIAL | wallet_transfers supports internal transfers | Cross-wallet concept exists implicitly; no multi-currency FX conversion |
| Wallet as payment method (remittance, bill pay, VAS) | PARTIAL | BillPaymentLive (3-step biller catalog) in Phase 9B | Bill payment is UI shell only; no actual biller integration |
| Cash withdrawal from branches | GAP | — | No branch cash-out workflow |
| ATM withdrawal via linked card | GAP | — | No ATM integration |

### 8. Refunds and Returns

| Requirement | Status | Implementation | Gap |
|---|---|---|---|
| Instant reversals for failed transactions | PARTIAL | ReversePosting command in wallet_ledger | Reversal exists at ledger level; no automated trigger from failed external transactions |
| Partial and full refund workflows | GAP | — | Only full reversal exists; no partial refund support; no admin refund workflow |

### 9. Account Management

| Requirement | Status | Implementation | Gap |
|---|---|---|---|
| View balance | DONE | DashboardLive shows account balance cards | |
| View and download statement (PDF/CSV) | PARTIAL | StatementsLive with format selection | UI form exists; actual PDF/CSV generation engine not implemented |
| Filter transactions | DONE | TransactionsLive with status/type filters and search | |
| Mini statement | PARTIAL | DashboardLive shows recent transfers | Not a distinct mini-statement feature |
| Individual transaction details | PARTIAL | TransactionsLive drill-down via push_patch | Basic detail view; not full receipt/detail page |
| Freeze/Unfreeze wallet | PARTIAL | FreezeWalletAccount / UnfreezeWalletAccount in wallet_accounts | Command exists; no customer-facing self-service freeze/unfreeze UX |
| Deactivate wallet | GAP | — | No wallet deactivation / closure workflow |
| Universal customer details across AlfaPay | GAP | — | No cross-system profile synchronization |

### 10. Language, Support & Chatbot

| Requirement | Status | Implementation | Gap |
|---|---|---|---|
| English, Arabic, and other languages | GAP | — | No i18n / Gettext setup; all UI is English-only |
| In-app FAQ, help section, chatbot | GAP | — | No help/FAQ section or chatbot integration |
| Multilingual support tools (5+ languages) | GAP | — | No language framework |
| Dispute raise and track | GAP | — | No dispute lifecycle or tracking system |
| Dispute management with SLA monitoring | GAP | — | No dispute engine or SLA enforcement |

### 11. Reward & Offers

| Requirement | Status | Implementation | Gap |
|---|---|---|---|
| Loyalty points for transactions | PARTIAL | wallet_rewards PointsBalance + RewardTransaction | Points exist but are not auto-earned from wallet transactions; earn is manual/seeded |
| Loyalty points for referral + referral tracking | GAP | — | No referral system or tracking |
| Redemption with configurable rules | PARTIAL | RedeemPoints command checks offer status + balance | Redemption rules are basic (points >= cost); no configurable admin rule engine |
| Real-time points balance updates | DONE | PointsStore + OffersLive/RewardsLive reflect balance changes | |
| Campaigns and promotions | PARTIAL | OfferStore with create/expire lifecycle | Offers are basic catalog items; no campaign targeting, segmentation, or scheduling |

### 12. Reconciliation

| Requirement | Status | Implementation | Gap |
|---|---|---|---|
| Real-time debit/credit updates | DONE | PostingEngine provides atomic balance updates | |
| General Ledger & Accounting | PARTIAL | wallet_ledger double-entry journal + entries | No GL integration with external AFEX core system |
| GL postings to AFEX core system | GAP | — | No CBS/core banking GL adapter |
| Card + wallet balance GL sync | GAP | — | No card-system balance reconciliation |
| Settlement engine | PARTIAL | wallet_settlement SettlementBatch lifecycle + ReconciliationRun | Settlement engine exists but is internal; no external clearinghouse integration |

### 13. Reporting

| Requirement | Status | Implementation | Gap |
|---|---|---|---|
| Real-time dashboards for KPIs (activations, DAU/MAU, etc.) | GAP | — | No analytics dashboard or KPI tracking |
| Usage, balance and settlement reports | GAP | — | No report generation engine |
| DIFF file for WPS account usage | GAP | — | No WPS integration |
| Dispute reports | GAP | — | No dispute system |
| Regulatory reports per CBUAE guidelines | GAP | — | No regulatory report templates or generation |

### 14. Value-Added Services (VAS)

| Requirement | Status | Implementation | Gap |
|---|---|---|---|
| Goal-based saving | GAP | — | No savings goal feature |
| Micro saving | GAP | — | No micro-saving mechanism |
| Expense categorization and tracker | GAP | — | No transaction categorization |
| Budget tracking | GAP | — | No budget/spending limit tracking |
| AI-driven personal finance tools | GAP | — | No AI/ML integration |
| Micro-insurance premium collection | GAP | — | No insurance integration |
| IoT device linking | GAP | — | No IoT support |
| SME expense wallets | GAP | — | No multi-wallet / sub-wallet support |
| Customer analytics | GAP | — | No analytics engine |

### 15. Lending Engine

| Requirement | Status | Implementation | Gap |
|---|---|---|---|
| Digital loan origination, approval, disbursement | GAP | — | Planned for Phase 10B; not yet started |
| Salary Advance | GAP | — | No salary advance workflow |
| Buy Now Pay Later (BNPL) | GAP | — | No BNPL engine |

### 16. Investment

| Requirement | Status | Implementation | Gap |
|---|---|---|---|
| Integration with licensed investment providers | GAP | — | No investment provider adapter or integration |

### 17. Notification

| Requirement | Status | Implementation | Gap |
|---|---|---|---|
| Push, SMS, email triggers for transactions | PARTIAL | wallet_notifications with StubAdapter; NotificationsLive for preference management | Notification domain exists but delivery adapters are stubs; no real push/SMS/email integration |
| Configurable notification templates | PARTIAL | Notification struct has template-like fields | No admin template editor or dynamic template system |

### 18. Acquiring & Merchant Services

| Requirement | Status | Implementation | Gap |
|---|---|---|---|
| Merchant acquisition and onboarding | GAP | — | No merchant onboarding workflow |
| POS/SoftPOS/QR payment acceptance | GAP | — | No merchant terminal or QR payment processing |
| Wallet as payment option at merchant points | GAP | — | No merchant payment acceptance SDK |

### 19. Admin Portal

| Requirement | Status | Implementation | Gap |
|---|---|---|---|
| Role-based access control | DONE | ABAC-hybrid policy (7 roles, 46+ actions), RequireRole plug | Full RBAC + attribute-based access |
| Customer search and profile view | DONE | UserSearchLive with account/KYC listing | |
| Reset PINs, unlock accounts, suspend wallets | PARTIAL | Admin BlockCard/UnblockCard; ServiceControlsLive | No admin PIN reset for wallet PIN; no wallet suspend/close admin action |
| Customer status tracking | PARTIAL | UserSearchLive shows account + KYC status | Limited to account lifecycle states + KYC status |
| Real-time transaction visibility | DONE | TransactionInquiryLive with status/type filters | |
| Advanced filters (customer, date, amount, corridor, service) | PARTIAL | TransactionInquiryLive has status/type/reference filters | Missing: date range, amount range, corridor, service type filters |
| Refund/reversal management with audit trail | GAP | — | No admin refund/reversal workflow |
| Custom report builder (CSV, Excel, PDF export) | GAP | — | No report builder or export engine |
| Fee and limit configuration | PARTIAL | PoliciesLive; PolicyStore with UpsertLimitPolicy/UpsertFeePolicy | Admin UI for policy management exists; limited to basic form |
| Rule-based usage controls | PARTIAL | wallet_limits_fees PolicyEngine evaluates limits per transaction | Rules are static (tier/currency/type); no dynamic rule builder |
| Risk management (block, rules, audit trail) | PARTIAL | CardSearchLive block/unblock; AuditLogLive; wallet_risk ScoringEngine | Risk rules are static scoring; no dynamic rule configuration UI |

### 20. Inward Remittance

| Requirement | Status | Implementation | Gap |
|---|---|---|---|
| Wallet as inward remittance channel | GAP | — | No remittance receipt workflow |
| Credit remittance to wallet balance | GAP | — | No inbound remittance adapter |
| Transaction details (sender, country, amount) | GAP | — | No remittance metadata model |
| Notifications and receipts | GAP | — | Notification infra exists but not wired for remittance |

---

## Gap Priority Matrix

### Critical Gaps (Core wallet operations not yet functional end-to-end)

| # | Gap | Business Impact | Suggested Phase |
|---|---|---|---|
| 1 | No real payment adapter (Lean/Checkout/AANI/AFEX cards) | Cannot fund wallets | Next (Integration) |
| 2 | No PIN-based authentication (6-digit wallet PIN) | Cannot authorize transactions per requirement | Next (Auth enhancement) |
| 3 | No P2P transfer via phone number / QR code | Core transfer flow incomplete | Next (Transfer enhancement) |
| 4 | No bank transfer (P2A) via IBAN | Cannot withdraw to bank | Next (Integration) |
| 5 | No Virtual IBAN | Cannot receive external funds | Next (Integration) |
| 6 | No wallet lifecycle states (Pending/Suspended/Closed) | Incomplete account lifecycle | Next (Accounts enhancement) |
| 7 | No real-time AFEX customer profile sync | Data consistency risk | Next (Integration) |
| 8 | No i18n (Arabic + multilingual) | Cannot launch in UAE market | Next (UI) |

### High Gaps (Required for regulated go-live)

| # | Gap | Business Impact | Suggested Phase |
|---|---|---|---|
| 9 | No regulatory reporting (CBUAE) | Compliance blocker | 10C or dedicated phase |
| 10 | No dispute management system | Customer service gap | Dedicated phase |
| 11 | No GL posting to AFEX core system | Accounting reconciliation risk | Integration phase |
| 12 | No refund/partial refund admin workflow | Customer resolution gap | 10C |
| 13 | No WPS salary credit integration | Key funding channel missing | Integration phase |
| 14 | No real notification delivery (push/SMS/email) | Customer communication gap | Integration phase |
| 15 | No statement PDF/CSV generation | Compliance + customer need | 10C |

### Medium Gaps (Expected for full product launch)

| # | Gap | Business Impact | Suggested Phase |
|---|---|---|---|
| 16 | No merchant services / acquiring | Revenue channel missing | Dedicated phase |
| 17 | No request money / payment requests | Feature gap | Dedicated phase |
| 18 | No remittance inward flow | Key use case missing | Integration phase |
| 19 | No campaign/promotion targeting engine | Marketing gap | Post-launch |
| 20 | No referral tracking / loyalty earn rules | Growth features missing | Post-launch |
| 21 | No biometric authentication | UX gap (mobile) | Mobile phase |
| 22 | No geo-fencing | Security feature gap | Post-launch |

### Lower Priority / Post-Launch

| # | Gap | Business Impact | Suggested Phase |
|---|---|---|---|
| 23 | No lending engine (salary advance, BNPL) | Revenue opportunity deferred | 10B (planned) |
| 24 | No investment provider integration | Revenue opportunity deferred | Post-launch |
| 25 | No VAS (goal saving, micro saving, budgets, AI tools) | Differentiation features deferred | Post-launch |
| 26 | No IoT device linking | Future capability | Post-launch |
| 27 | No SME expense wallets | B2B feature deferred | Post-launch |
| 28 | No chatbot / in-app help | Customer support gap | Post-launch |
| 29 | No custom report builder | Admin productivity gap | Post-launch |
| 30 | No analytics / BI dashboards | Business intelligence gap | Post-launch |

---

## Coverage Summary by Count

| Status | Requirements Count | Sub-items Covered | Sub-items Gap |
|---|---|---|---|
| DONE (fully covered) | 0 of 20 areas | ~12 individual items | — |
| PARTIAL (foundation exists) | 11 of 20 areas | ~35 individual items | ~30 items need enhancement |
| GAP (not started) | 9 of 20 areas | — | ~40 individual items |

**Estimated coverage: ~30% of business requirements have working implementations.**
**Estimated foundation coverage: ~55% have at least partial domain-layer scaffolding.**

The platform's architectural foundation (auth, ledger, transfers, limits, settlement, compliance, risk, observability, admin RBAC) is strong. The primary gaps are in **external system integrations** (payment rails, banking connectors, AFEX core sync), **mobile-specific features** (PIN, biometrics, QR), **regulatory and reporting capabilities**, and **value-added services** (lending, VAS, merchant, investment).