Bank Integration Flow¶

Overview¶

The bank integration process in OmniButler enables users to securely connect their financial accounts through Plaid. The flow is designed to be secure, efficient, and user-friendly, leveraging Plaid's Link interface for bank authentication and Firestore for connection management.

Flow Diagrams¶

System Flow¶

```mermaid sequenceDiagram participant User participant Frontend participant Backend participant Plaid API participant Firestore

User->>Frontend: Initiate bank connection
Frontend->>Backend: GET /bank/connect
Backend->>Backend: Verify Firebase token
Backend->>Firestore: Get user details
Backend->>Plaid API: Create link token
Plaid API-->>Backend: Return link token
Backend-->>Frontend: Return link token
Frontend-->>User: Launch Plaid Link
User->>Frontend: Complete Plaid Link
Frontend->>Backend: POST /bank/set_access_token
Backend->>Backend: Verify Firebase token
Backend->>Firestore: Get user details
Backend->>Plaid API: Exchange public token
Plaid API-->>Backend: Return access token
Backend->>Firestore: Create bank connection
Backend->>Plaid API: Get institution details
Backend->>Firestore: Store institution info
Backend-->>Frontend: Return success

```

Code Flow¶

```mermaid graph TD subgraph Frontend A[User Initiation] → B[Plaid Link SDK] B → C[Get Link Token] end

subgraph Backend
    D[API Request with Token] --> E[Auth Middleware]
    E --> F[verify_firebase_token]

    subgraph Application Layer
        F --> G[PlaidConnectRouter]
        G --> H[create_link_token]
        G --> I[exchange_public_token]
    end

    subgraph Domain Layer
        H --> J[BankConnection Model]
        I --> K[ItemStatus Enum]
    end

    subgraph Infrastructure Layer
        J --> L[PlaidClient]
        L --> M[link_token_create]
        L --> N[item_public_token_exchange]
        J --> O[Firestore Operations]
    end
end

style Frontend fill:#f9f,stroke:#333,stroke-width:2px
style Backend fill:#bbf,stroke:#333,stroke-width:2px
style Application Layer fill:#dfd,stroke:#333,stroke-width:2px
style Domain Layer fill:#fdd,stroke:#333,stroke-width:2px
style Infrastructure Layer fill:#ddf,stroke:#333,stroke-width:2px

```

Key Components¶

Frontend
Plaid Link SDK
Token management
API client
Application Layer
PlaidConnectRouter: Manages bank connection endpoints
verify_firebase_token: Handles token verification
API routes and controllers
Domain Layer
BankConnection: Core bank connection entity
ItemStatus: Connection status tracking
InstitutionInfo: Bank institution details
Infrastructure Layer
PlaidClient: Plaid API integration
Firestore client
Firebase admin SDK

Technical Details¶

Authentication Flow¶

Initial Connection
User initiates bank connection
Backend creates Plaid link token
User authenticates with bank through Plaid Link
Token Exchange
Plaid returns public token
Backend exchanges for access token
Access token stored securely in Firestore
Connection Creation
System creates bank connection record
Fetches institution details
Stores connection metadata

Data Models¶

BankConnection¶

class BankConnection(BaseModel):
    connection_id: str
    app_user_id: str
    institution_id: str
    institution_name: str
    item_id: str
    access_token: str
    cursor: str = ""
    status: ItemStatus = ItemStatus.GOOD
    error_type: str | None = None
    error_code: str | None = None
    last_sync: datetime
    account_ids: list[str]

ItemStatus¶

class ItemStatus(StrEnum):
    GOOD = "good"
    BAD = "bad"
    ERROR = "error"
    PENDING_EXPIRATION = "pending_expiration"
    PENDING_DISCONNECT = "pending_disconnect"

Security Considerations¶

All authentication through Firebase
Access tokens stored securely in Firestore
Public tokens are single-use
Each connection has isolated access

API Endpoints¶

The bank integration flow uses these endpoints:

Plaid Integration
/api/v1/bank/connect - Create link token
/api/v1/bank/set_access_token - Exchange public token

Error Handling¶

The system handles various error scenarios:

Authentication Failures
Invalid tokens
Expired sessions
Plaid API errors
Connection Failures
Invalid public tokens
Institution errors
Storage failures
Integration Issues
Plaid API errors
Token exchange failures
Institution data issues

Monitoring¶

The system logs key events: - Connection creation - Token exchanges - Institution data fetches - Error conditions

Areas for Improvement¶

By Category¶

1. Security Enhancements¶

Token Handling
Implement token rotation mechanism
Add token expiration monitoring
Implement token revocation
Add rate limiting for token exchanges
Remove sensitive data from logs
Data Protection
Implement encryption for sensitive data
Add connection audit logging
Implement row-level security
Add data access controls
Error Handling
Implement specific error types
Add proper error messages
Implement consistent error patterns
Add error recovery mechanisms

2. Architecture Improvements¶

Clean Architecture
Create proper interfaces for Plaid integration
Move Plaid client dependency to infrastructure layer
Separate connection and data concerns
Implement proper dependency injection
Repository Pattern
Define clear repository interfaces
Implement proper data access patterns
Add connection status tracking
Implement proper error handling

3. Performance Optimizations¶

Caching
Implement institution data caching
Add connection status caching
Implement token caching
Add performance monitoring
Batch Operations
Implement batch token exchanges
Add bulk institution data fetches
Implement connection pooling
Add performance metrics

4. User Experience¶

Connection Management
Add connection status notifications
Implement progress tracking
Add error recovery flows
Implement user feedback
Error Recovery
Add automatic reconnection
Implement error reporting
Add user guidance
Implement fallback mechanisms

By Priority¶

High Priority¶

Security
Token rotation implementation
Enhanced error handling
Data encryption
Reliability
Error recovery mechanisms
Connection status tracking
Automatic reconnection
Performance
Institution data caching
Batch operations
Connection pooling

Medium Priority¶

Features
Additional Plaid products
Country support expansion
Enhanced metadata
Monitoring
Connection health tracking
Performance metrics
Automated alerts
User Experience
Status notifications
Progress tracking
Error recovery flows

Low Priority¶

Documentation
API documentation
Troubleshooting guides
Best practices
Testing
Integration tests
Load testing
Test automation
Maintenance
Dependency updates
Code optimization
Technical debt

Future Considerations¶

Short-term (1-3 months)¶

Implement token rotation
Add basic monitoring
Enhance error handling

Medium-term (3-6 months)¶

Expand country support
Add performance optimizations
Implement comprehensive testing

Long-term (6+ months)¶

Add advanced security features
Implement AI-powered error detection
Create automated recovery systems

Robust SyncProgress Handling (June 2025)¶

The transaction sync system now mirrors the email system's robust SyncProgress handling: - SyncProgress is updated at every stage (pending, in_progress, completed, failed), with detailed context and error information. - Failed syncs are automatically reset to 'pending' for retry, ensuring reliability and idempotency. - All orchestrator and worker code now uses the same update pattern as the email system, with structured logging and error handling. - Tests have been updated to assert on sync progress updates, ensuring regression safety and business-driven coverage. - This closes the gap with the email system for progress tracking, error recovery, and user experience. - All relevant code and tests now pass, confirming the system is robust and production-ready.