Banking and Financial Data Domain - Connected Account UX, Provider Proxy Routes, and Frontend Banking APIs

Overview

This feature drives the “connect your accounts” step in the application flow. It decides whether the user lands in the Plaid or Salt Edge experience, keeps the browser state for connected accounts and redirects, and lets the user continue even when they choose to upload a credit report instead of linking every account.

The frontend is the orchestrator. It reads country and provider from the URL, selects the correct provider-specific UI, creates or reuses Salt Edge customers and connect sessions, restores returning users from localStorage, and sends the browser through Next.js proxy routes to the backend open-banking services.

For Salt Edge, the browser never talks to the provider directly. It calls Next.js API routes under frontend/app/api/saltedge/*, which forward to the backend Salt Edge endpoints. The backend then creates customers, connect sessions, and connection lookups used by the connected-account UI.

Architecture Overview

flowchart TD
    U[User in browser] --> R[ConnectAccountsRouter]
    R -->|us or ca or plaid| P[PlaidConnectAccounts]
    R -->|other countries| S[SaltEdgeConnectAccounts]

    subgraph FrontendShell[Next.js Frontend Shell]
        L[ConnectAccountsLayout]
        PBtn[PlaidLinkButton]
        SaltPage[pageSalt helpers]
    end

    P --> L
    S --> L
    P --> PBtn
    S --> SaltPage

    subgraph FrontendProxy[Next.js API Proxy Routes]
        C1[customer connections route]
        C2[connection details route]
        C3[v6 customer route]
        C4[v6 connect session route]
    end

    SaltPage --> C3
    SaltPage --> C4
    SaltPage --> C1
    SaltPage --> C2
    PBtn --> BToken[backend plaid link token API]

    subgraph BackendBanking[Backend open banking service]
        BS[Salt Edge endpoint handlers]
        UC[Salt Edge usecase helpers]
        CACHE[customer cache]
        LOG[logger]
    end

    C1 --> BS
    C2 --> BS
    C3 --> BS
    C4 --> BS
    BS --> UC
    BS --> CACHE
    BS --> LOG

Component Structure

1. Presentation Layer

Connect Accounts Router (frontend/app/application/connect-accounts/page.tsx)

Routes the user to the provider-specific onboarding experience. It normalizes the country parameter, applies a default country=us when missing, and switches to Plaid either for Plaid countries or when provider=plaid is present.

Key behaviors

  • Defaults the query string to country=us when omitted.
  • Uses PLAID_COUNTRIES and the provider query parameter to decide which page to render.
  • Loads the provider page with ssr: false so the browser owns the onboarding flow.

Salt Edge Connect Accounts Page (frontend/app/application/connect-accounts/pageSalt.tsx)

Runs the Salt Edge-connected account flow. It manages browser state, creates Salt Edge customers, creates connect sessions, reads Salt Edge return parameters, and rebuilds the connected-account list from the backend response.

Key state

  • redirectingStates
  • error
  • isProcessingConnection
  • customerId
  • categoryOverrides
  • connectedAccounts
  • creditReportFileName
  • creditReportUploadError
  • addCountryOpen

Key derived values

  • isEuFlow
  • selectedProvider
  • countryDisplayName
  • hasPersonalAccount
  • businessAccountTitle
  • continueUrl
  • backUrl
  • connectLaterUrl

Plaid Connect Accounts Page (frontend/app/application/connect-accounts/pagePlaid.tsx)

Provides the Plaid version of the same step. It shares the same layout and account-card structure but uses PlaidLinkButton for provider interaction and stores connected-account state in localStorage with versioning.

Connect Accounts Layout (frontend/app/application/connect-accounts/components/ConnectAccountsLayout.tsx)

Shared shell for both provider experiences. It renders the application progress indicator, the Lita logo, the main page title, and the footer navigation.

A provider-specific control that fetches a Plaid link token from the backend, opens Plaid Link, and preserves redirect state across the OAuth round trip.

2. Provider Configuration

Provider Catalog and Country Overrides (frontend/app/application/connect-accounts/providers.ts)

Defines provider metadata and country-specific bank suggestions.

Types

Type Properties
OpenBankingProviderOption id, name, summary, coverage, compliance, dataHandling
Bank id, name, description, defaultAccount, connectUrl?
ProviderDetail provider, providerName, connectUrl, personal, investment
CountryOverride provider, providerName?, connectUrl?, personal?, investment?

Functions

Method Description
getCountryBankConfig Returns the provider, display name, connect URL, and bank suggestions for a country and account type.
getOpenBankingProvidersForCountry Returns the provider option list for a country.
getDefaultOpenBankingProviderForCountry Returns the default provider option for a country.
getOpenBankingProviderById Returns the provider option for a provider ID.

3. Frontend Banking API Proxies

Get Customer Connections

[!NOTE] getDefaultOpenBankingProviderForCountry and getOpenBankingProvidersForCountry both collapse to the Salt Edge option. Country-specific provider switching in this feature is performed by frontend/app/application/connect-accounts/page.tsx using PLAID_COUNTRIES and the provider query parameter.

frontend/app/api/saltedge/customer/[customerId]/connections/route.ts

{
    "title": "Get Customer Connections",
    "description": "Proxies a Salt Edge customer connection lookup from the browser to the backend service",
    "method": "GET",
    "baseUrl": "<FrontendOrigin>",
    "endpoint": "/api/saltedge/customer/{customerId}/connections",
    "headers": [],
    "queryParams": [],
    "pathParams": [
        {
            "key": "customerId",
            "value": "cus_123456",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Connections for a Salt Edge customer",
            "body": "{\n    \"connections\": [\n        {\n            \"id\": \"con_123456\",\n            \"provider_name\": \"HSBC\",\n            \"categorization\": \"personal\",\n            \"accounts\": [\n                {\n                    \"id\": \"acc_123456\",\n                    \"connection_id\": \"con_123456\",\n                    \"name\": \"HSBC One Account\",\n                    \"nature\": \"checking\",\n                    \"balance\": 1520.45,\n                    \"currency_code\": \"GBP\",\n                    \"extra\": {\n                        \"account_type\": \"checking\"\n                    },\n                    \"created_at\": \"2024-10-01T00:00:00Z\",\n                    \"updated_at\": \"2024-10-01T00:00:00Z\"\n                }\n            ]\n        }\n    ]\n}"
        }
    }
}

The route forwards requests to both /api/saltedge/customer/{customerId}/connections and /saltedge/customer/{customerId}/connections, letting the frontend work against whichever backend mount point is available.

Get Connection Details

frontend/app/api/saltedge/connection/[connectionId]/route.ts

{
    "title": "Get Connection Details",
    "description": "Proxies a single Salt Edge connection lookup from the browser to the backend service",
    "method": "GET",
    "baseUrl": "<FrontendOrigin>",
    "endpoint": "/api/saltedge/connection/{connectionId}",
    "headers": [],
    "queryParams": [],
    "pathParams": [
        {
            "key": "connectionId",
            "value": "con_123456",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Single Salt Edge connection record",
            "body": "{\n    \"id\": \"con_123456\",\n    \"customer_id\": \"cus_123456\",\n    \"provider_name\": \"HSBC\",\n    \"categorization\": \"personal\",\n    \"status\": \"active\",\n    \"accounts\": [\n        {\n            \"id\": \"acc_123456\",\n            \"connection_id\": \"con_123456\",\n            \"name\": \"HSBC One Account\",\n            \"nature\": \"checking\",\n            \"balance\": 1520.45,\n            \"currency_code\": \"GBP\",\n            \"extra\": {\n                \"account_type\": \"checking\"\n            },\n            \"created_at\": \"2024-10-01T00:00:00Z\",\n            \"updated_at\": \"2024-10-01T00:00:00Z\"\n        }\n    ]\n}"
        }
    }
}

The frontend uses this route when the Salt Edge widget returns connection_id, allowing it to recover the customer_id before refreshing the full connection list.

Create Salt Edge Customer

frontend/app/api/saltedge/v6/customer/route.ts

{
    "title": "Create Salt Edge Customer",
    "description": "Creates or reuses a Salt Edge customer for the onboarding flow",
    "method": "POST",
    "baseUrl": "<FrontendOrigin>",
    "endpoint": "/api/saltedge/v6/customer",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"email\": \"[email protected]\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Salt Edge customer identifier",
            "body": "{\n    \"customer_id\": \"cus_123456\"\n}"
        }
    }
}

Create Salt Edge Connect Session

frontend/app/api/saltedge/v6/connect-session/route.ts

{
    "title": "Create Salt Edge Connect Session",
    "description": "Creates a Salt Edge connect widget session for the onboarding flow",
    "method": "POST",
    "baseUrl": "<FrontendOrigin>",
    "endpoint": "/api/saltedge/v6/connect-session",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"customer_id\": \"cus_123456\",\n    \"return_to\": \"http://localhost:3000/application/connect-accounts?saltedge_redirect=true&category=personal&country=us&[email protected]\",\n    \"consent_scopes\": [\n        \"accounts\",\n        \"transactions\",\n        \"holder_info\"\n    ],\n    \"categorization\": \"personal\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Salt Edge connect session URL",
            "body": "{\n    \"connect_url\": \"https://widget.saltedge.com/connect?session_id=ses_123456\",\n    \"expires_at\": \"2024-10-01T12:30:00Z\"\n}"
        }
    }
}

This is the route the frontend calls after customer creation. If the backend returns an unsupported_country error, the Salt Edge page sends the browser to "/dashboard?manual_credit_upload=true".

4. Backend Open Banking Orchestration

Salt Edge Usecase Helpers (backend/src/usecase/saltedge_usecase.py)

These helpers assemble Salt Edge requests on the backend.

Functions

Method Description
get_or_create_saltedge_customer Calls saltedge_client.create_customer(identifier=...) and returns the resulting customer_id when available.
generate_saltedge_connect_url Calls saltedge_client.create_connect_session(...) with consent_scopes and return_to_url, then returns connect_url, expires_at, and customer_id when present.

These helpers are used by the backend Salt Edge endpoints to centralize customer and connect-session creation.

Salt Edge Backend API (backend/src/interface/saltedge_endpoints.py)

Models

Model Properties
SaltEdgeCustomerData customer_id, identifier, created_at
SaltEdgeCustomerListResponse data
SaltEdgeConnectionData id, provider_name
SaltEdgeConnectionListResponse data
SaltEdgeAccountData id, connection_id, name, nature, balance, currency_code, extra, created_at, updated_at
SaltEdgeAccountListResponse data
SaltEdgeInitiateEnduserConnectionRequest email, return_to
SaltEdgeV6CustomerRequest email
SaltEdgeV6CustomerResponse customer_id
SaltEdgeV6ConnectSessionRequest customer_id, return_to, consent_scopes, categorization
SaltEdgeV6ConnectSessionResponse connect_url, expires_at
SaltEdgeConnectionWithAccountsData id, provider_name, categorization, accounts
SaltEdgeConnectionsForCustomerResponse connections
SaltEdgeSingleConnectionResponse id, customer_id, provider_name, categorization, status, accounts

Endpoints

Connect URL

{
    "title": "Create Salt Edge Connect URL",
    "description": "Creates a Salt Edge connect URL for an authenticated user",
    "method": "POST",
    "baseUrl": "<BackendApiBaseUrl>",
    "endpoint": "/api/saltedge/connect-url",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"email\": \"[email protected]\",\n    \"return_to\": \"http://localhost:3000/dashboard\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Connect URL response",
            "body": "{\n    \"connect_url\": \"https://widget.saltedge.com/connect?session_id=ses_123456\",\n    \"expires_at\": \"2024-10-01T12:30:00Z\",\n    \"customer_id\": \"cus_123456\"\n}"
        }
    }
}

Customer List

{
    "title": "List Salt Edge Customers",
    "description": "Returns cached Salt Edge customers for the authenticated user",
    "method": "GET",
    "baseUrl": "<BackendApiBaseUrl>",
    "endpoint": "/api/saltedge/customers",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Customer list",
            "body": "{\n    \"data\": [\n        {\n            \"customer_id\": \"cus_123456\",\n            \"identifier\": \"[email protected]\",\n            \"created_at\": \"2024-10-01T12:00:00Z\"\n        }\n    ]\n}"
        }
    }
}

Connections

{
    "title": "List Salt Edge Connections",
    "description": "Returns connections for a customer",
    "method": "GET",
    "baseUrl": "<BackendApiBaseUrl>",
    "endpoint": "/api/saltedge/connections",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "customer_id",
            "value": "cus_123456",
            "required": true
        }
    ],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Connection list",
            "body": "{\n    \"data\": [\n        {\n            \"id\": \"con_123456\",\n            \"provider_name\": \"HSBC\"\n        }\n    ]\n}"
        }
    }
}

Accounts

{
    "title": "List Salt Edge Accounts",
    "description": "Returns accounts for a customer connection",
    "method": "GET",
    "baseUrl": "<BackendApiBaseUrl>",
    "endpoint": "/api/saltedge/accounts",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "customer_id",
            "value": "cus_123456",
            "required": true
        },
        {
            "key": "connection_id",
            "value": "con_123456",
            "required": true
        }
    ],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Account list",
            "body": "{\n    \"data\": [\n        {\n            \"id\": \"acc_123456\",\n            \"connection_id\": \"con_123456\",\n            \"name\": \"HSBC One Account\",\n            \"nature\": \"checking\",\n            \"balance\": 1520.45,\n            \"currency_code\": \"GBP\",\n            \"extra\": {\n                \"account_type\": \"checking\"\n            },\n            \"created_at\": \"2024-10-01T00:00:00Z\",\n            \"updated_at\": \"2024-10-01T00:00:00Z\"\n        }\n    ]\n}"
        }
    }
}

Enduser Connection

{
    "title": "Initiate Enduser Salt Edge Connection",
    "description": "Creates a Salt Edge connect URL from a provided email address",
    "method": "POST",
    "baseUrl": "<BackendApiBaseUrl>",
    "endpoint": "/api/saltedge/initiate-enduser-connection",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"email\": \"[email protected]\",\n    \"return_to\": \"http://localhost:3000/application/review\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Connect URL response",
            "body": "{\n    \"connect_url\": \"https://widget.saltedge.com/connect?session_id=ses_123456\",\n    \"expires_at\": \"2024-10-01T12:30:00Z\",\n    \"customer_id\": \"cus_123456\"\n}"
        }
    }
}

v6 Customer

{
    "title": "Create Salt Edge v6 Customer",
    "description": "Creates or reuses a Salt Edge customer for the onboarding page",
    "method": "POST",
    "baseUrl": "<BackendApiBaseUrl>",
    "endpoint": "/api/saltedge/v6/customer",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"email\": \"[email protected]\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Customer identifier",
            "body": "{\n    \"customer_id\": \"cus_123456\"\n}"
        }
    }
}

v6 Connect Session

{
    "title": "Create Salt Edge v6 Connect Session",
    "description": "Creates a Salt Edge connect session for the onboarding page",
    "method": "POST",
    "baseUrl": "<BackendApiBaseUrl>",
    "endpoint": "/api/saltedge/v6/connect-session",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"customer_id\": \"cus_123456\",\n    \"return_to\": \"http://localhost:3000/application/connect-accounts?saltedge_redirect=true&category=personal\",\n    \"consent_scopes\": [\n        \"accounts\",\n        \"transactions\",\n        \"holder_info\"\n    ],\n    \"categorization\": \"personal\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Connect session URL",
            "body": "{\n    \"connect_url\": \"https://widget.saltedge.com/connect?session_id=ses_123456\",\n    \"expires_at\": \"2024-10-01T12:30:00Z\"\n}"
        }
    }
}

Customer Connections

{
    "title": "Get Customer Connections",
    "description": "Returns all Salt Edge connections for a customer with their accounts",
    "method": "GET",
    "baseUrl": "<BackendApiBaseUrl>",
    "endpoint": "/api/saltedge/customer/{customer_id}/connections",
    "headers": [],
    "queryParams": [],
    "pathParams": [
        {
            "key": "customer_id",
            "value": "cus_123456",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Connections with account payloads",
            "body": "{\n    \"connections\": [\n        {\n            \"id\": \"con_123456\",\n            \"provider_name\": \"HSBC\",\n            \"categorization\": \"personal\",\n            \"accounts\": [\n                {\n                    \"id\": \"acc_123456\",\n                    \"connection_id\": \"con_123456\",\n                    \"name\": \"HSBC One Account\",\n                    \"nature\": \"checking\",\n                    \"balance\": 1520.45,\n                    \"currency_code\": \"GBP\",\n                    \"extra\": {\n                        \"account_type\": \"checking\"\n                    },\n                    \"created_at\": \"2024-10-01T00:00:00Z\",\n                    \"updated_at\": \"2024-10-01T00:00:00Z\"\n                }\n            ]\n        }\n    ]\n}"
        }
    }
}

Connection Details

{
    "title": "Get Salt Edge Connection",
    "description": "Returns one Salt Edge connection with customer and account details",
    "method": "GET",
    "baseUrl": "<BackendApiBaseUrl>",
    "endpoint": "/api/saltedge/connection/{connection_id}",
    "headers": [],
    "queryParams": [],
    "pathParams": [
        {
            "key": "connection_id",
            "value": "con_123456",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Single connection payload",
            "body": "{\n    \"id\": \"con_123456\",\n    \"customer_id\": \"cus_123456\",\n    \"provider_name\": \"HSBC\",\n    \"categorization\": \"personal\",\n    \"status\": \"active\",\n    \"accounts\": [\n        {\n            \"id\": \"acc_123456\",\n            \"connection_id\": \"con_123456\",\n            \"name\": \"HSBC One Account\",\n            \"nature\": \"checking\",\n            \"balance\": 1520.45,\n            \"currency_code\": \"GBP\",\n            \"extra\": {\n                \"account_type\": \"checking\"\n            },\n            \"created_at\": \"2024-10-01T00:00:00Z\",\n            \"updated_at\": \"2024-10-01T00:00:00Z\"\n        }\n    ]\n}"
        }
    }
}

Bank Logo Keyword Set

frontend/app/api/bank-logos/route.ts

BANK_KEYWORDS contains the institution-name tokens used for bank-logo classification:

  • bank
  • financial
  • finance
  • credit
  • trust
  • capital
  • banc
  • banco
  • banca
  • banque

Feature Flows

1. Provider Selection and Page Routing

sequenceDiagram
    participant U as User
    participant R as ConnectAccountsRouter
    participant P as PlaidConnectAccounts
    participant S as SaltEdgeConnectAccounts

    U->>R: Open connect accounts page
    R->>R: Read country and provider query params
    R->>R: Normalize country
    alt Plaid country or provider is plaid
        R->>P: Render Plaid flow
    else Salt Edge flow
        R->>S: Render Salt Edge flow
    end

page.tsx enforces the default country and decides which provider experience the user sees. The router does not render both flows at once; it selects one dynamic component and keeps the provider-specific implementation isolated.

2. Salt Edge Customer and Connect Session Creation

sequenceDiagram
    participant U as User
    participant S as SaltEdgeConnectAccounts
    participant F as fetchApiWithFallback
    participant R1 as v6 customer route
    participant R2 as v6 connect session route
    participant B as Backend Salt Edge API

    U->>S: Click Connect
    S->>F: POST /api/saltedge/v6/customer
    F->>R1: Browser request
    R1->>B: create customer
    B-->>R1: customer_id
    R1-->>F: customer_id
    F-->>S: customer_id

    S->>F: POST /api/saltedge/v6/connect-session
    F->>R2: Browser request
    R2->>B: create connect session
    B-->>R2: connect_url
    R2-->>F: connect_url
    F-->>S: connect_url
    S->>U: Redirect to connect_url

startSaltEdgeConnect creates a customer only when customerId is missing. It then builds a return_to URL containing saltedge_redirect=true, the selected category, and the current country and email query values.

If the backend returns an unsupported-country error for connect-session creation, the page clears the redirect state and sends the user to "/dashboard?manual_credit_upload=true".

3. Salt Edge Return Processing and Account Refresh

sequenceDiagram
    participant U as User
    participant S as SaltEdgeConnectAccounts
    participant D as /api/saltedge/connection route
    participant C as /api/saltedge/customer connections route
    participant B as Backend Salt Edge API

    U->>S: Return from Salt Edge widget
    S->>S: Read connection_id and category from query params
    S->>D: GET connection details
    D->>B: Fetch connection
    B-->>D: connection payload
    D-->>S: connection payload
    S->>S: Update category overrides and customerId

    S->>C: GET customer connections
    C->>B: Fetch all connections with accounts
    B-->>C: connections payload
    C-->>S: connections payload
    S->>S: Clean and persist connected accounts

handleSaltEdgeReturn uses the returned connection_id to recover the customer_id, updates the category overrides, and refreshes the full connection list. The handler also removes duplicate return processing by tracking processed connection IDs in a Set.

4. Plaid Token Bootstrap

sequenceDiagram
    participant U as User
    participant P as PlaidLinkButton
    participant B as Backend Plaid API

    U->>P: Click Connect
    P->>B: GET /api/plaid/create_link_token
    B-->>P: link_token
    P->>P: Store link token and account type
    P->>P: Open Plaid Link

PlaidLinkButton stores plaid_oauth_link_token and plaid_oauth_account_type so the browser can resume correctly after an OAuth redirect.

State Management

Browser State and Persistence

State or Key Type Purpose
redirectingStates Record<AccountCategory, boolean> Disables buttons while a provider redirect is in flight.
error `string \ null`
isProcessingConnection boolean Prevents duplicate Salt Edge return handling.
customerId `string \ null`
categoryOverrides Record<string, AccountCategory> Stores per-connection category overrides.
connectedAccounts { personal; business; investments } Holds the current browser-side connected-account list.
creditReportFileName `string \ null`
creditReportUploadError `string \ null`
addCountryOpen boolean Controls the “Add Another Country” modal.

Local Storage Keys

Key Purpose
dw_application_connected_accounts Persists the connected account buckets.
dw_application_connected_accounts_version Invalidates stored connected accounts when the schema changes.
dw_application_saltedge_customer_id Persists the Salt Edge customer ID.
dw_application_saltedge_category_overrides Persists account-type overrides by connection ID.
plaid_oauth_link_token Persists the Plaid link token through OAuth redirects.
plaid_oauth_account_type Persists which Plaid account category is being connected.
userFormData Carries applicant data across steps and provider returns.
email Stores the applicant email for later steps.

Account Categories

AccountCategory values: personal, business, investments.

Error Handling

  • fetchApiWithFallback tries multiple candidate URLs and keeps the last 404 response if every candidate fails with “not found”.
  • Salt Edge backend errors are surfaced as HTTPException responses with the backend status and detail string.
  • Unsupported Salt Edge country errors are converted to 422 with { code: "unsupported_country", message: ... }, which the frontend maps to the manual credit-upload path.
  • Browser parsing errors from localStorage are caught and the broken storage entry is removed.
  • Invalid credit-report uploads reset the file input and show an inline error message.
  • PlaidLinkButton clears its stored OAuth keys on both success and exit so the next connect starts cleanly.

Caching Strategy

Backend Salt Edge Customer Cache

backend/src/interface/saltedge_endpoints.py keeps a module-level customer cache for list_saltedge_customers.

Item Value
Cache object _customer_cache
Lock _customer_cache_lock
TTL CUSTOMER_CACHE_TTL_SECONDS = 60

Lifecycle

  1. Check the cache before acquiring the lock.
  2. Re-check the cache after acquiring the lock.
  3. Populate the cache from saltedge_client.list_all_customers().
  4. Return cached data until TTL expiry.

Frontend Browser Persistence

  • Connected accounts are written to localStorage after every state change.
  • The stored account payload is versioned with CONNECTED_ACCOUNTS_STORAGE_VERSION = "7".
  • When the version mismatches, the saved accounts, version key, customer ID, and category overrides are cleared.
  • Salt Edge return handling also cleans query-string parameters with router.replace after processing.

Dependencies

  • Next.js App Router
  • React hooks: useState, useEffect, useMemo, useCallback, useRef, Suspense
  • next/navigation
  • next/dynamic
  • react-plaid-link
  • lucide-react
  • ConnectAccountsLayout
  • AddCountryModal
  • resolveBackendApiUrl
  • isLikelyNetworkError
  • Backend Salt Edge service and SaltEdgeClient
  • Backend auth dependency getCurrentUserEmail
  • proxySaltEdgeRequest

Testing Considerations

  • Route selection should switch to Plaid for us, ca, or provider=plaid.
  • Missing country should resolve to us.
  • Salt Edge return URLs should clear duplicate query parameters after processing.
  • A second return for the same connection_id should be ignored by processedConnections.
  • Invalid credit-report files should clear the file input and surface the validation error.
  • dw_application_connected_accounts_version mismatches should invalidate old browser state.
  • Salt Edge unsupported_country errors should send the browser to the manual credit-upload path.
  • Proxy routes should preserve the expected response shape for customer connections and connection details.

Key Classes Reference

Class Responsibility
page.tsx Selects the Plaid or Salt Edge onboarding route and applies the default country.
pageSalt.tsx Manages Salt Edge customer creation, session creation, return handling, and browser persistence.
pagePlaid.tsx Hosts the Plaid onboarding variant and browser-side account persistence.
ConnectAccountsLayout.tsx Renders the shared onboarding shell, progress indicator, and navigation.
PlaidLinkButton.tsx Fetches Plaid link tokens, opens Plaid Link, and survives OAuth redirects.
providers.ts Defines provider metadata, country overrides, and provider lookup helpers.
route.ts Proxies browser requests to Salt Edge customer and connection endpoints.
route.ts Proxies browser requests to Salt Edge v6 customer and connect-session endpoints.
saltedge_endpoints.py Implements the backend Salt Edge API, customer cache, and error translation.
saltedge_usecase.py Builds Salt Edge customer and connect-session requests for the backend.