saafe-redirection-flow 2.0.0 → 2.2.0

package/docs/features/account-discovery.md

@@ -0,0 +1,803 @@
+# Account Discovery Module Documentation
+
+## Overview
+
+The Account Discovery module is a core feature of the SAAFE Redirection Flow that enables users to discover, select, and link their financial accounts from various Financial Institution Providers (FIPs). This module provides both automatic discovery based on user identifiers and manual selection through a comprehensive Financial Institution listing.
+
+## Core Components
+
+### 1. Discover Page (`Discover.tsx`)
+
+The main interface for account discovery and linking functionality.
+
+**Location**: `src/pages/accounts/Discover.tsx`
+
+**Multi-Purpose Component**:
+The Discover component handles multiple account-related flows based on the current route:
+- FIP category listing (`/link-accounts/:category`)
+- Account discovery (`/link-accounts/discovery`)
+- Account linking (`/link-accounts/link`)
+- Account details (`/link-accounts/discover-account`)
+
+**Key Features**:
+- Dynamic FIP categorization and display
+- Search functionality with real-time filtering
+- Account auto-discovery integration
+- Multi-account selection capability
+- Progressive disclosure of account information
+
+### 2. AccountsToProceed Component
+
+**Location**: `src/pages/accounts/AccountsToProceed.tsx`
+
+**Purpose**: Displays selected accounts before proceeding to consent review
+
+**Features**:
+- Account selection summary
+- Individual account details
+- Modification options
+- Navigation to consent review
+
+### 3. DiscoverAccount Component
+
+**Location**: `src/pages/accounts/DiscoverAccount.tsx`
+
+**Purpose**: Detailed view for specific account discovery
+
+**Features**:
+- Account-specific information display
+- Discovery status tracking
+- Error handling for discovery failures
+- Retry mechanisms
+
+### 4. LinkSelectedAccounts Component
+
+**Location**: `src/pages/accounts/LinkSelectedAccounts.tsx`
+
+**Purpose**: Final account linking interface
+
+**Features**:
+- Selected accounts confirmation
+- Linking progress indication
+- Success/failure handling
+- Post-linking actions
+
+### 5. OldUser Component
+
+**Location**: `src/pages/accounts/OldUser.tsx`
+
+**Purpose**: Interface for returning users with existing linked accounts
+
+**Features**:
+- Display of previously linked accounts
+- Option to add new accounts
+- Account unlinking functionality
+- Account status management
+
+## FIP (Financial Institution Provider) Management
+
+### FIP Store (`fip.store.ts`)
+
+**Location**: `src/store/fip.store.ts`
+
+**State Structure**:
+```typescript
+interface FipState {
+  fips: FipData[];
+  groupedFips: Record<string, FipData[]>;
+  selectedFips: Record<string, string[]>;
+  activeCategory: string | null;
+  categories: string[];
+  completedCategories: string[];
+  currentCategoryStep: CategoryStepType;
+  selectedAccountToLink: AccountToLink[];
+  originalAccounts: AutoDiscoveryResponse['Accounts'];
+  accountsStatusArray: AccountStatus[];
+  identifiers: Identifier[];
+  accountForConsent: AccountForConsent[];
+}
+```
+
+**Key Actions**:
+- `setFips(fips, categories)` - Initialize FIP data
+- `setSelectedFips(category, fipIds)` - Manage FIP selections
+- `setActiveCategory(category)` - Set current category
+- `setSelectedAccountToLink(accounts)` - Manage account selections
+- `setOriginalAccounts(accounts)` - Store auto-discovery results
+
+### FIP Categories
+
+**Supported Categories**:
+- **BANK**: Traditional banking institutions
+- **NBFC**: Non-Banking Financial Companies
+- **INSURANCE**: Insurance providers
+- **GST**: GST-related financial data
+- **INVESTMENTS**: Investment and mutual fund companies
+
+**Category Configuration**:
+```typescript
+const CATEGORY_TYPES = {
+  BANK: 'Banks',
+  NBFC: 'NBFCs', 
+  INSURANCE: 'Insurance',
+  GST: 'GST',
+  INVESTMENTS: 'Investments'
+} as const;
+```
+
+## Auto-Discovery Feature
+
+### Auto-Discovery Hook (`use-auto-discovery.ts`)
+
+**Location**: `src/hooks/use-auto-discovery.ts`
+
+**Purpose**: Automatically discover user accounts based on identifiers
+
+**Key Features**:
+- Multiple identifier support (mobile, email, PAN, etc.)
+- Batch discovery across FIPs
+- Real-time discovery status
+- Error handling and retry logic
+
+**Usage**:
+```typescript
+const {
+  discoverAccounts,
+  isDiscovering,
+  discoveryResults,
+  error
+} = useAutoDiscovery();
+
+// Trigger discovery
+const results = await discoverAccounts({
+  identifiers: ['mobile:9876543210', 'email:user@example.com'],
+  categories: ['BANK', 'INSURANCE']
+});
+```
+
+### Account Discovery Hook (`use-account-discovery.ts`)
+
+**Location**: `src/hooks/use-account-discovery.ts`
+
+**Purpose**: Enhanced account discovery with additional features
+
+**Features**:
+- Progressive discovery
+- Cache management
+- Background updates
+- Discovery analytics
+
+## Account Selection and Linking
+
+### Account Data Structures
+
+**Account Interface**:
+```typescript
+interface AccountToLink {
+  accountId: string;
+  accountNumber: string;
+  accountType: string;
+  fipId: string;
+  fipName: string;
+  maskedAccountNumber: string;
+  isSelected: boolean;
+  balance?: number;
+  currency?: string;
+}
+```
+
+**Account Status Interface**:
+```typescript
+interface AccountStatus {
+  accountId: string;
+  status: 'PENDING' | 'LINKED' | 'FAILED' | 'EXPIRED';
+  lastUpdated: Date;
+  errorMessage?: string;
+}
+```
+
+### Link Accounts Hook (`use-link-accounts.ts`)
+
+**Purpose**: Manage the account linking process
+
+**Features**:
+- Multi-account linking
+- Progress tracking
+- Error handling
+- Success confirmation
+
+**Usage**:
+```typescript
+const {
+  linkAccounts,
+  isLinking,
+  progress,
+  linkedAccounts,
+  errors
+} = useLinkAccounts();
+
+// Link selected accounts
+await linkAccounts(selectedAccounts);
+```
+
+## Search and Filtering
+
+### FIP Search Functionality
+
+**Search Features**:
+- Real-time text search
+- Category-based filtering
+- Multi-criteria search
+- Search result highlighting
+
+**Search Implementation**:
+```typescript
+const filteredFips = useMemo(() => {
+  return fips.filter(fip => {
+    const matchesSearch = fip.name.toLowerCase().includes(searchTerm.toLowerCase());
+    const matchesCategory = !activeCategory || fip.category === activeCategory;
+    return matchesSearch && matchesCategory;
+  });
+}, [fips, searchTerm, activeCategory]);
+```
+
+### Advanced Filtering
+
+**Filter Options**:
+- Institution type
+- Availability status
+- Onboarding status
+- Popular institutions
+
+**Filter Implementation**:
+```typescript
+const getFilteredFips = (fips: FipData[], filters: FilterOptions) => {
+  return fips.filter(fip => {
+    if (filters.type && fip.type !== filters.type) return false;
+    if (filters.onlyAvailable && !fip.isAvailable) return false;
+    if (filters.onlyOnboarded && !fip.isOnBoarded) return false;
+    return true;
+  });
+};
+```
+
+## API Integration
+
+### FIP Service (`fip.service.ts`)
+
+**Location**: `src/services/api/fip.service.ts`
+
+**API Endpoints**:
+```typescript
+// Get available FIPs
+GET /fips
+Query: { category?, search?, limit?, offset? }
+
+// Discover accounts
+POST /accounts/discover
+Body: { identifiers: string[], fipIds: string[] }
+
+// Link accounts
+POST /accounts/link
+Body: { accounts: AccountToLink[] }
+
+// Get account details
+GET /accounts/:accountId
+```
+
+**Service Methods**:
+- `getFips(category?)` - Fetch available FIPs
+- `discoverAccounts(identifiers, fipIds)` - Auto-discover accounts
+- `linkAccounts(accounts)` - Link selected accounts
+- `getAccountDetails(accountId)` - Get detailed account info
+
+### Account Service (`account.service.ts`)
+
+**Location**: `src/services/api/account.service.ts`
+
+**Features**:
+- Account CRUD operations
+- Bulk account operations
+- Account status management
+- Account metadata handling
+
+## User Interface Components
+
+### FIP Category Cards
+
+**Features**:
+- Category-specific icons
+- Institution counts
+- Progress indicators
+- Completion status
+
+**Component Structure**:
+```tsx
+interface CategoryCardProps {
+  category: string;
+  institutionCount: number;
+  isCompleted: boolean;
+  isActive: boolean;
+  onClick: () => void;
+}
+```
+
+### FIP Institution Cards
+
+**Features**:
+- Institution logos
+- Availability status
+- Selection indicators
+- Quick actions
+
+**Card Variants**:
+- List view for mobile
+- Grid view for desktop
+- Compact view for selection
+
+### Account Selection Interface
+
+**Features**:
+- Multi-select checkboxes
+- Account detail cards
+- Selection summary
+- Bulk operations
+
+**Selection Management**:
+```typescript
+const handleAccountSelection = (account: AccountToLink) => {
+  setSelectedAccounts(prev => {
+    const isSelected = prev.some(acc => acc.accountId === account.accountId);
+    if (isSelected) {
+      return prev.filter(acc => acc.accountId !== account.accountId);
+    } else {
+      return [...prev, account];
+    }
+  });
+};
+```
+
+## Internationalization
+
+### Multi-Language Support
+
+**Supported Languages**:
+- English (en)
+- Hindi (hi)
+- Tamil (ta)
+- Malayalam (ml)
+- Telugu (te)
+- Kannada (kn)
+- Urdu (ur)
+
+**Translation Keys**:
+```json
+{
+  "categories": {
+    "bank": "Banks",
+    "nbfc": "NBFCs",
+    "insurance": "Insurance",
+    "gst": "GST",
+    "investments": "Investments"
+  },
+  "discovery": {
+    "searching": "Searching for accounts...",
+    "found": "Found {{count}} accounts",
+    "noResults": "No accounts found"
+  }
+}
+```
+
+### RTL Support
+
+**Features**:
+- Right-to-left layout for Arabic/Urdu
+- RTL-aware animations
+- Direction-specific styling
+- Icon orientation handling
+
+## Platform-Specific Optimizations
+
+### Mobile Platform
+
+**Optimizations**:
+- Touch-friendly interface
+- Swipe gestures for navigation
+- Bottom sheet for account details
+- Mobile-specific layouts
+
+**Mobile Components**:
+```tsx
+// Mobile-specific FIP grid
+<div className="grid grid-cols-2 gap-4 md:grid-cols-3 lg:grid-cols-4">
+  {fips.map(fip => (
+    <FipCard key={fip.id} fip={fip} variant="mobile" />
+  ))}
+</div>
+```
+
+### Desktop Platform
+
+**Optimizations**:
+- Hover states and animations
+- Keyboard navigation
+- Multi-column layouts
+- Advanced filtering UI
+
+**Desktop Features**:
+- Sidebar navigation
+- Tabbed interface
+- Advanced search
+- Bulk operations
+
+## Error Handling
+
+### Discovery Errors
+
+**Error Types**:
+- Network connectivity issues
+- FIP service unavailable
+- Invalid credentials
+- Account not found
+- Rate limiting
+
+**Error Recovery**:
+```typescript
+const handleDiscoveryError = (error: DiscoveryError) => {
+  switch (error.type) {
+    case 'NETWORK_ERROR':
+      // Retry with exponential backoff
+      scheduleRetry(error.context);
+      break;
+    case 'FIP_UNAVAILABLE':
+      // Skip FIP and continue
+      skipFipAndContinue(error.fipId);
+      break;
+    case 'RATE_LIMITED':
+      // Wait and retry
+      scheduleRetryAfterDelay(error.retryAfter);
+      break;
+    default:
+      // Show user-friendly error
+      showErrorMessage(error.message);
+  }
+};
+```
+
+### User-Friendly Error Messages
+
+**Error Message Mapping**:
+```typescript
+const ERROR_MESSAGES = {
+  NETWORK_ERROR: 'Please check your internet connection and try again.',
+  FIP_UNAVAILABLE: 'This institution is temporarily unavailable.',
+  ACCOUNT_NOT_FOUND: 'No accounts found with the provided information.',
+  INVALID_CREDENTIALS: 'Please verify your login credentials.',
+};
+```
+
+## Performance Optimizations
+
+### Virtual Scrolling
+
+**Implementation**:
+- Large FIP lists optimization
+- Smooth scrolling performance
+- Memory usage optimization
+
+```tsx
+import { FixedSizeList } from 'react-window';
+
+const VirtualFipList = ({ fips }: { fips: FipData[] }) => (
+  <FixedSizeList
+    height={400}
+    itemCount={fips.length}
+    itemSize={80}
+    itemData={fips}
+  >
+    {FipListItem}
+  </FixedSizeList>
+);
+```
+
+### Caching Strategy
+
+**Cache Levels**:
+- FIP list caching (24 hours)
+- Discovery results caching (5 minutes)
+- Account details caching (1 hour)
+
+**Cache Implementation**:
+```typescript
+const useFipsWithCache = () => {
+  return useQuery({
+    queryKey: ['fips'],
+    queryFn: fetchFips,
+    staleTime: 24 * 60 * 60 * 1000, // 24 hours
+    cacheTime: 24 * 60 * 60 * 1000,
+  });
+};
+```
+
+## Analytics and Tracking
+
+### Discovery Analytics
+
+**Tracked Events**:
+- FIP category selection
+- Institution selection
+- Account discovery initiation
+- Discovery success/failure
+- Account linking actions
+
+**Analytics Implementation**:
+```typescript
+// Track discovery events
+trackEvent('ACCOUNT_DISCOVERY_STARTED', {
+  category: activeCategory,
+  fipCount: selectedFips.length,
+  identifierTypes: identifiers.map(id => id.type)
+});
+
+trackEvent('ACCOUNT_DISCOVERY_COMPLETED', {
+  category: activeCategory,
+  accountsFound: discoveredAccounts.length,
+  duration: discoveryDuration
+});
+```
+
+### User Journey Tracking
+
+**Journey Stages**:
+1. Category selection
+2. FIP browsing
+3. Institution selection
+4. Account discovery
+5. Account selection
+6. Linking confirmation
+
+## Testing Strategy
+
+### Unit Tests
+
+**Test Coverage**:
+- FIP filtering logic
+- Account selection state
+- Discovery hook functionality
+- Error handling scenarios
+
+**Example Tests**:
+```typescript
+describe('FIP Discovery', () => {
+  test('filters FIPs by category', () => {
+    const fips = mockFipData;
+    const filtered = filterFipsByCategory(fips, 'BANK');
+    expect(filtered).toHaveLength(5);
+    expect(filtered.every(fip => fip.category === 'BANK')).toBe(true);
+  });
+
+  test('handles discovery errors gracefully', async () => {
+    const mockError = new Error('Network error');
+    mockDiscoveryService.mockRejectedValue(mockError);
+    
+    const { result } = renderHook(() => useAutoDiscovery());
+    await act(() => result.current.discoverAccounts(mockIdentifiers));
+    
+    expect(result.current.error).toBe(mockError);
+  });
+});
+```
+
+### Integration Tests
+
+**Test Scenarios**:
+- Complete discovery flow
+- Multi-category selection
+- Account linking process
+- Error recovery flows
+
+### End-to-End Tests
+
+**E2E Scenarios**:
+```typescript
+test('complete account discovery and linking flow', async () => {
+  // Navigate to discovery page
+  await page.goto('/link-accounts/banks');
+  
+  // Select a bank
+  await page.click('[data-testid="bank-card-hdfc"]');
+  
+  // Wait for discovery
+  await page.waitForSelector('[data-testid="discovered-accounts"]');
+  
+  // Select accounts
+  await page.check('[data-testid="account-checkbox-1"]');
+  await page.check('[data-testid="account-checkbox-2"]');
+  
+  // Proceed to consent
+  await page.click('[data-testid="proceed-button"]');
+  
+  // Verify navigation to consent page
+  expect(page.url()).toContain('/review');
+});
+```
+
+## Configuration
+
+### Discovery Configuration
+
+```typescript
+export const DISCOVERY_CONFIG = {
+  maxConcurrentDiscoveries: 5,
+  discoveryTimeout: 30000, // 30 seconds
+  retryAttempts: 3,
+  retryDelay: 1000, // 1 second
+  cacheTimeout: 5 * 60 * 1000, // 5 minutes
+};
+```
+
+### FIP Display Configuration
+
+```typescript
+export const FIP_DISPLAY_CONFIG = {
+  itemsPerPage: 20,
+  enableVirtualScrolling: true,
+  showLogos: true,
+  enableSearch: true,
+  enableFiltering: true,
+  defaultSortBy: 'popularity',
+};
+```
+
+## Future Enhancements
+
+### Planned Features
+
+1. **Smart Recommendations**
+   - AI-based FIP suggestions
+   - Popular institution highlighting
+   - User behavior analysis
+
+2. **Enhanced Discovery**
+   - OCR-based document scanning
+   - QR code account linking
+   - Bulk import functionality
+
+3. **Advanced Filtering**
+   - Geographic filtering
+   - Service-based filtering
+   - Custom filter presets
+
+4. **Improved UX**
+   - Progressive web app features
+   - Offline support
+   - Voice navigation
+
+### Performance Improvements
+
+1. **Optimization**
+   - GraphQL integration
+   - Server-side rendering
+   - Edge caching
+
+2. **Mobile Enhancements**
+   - Native app integration
+   - Biometric authentication
+   - Push notifications
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Discovery Timeout**
+   - **Symptom**: Discovery process hangs
+   - **Solution**: Increase timeout values
+   - **Prevention**: Implement progressive discovery
+
+2. **No Accounts Found**
+   - **Symptom**: Discovery returns empty results
+   - **Solution**: Verify identifier formats
+   - **Prevention**: Add identifier validation
+
+3. **FIP Loading Issues**
+   - **Symptom**: FIP list fails to load
+   - **Solution**: Check API connectivity
+   - **Prevention**: Implement offline fallback
+
+### Debug Mode
+
+**Enable Debug Logging**:
+```typescript
+localStorage.setItem('discovery-debug', 'true');
+```
+
+**Debug Information**:
+- Discovery request/response logs
+- FIP filtering operations
+- Account selection changes
+- Performance metrics
+
+## API Documentation
+
+### Discovery Endpoints
+
+**Base URL**: `{API_URL}/discovery`
+
+#### GET /fips
+Get available Financial Institution Providers.
+
+**Request**:
+```
+GET /fips?category=BANK&search=hdfc&limit=20&offset=0
+```
+
+**Response**:
+```json
+{
+  "success": true,
+  "data": {
+    "fips": [
+      {
+        "id": "fip_001",
+        "name": "HDFC Bank",
+        "category": "BANK",
+        "logo": "https://...",
+        "isAvailable": true,
+        "isOnBoarded": true
+      }
+    ],
+    "total": 150,
+    "categories": ["BANK", "NBFC", "INSURANCE"]
+  }
+}
+```
+
+#### POST /accounts/discover
+Discover user accounts across FIPs.
+
+**Request**:
+```json
+{
+  "identifiers": [
+    {
+      "type": "mobile",
+      "value": "9876543210"
+    },
+    {
+      "type": "email", 
+      "value": "user@example.com"
+    }
+  ],
+  "fipIds": ["fip_001", "fip_002"],
+  "categories": ["BANK", "INSURANCE"]
+}
+```
+
+**Response**:
+```json
+{
+  "success": true,
+  "data": {
+    "accounts": [
+      {
+        "accountId": "acc_001",
+        "fipId": "fip_001",
+        "accountNumber": "****1234",
+        "accountType": "SAVINGS",
+        "balance": 25000.50,
+        "currency": "INR"
+      }
+    ],
+    "discoveryStatus": {
+      "total": 2,
+      "successful": 1,
+      "failed": 1,
+      "errors": ["FIP_002: Service temporarily unavailable"]
+    }
+  }
+}
+```
+
+## Conclusion
+
+The Account Discovery module provides a comprehensive and user-friendly interface for discovering and linking financial accounts. It combines automatic discovery capabilities with manual selection options, ensuring users can connect all their relevant financial accounts efficiently and securely.