Wallet & Member Wallet UI/UX - Gap & SWOT Analysis

Date: 2025-12-21 Analysis Scope: Wallet Admin and Member Portal UI/UX Completeness Current Completeness: ~98% Architecture Status: Three-tier component structure complete MCA Migration Status: Complete - memberWallets.tsx uses new wallet wrapper modals Statement Export: Complete - PDF/CSV export in TransactionHistoryPage and MemberWalletDetail Wallet Status Management: Complete - Suspend/reactivate/close in MemberWalletDetail Recurring Top-Up: Complete - Auto top-up config + checkout + worker + mandate sync Audit + Outbox: Complete - Wallet audit page + outbox monitoring + journal entries Spending Categories: Complete - Admin category rules + manual tagging + portal display Advanced Analytics: Complete - Merchant rollups + tier/club cohorts + retention curves API Hooks: Complete - @digiwedge/wallet-api-client + @digiwedge/wallet-api-hooks Real-time Updates: Complete - SSE-based wallet events with outbox polling Double-Entry Ledger: Complete - Journal entries with balanced assertions

Executive Summary

The Wallet UI/UX system has achieved near-complete implementation with a clean three-tier component library structure:

@digiwedge/ui-wallet - Presentational components (Ant Design)
@digiwedge/ui-wallet-pages - Composed page components (Ant Design)
libs/ui/mca/src/components/wallet - MCA wrappers (Mantine UI)

All core admin and member-facing wallet features are now functional. The remaining gaps are advanced analytics and notification enhancements rather than core functionality.

Issue Tracker

Open Issues

Issue	Title	Priority	Notes
#10515	feat(mobile): add Wallet deep link screen	P2	Implemented in repo; verify/close if still open

Gaps Requiring Issues

Gap	Priority	Status
Mobile WalletView screen	P2	✅ Implemented
Web `/wallet` page	P2	✅ Implemented
Link-router `/wallet` route	P2	✅ Implemented; deploy pending in UAT/prod

Part 1: Architecture Assessment

1.1 Current Library Structure

Library	UI Framework	Purpose	Components
`@digiwedge/ui-wallet`	Ant Design	Presentational components	18 core components + 1 hook
`@digiwedge/ui-wallet-pages`	Ant Design	Composed page components	6 pages + bulk adjust modal
`@digiwedge/wallet-api-client`	-	REST API client	Typed client with all endpoints
`@digiwedge/wallet-api-hooks`	React Query	Data fetching hooks	23 hooks (admin + portal)
`libs/ui/mca/.../wallet`	Mantine	MCA app wrappers	3 modals + types

1.2 `@digiwedge/ui-wallet` Components

Component	Status	Storybook	Tests
`AppleWalletButton`	Complete	Yes	Yes
`GoogleWalletButton`	Complete	Yes	Yes
`AddToWalletButtons`	Complete	Yes	Yes
`WalletCardPreview`	Complete	Yes	Yes
`WalletBalance`	Complete	Yes	Yes
`WalletTopUpForm`	Complete	Yes	Yes
`WalletTransferForm`	Complete	Yes	Yes
`WalletReversalModal`	Complete	Yes	Yes
`TransactionTable`	Complete	Yes	Yes
`StatementExport`	Complete	Yes	Yes
`WalletStatusModal`	Complete	Yes	Yes
`WalletJournalEntryDrawer`	Complete	Yes	Yes
`WalletStatusTimeline`	Complete	Yes	Yes
`WalletOutboxPayloadDrawer`	Complete	Yes	Yes
`EventTicketCard`	Complete	Yes	Yes
`WalletQrLink`	Complete	Yes	Yes
`WalletEmailTemplate`	Complete	Yes	Yes
`WalletWhatsAppTemplate`	Complete	Yes	Yes
`useSendWalletLinkWhatsApp`	Complete	-	Yes

1.3 `@digiwedge/ui-wallet-pages` Pages

Page	Audience	Status	Storybook	Tests
`WalletsDashboard`	Admin	Complete	Yes	Yes
`MemberWalletDetail`	Admin	Complete	Yes	Yes
`WalletAuditPage`	Admin	Complete	Yes	Yes
`WalletOutboxDashboard`	Admin	Complete	Yes	Yes
`WalletsBulkAdjustModal`	Admin	Complete	Yes	Yes
`MyWalletPage`	Member	Complete	Yes	Yes
`TransactionHistoryPage`	Member	Complete	Yes	Yes

1.4 `@digiwedge/wallet-api-hooks` Hooks

Hook Category	Hooks	Status
Admin Wallets	`useAdminWallets`, `useAdminWalletSummary`, `useAdminWalletTransactions`	Complete
Admin Journal	`useAdminWalletJournalEntries`, `useAdminWalletStatusEvents`	Complete
Admin Outbox	`useAdminWalletOutbox`, `useAdminWalletOutboxRetry`, `useAdminWalletOutboxRetryMany`	Complete
Admin Bulk	`useAdminWalletBulkAdjust`	Complete
Admin Auto TopUp	`useAdminWalletAutoTopUp`, `useAdminWalletAutoTopUpStatus`	Complete
Portal History	`usePortalWalletHistory`, `usePortalWalletStatusEvents`	Complete
Portal Auto TopUp	`usePortalWalletAutoTopUp`, `usePortalWalletAutoTopUpUpdate`, `usePortalWalletAutoTopUpCheckout`, `usePortalWalletAutoTopUpPause`, `usePortalWalletAutoTopUpResume`, `usePortalWalletAutoTopUpCancel`	Complete

1.5 Backend Services

Service	Purpose	Status
`WalletRealtimeService`	Polls wallet outbox, emits events via RxJS Subject	Complete
`WalletRealtimeController`	SSE endpoints for portal/admin with tenant/wallet filtering	Complete
`JwtQueryGuard`	Enables JWT auth via query param for EventSource	Complete
`WalletAutoTopUpService`	Manages auto top-up config and BullMQ schedulers	Complete
`WalletAutoTopUpWorker`	Processes scheduled/threshold jobs, creates charges	Complete
`WalletLedgerService`	Double-entry journal posting with balance assertion	Complete

1.6 MCA Integration Layer

Component	Purpose	Status
`WalletTopUpModal`	Mantine wrapper for top-up	Complete
`WalletTransferModal`	Mantine wrapper for transfer	Complete
`WalletReversalModal`	Mantine wrapper for reversal	Complete
`memberWallets.tsx`	Member wallet transactions view	Migrated
`wallets.tsx`	Finances tab wallets list	Migrated

Part 2: Gap Analysis

2.1 Feature Completeness by Domain

Digital Wallet Passes    [█████████████████████] 98%
├── Apple Wallet Button          Complete (with i18n)
├── Google Wallet Button         Complete (with i18n)
├── Pass Preview                 Complete
├── QR Code Distribution         Complete
├── Email Distribution           Complete
├── WhatsApp Distribution        Complete
└── Pass Analytics               Complete (admin analytics panel)

Admin Wallet Management  [███████████████████░░] 95%
├── Member Wallets List          Complete
├── Member Wallet Detail         Complete
├── Top-Up Functionality         Complete
├── Transfer Functionality       Complete
├── Transaction Reversal         Complete
├── Wallet Status Management     Complete (suspend/reactivate/close)
├── Bulk Operations              Complete (bulk adjustments + CSV import)
├── Spending Category Rules      Complete (rules + manual tagging)
├── Spending Limits              98% Complete (schema, service, controller, portal UI done; auto-enforcement + tests pending)
├── Transaction Export           Complete (Statement export)
├── Audit Trail                  Complete (Audit page + journal)
├── Real-time Updates            Complete (SSE events)
└── Auto Top-Up Admin            Complete (view/pause/resume/cancel)

Member Portal Features   [███████████████████░] 95%
├── View Balance                 Complete
├── Transaction History          Complete
├── Top-Up (Self-Service)        Complete
├── Transfer to Member           Complete
├── Add to Apple Wallet          Complete
├── Add to Google Wallet         Complete
├── Transaction Filters          Complete
├── Statement Export             Complete (PDF/CSV export)
├── Spending Analytics           Complete (totals + categories + trend + merchants + cohorts + retention)
├── Recurring Top-Up             Complete (auto top-up config + checkout)
├── Real-time Updates            Complete (SSE events)
└── Notification Preferences     Complete (member-configurable alerts)

Integration & Hooks      [████████████████████░] 95%
├── GraphQL Queries              Partial (MCA only)
├── REST API Integration         Complete (wallet-api-client + hooks)
├── Real-time Updates            Complete (SSE wallet events)
├── Error Handling               Complete (React Query error states)
├── Loading States               Complete
└── Double-Entry Ledger          Complete (balanced assertions)

2.2 Remaining Gaps

Priority 1 (High) - Business Impact

Gap	Description	Effort	Status
~~API Integration Hooks~~	~~Pages have no data fetching hooks~~	~~Medium~~	COMPLETE
~~Wallet Status Management~~	~~Cannot suspend/reactivate/close wallets~~	~~Medium~~	COMPLETE
~~Statement Export~~	~~Members cannot export statements~~	~~Low~~	COMPLETE
~~Bulk Operations~~	~~No bulk top-up or batch processing~~	~~High~~	COMPLETE
~~Real-time Updates~~	~~No live updates, manual refresh required~~	~~Medium~~	COMPLETE

Priority 2 (Medium) - Enhancement

Gap	Description	Effort	Impact
~~Pass Analytics Dashboard~~	~~No visibility into wallet pass installations, usage~~	~~Medium~~	COMPLETE
~~Spending Insights (advanced)~~	~~Merchant rollups + cohort segmentation + retention curves~~	~~Medium~~	COMPLETE
~~Recurring Top-Up~~	~~No automated wallet funding configuration~~	~~High~~	COMPLETE
~~Transaction Notifications~~	~~No configurable alerts for low balance, transactions~~	~~Medium~~	COMPLETE

Priority 3 (Low) - Nice to Have

Gap	Description	Effort	Impact
~~MCA Migration~~	~~`memberWallets.tsx` uses legacy modals~~	~~Low~~	COMPLETE
~~Wallet Limits~~	~~Spending limits, transfer limits per member~~	~~Medium~~	98% Complete (auto-enforce + tests pending)
~~Audit Trail~~	~~Wallet-specific audit log with admin actions~~	~~Low~~	COMPLETE
Multi-Currency	UI assumes single currency (ZAR)	Medium	Low

2.3 Analytics Metrics + Data Sources

Metric	Source	Notes
Merchant rollups	`wallet-data.WalletTransaction.metadata.merchantName`	Populated on purchase ingestion from `Company.brandName`/`legalName` (fallback to `metadata.merchant`)
Cohorts by club	`scl-data.MemberClub` + `Member.walletAccountId`	Wallets grouped by club membership; respects tenant/club filter
Cohorts by tier	`scl-data.Member.membershipTierId` + `MembershipTier`	Current tier only; label includes club name to avoid collisions
Retention curves	`wallet-data.WalletAccount.createdAt` + `WalletTransaction` (DEBIT)	Cohort month = account created month; active if spend in month; 6-month window

2.4 Comparison: MCA vs Wallet-Pages

Feature	MCA (Current)	wallet-pages (New)
Data Fetching	GraphQL hooks	React Query hooks (wallet-api-hooks)
UI Framework	Mantine	Ant Design
Transaction List	TanStack Table	Ant Design Table
Modal Management	useDisclosure	useState
Reversal Logic	Server-side	Client-side detection
Type Safety	Partial	Complete
Storybook Coverage	Partial	Complete
Test Coverage	Limited	Comprehensive
Real-time Updates	Manual refresh	SSE EventSource

Part 3: SWOT Analysis

Strengths

Clean Three-Tier Architecture
- Clear separation: components → pages → app wrappers
- Shared types via @digiwedge/ui-wallet-pages types
- Presentational components are fully reusable
Comprehensive Digital Wallet Support
- Apple and Google Wallet button components
- Proper branding guideline compliance
- Multi-language support (en, es, fr, ar, id)
- Multiple distribution channels (QR, email, WhatsApp)
Complete Storybook Coverage
- All components have stories
- Page-level stories with mock data
- Interactive development possible
Type Safety
- Shared types between libraries
- Form value types exported
- Transaction type detection helper
- API client fully typed
Modern UI Patterns
- Ant Design for consistency
- Proper form validation
- Accessible components
- Responsive layouts
Complete API Integration (New)
- @digiwedge/wallet-api-client for REST calls
- @digiwedge/wallet-api-hooks for React Query integration
- 23 hooks covering all admin and portal operations
Real-time Updates (New)
- SSE-based wallet event streaming
- Automatic React Query invalidation on events
- Per-tenant/wallet event filtering
- Heartbeat mechanism for connection health
Double-Entry Ledger (New)
- Balanced journal entries for all transactions
- Audit trail with journal entry drawer
- Outbox pattern for durable event publishing

Weaknesses

~~No Data Fetching Layer~~ RESOLVED
- ~~wallet-pages has no hooks for API integration~~ Hooks now ship with wallet API client
- ~~Consumers must implement all data fetching~~ Hook layer handles fetch + error states
- ~~No React Query or Apollo integration~~ React Query hooks added
~~MCA Integration Incomplete~~ RESOLVED
- ~~memberWallets.tsx uses legacy modal imports~~ Now uses new wrapper modals
- ~~Not yet consuming wrapper components~~ Wrapper components in use
- ~~Dual patterns exist~~ Legacy modals removed
~~Limited Admin Capabilities~~ RESOLVED
- ~~Cannot manage wallet status~~ ✅ Now complete
- ~~No bulk operations~~ ✅ Bulk adjustments available
- ~~No audit trail~~ ✅ Audit page + journal view added
~~No Real-Time Updates~~ RESOLVED
- ~~Transactions require manual refresh~~ ✅ SSE integration added
- ~~No WebSocket integration~~ ✅ Using SSE (more appropriate for this use case)
- ~~Balance updates not pushed~~ ✅ React Query invalidation on events
~~Export Functionality Missing~~ RESOLVED
- ~~No statement export~~ ✅ StatementExport component added
- ~~No transaction export for admin~~ ✅ Statement export in MemberWalletDetail
Limited Analytics (Partially resolved)
- ✅ Pass install + status metrics (provider + status counts, 30-day installs/events)
- ✅ Tenant-level spend analytics (90-day spend, type/category breakdown, 6-month trend)
- ✅ Cohort signals (new wallets 30d, active wallets 30d/90d, repeat spend rate, churn after zero balance)
- ✅ Merchant rollups when merchant metadata is present
- Concrete metrics + data sources:
  - WalletTransaction + WalletTransactionCategory → spend totals, category mix, top transaction types
  - WalletJournalEntry + WalletJournalLine → double-entry rollups by account, audit-ready totals
  - WalletPass + WalletPassUpdate + WalletPassEvent → installs, status mix, 30-day engagement
  - WalletAccountStatusEvent → status change volume, suspension/reactivation rates
- Remaining advanced analytics:
  - Cohort segmentation (new vs returning by tier/club)
  - Merchant enrichment + verified merchant taxonomy
  - Pass engagement depth (opens_per_pass, avg_time_between_updates, last_pass_event_at)
~~No Notification System~~ RESOLVED
- ✅ Low balance alerts
- ✅ Transaction notifications (credit/debit)
- ✅ Configurable member alert preferences

Opportunities

Pass Engagement Analytics
- Deep usage patterns (opens per pass, update cadence)
- Geo distribution and location relevance
- Adoption trends segmented by device
Self-Service Expansion
- Spending budgets and limits
- Transaction categorization
- Personal spending insights
Member Engagement
- Low balance notifications
- Transaction alerts
- Spending insights dashboard
Mobile App Integration
- Share wallet-api-hooks with mobile
- Consistent behavior across platforms
- Real-time updates in mobile app

Threats

Fragmentation Risk (Mitigated)
- MCA migration complete
- Wrapper pattern established
- Single source of truth for components
Mobile App Divergence
- Mobile may implement separate wallet UI
- Native vs web parity issues
- Feature drift between platforms
API Evolution
- Backend may change without UI updates
- Type mismatches possible
- Need to keep client library in sync
Competition
- Third-party wallet solutions
- Apple/Google native features
- Payment app wallet features

Part 4: Recommendations

Completed Items

The following high-priority items have been delivered:

Item	Status	Delivered
API Integration Hooks	Complete	`@digiwedge/wallet-api-hooks` with 23 hooks
Statement Export	Complete	PDF/CSV via `StatementExport` component
Wallet Status Management	Complete	Suspend/reactivate/close via `WalletStatusModal`
Bulk Operations	Complete	`WalletsBulkAdjustModal` with CSV import
Recurring Top-Up	Complete	Auto top-up config, checkout, worker
Audit Trail	Complete	`WalletAuditPage`, journal entries, status timeline
Spending Insights (basic)	Partial	90-day totals + category breakdown + trend
Real-time Updates	Complete	SSE via `WalletRealtimeService` + EventSource wiring
MCA Migration	Complete	Wrapper modals in use, legacy modals removed
Double-Entry Ledger	Complete	Balanced journal posting with outbox

Next Priority Items

1. Transaction Notifications (Medium effort, Medium impact)

Enable configurable wallet alerts:

Low balance threshold alerts
Transaction notifications (credit/debit)
Delivery via email/push/WhatsApp
User preference management UI

2. Spending Insights (advanced) (Medium effort, Medium impact)

Member-facing analytics:

Balance history chart
Month-over-month change indicators
Merchant-level analytics (when references are enriched)
Comparison to cohort averages

Long-Term (Backlog)

Item	Description	Effort
~~Wallet Limits~~	~~Spending/transfer limits per member~~	~~Medium~~
Multi-Currency	Partial support (wallet currency wired to portal history); remaining defaults still ZAR in some components/tests	Medium
Batch Processing Status	Real-time status for bulk operations	Low
GraphQL Deprecation	Migrate MCA to REST hooks	Medium

Part 5: Technical Debt Register

Item	Description	Priority	Effort	Status
~~Legacy MCA modals~~	~~`memberWallets.tsx` imports old modals~~	~~Medium~~	~~Low~~	RESOLVED
~~Deprecate old modals~~	~~Remove `libs/ui/mca/src/modals/wallet*.tsx`~~	~~Low~~	~~Low~~	REMOVED
~~Missing wallet hooks~~	~~No `useWallet` hook in wallet lib~~	~~High~~	~~Medium~~	RESOLVED
Currency hardcoding	ZAR defaults remain in some components/tests (portal history now honors wallet currency)	Low	Low	Partial
Date formatting	Inconsistent date formats	Low	Low	Open
~~Error handling~~	~~Basic error display, no retry~~	~~Medium~~	~~Medium~~	RESOLVED
~~Real-time updates~~	~~Manual refresh required~~	~~Medium~~	~~Medium~~	RESOLVED

Part 6: Success Metrics

Metric	Current	Target	Notes
Component library coverage	95%	95%	All core components complete
Storybook coverage	100%	100%	All components have stories
Test coverage	80%	80%	Comprehensive page + hook tests
Admin features complete	97%	95%	Analytics panel added
Member features complete	95%	95%	Advanced analytics pending
MCA migration complete	100%	100%	Wrapper modals in use
Wallet status management	100%	100%	Suspend/reactivate/close done
Real-time updates	100%	100%	SSE integration complete
API hooks coverage	100%	100%	23 hooks covering all operations

Appendix A: File References

Core Libraries

libs/ui/wallet/src/ - Presentational components
libs/ui/wallet-pages/src/ - Page compositions
libs/wallet/api-client/src/ - REST API client
libs/hooks/wallet-api-hooks/src/ - React Query hooks
libs/ui/mca/src/components/wallet/ - MCA wrappers

Backend Services

apps/scl/scl-backend/src/app/wallet-realtime.service.ts - Outbox poller
apps/scl/scl-backend/src/app/wallet-realtime.controller.ts - SSE endpoints
apps/scl/scl-backend/src/app/guards/jwt-query.guard.ts - Query param auth
apps/scl/scl-backend/src/app/wallet-auto-topup.service.ts - Auto top-up config
apps/scl/events-worker/src/app/wallet-auto-topup.worker.ts - Job processing

Key Types

libs/ui/wallet-pages/src/types.ts - Shared types
libs/wallet/api-client/src/types.ts - API types

MCA Integration Points

libs/ui/mca/src/components/membership/viewMemberContent/memberWallets.tsx
libs/ui/mca/src/components/finances/financeTabs/wallets.tsx

Appendix B: Implementation Timeline

Date	Milestone
2025-12-18	Statement export added
2025-12-19	Wallet status management complete
2025-12-19	MCA migration + legacy modal removal
2025-12-20	Double-entry journal ledger
2025-12-20	Wallet outbox + audit trail
2025-12-20	Bulk adjustments + CSV import
2025-12-21	Auto top-up end-to-end flow
2025-12-21	SSE real-time updates
2025-12-21	Spending categories + portal insights + currency wiring

Last updated: 2025-12-21

Executive Summary​

Issue Tracker​

Open Issues​

Gaps Requiring Issues​

Part 1: Architecture Assessment​

1.1 Current Library Structure​

1.2 @digiwedge/ui-wallet Components​

1.3 @digiwedge/ui-wallet-pages Pages​

1.4 @digiwedge/wallet-api-hooks Hooks​

1.5 Backend Services​

1.6 MCA Integration Layer​

Part 2: Gap Analysis​

2.1 Feature Completeness by Domain​

2.2 Remaining Gaps​

Priority 1 (High) - Business Impact​

Priority 2 (Medium) - Enhancement​

Priority 3 (Low) - Nice to Have​

2.3 Analytics Metrics + Data Sources​

2.4 Comparison: MCA vs Wallet-Pages​

Part 3: SWOT Analysis​

Strengths​

Weaknesses​

Opportunities​

Threats​

Part 4: Recommendations​

Completed Items​

Next Priority Items​

1. Transaction Notifications (Medium effort, Medium impact)​

2. Spending Insights (advanced) (Medium effort, Medium impact)​

Long-Term (Backlog)​

Part 5: Technical Debt Register​

Part 6: Success Metrics​

Appendix A: File References​

Core Libraries​

Backend Services​

Key Types​

MCA Integration Points​

Appendix B: Implementation Timeline​