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=uswhen omitted. - Uses
PLAID_COUNTRIESand theproviderquery parameter to decide which page to render. - Loads the provider page with
ssr: falseso 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
redirectingStateserrorisProcessingConnectioncustomerIdcategoryOverridesconnectedAccountscreditReportFileNamecreditReportUploadErroraddCountryOpen
Key derived values
isEuFlowselectedProvidercountryDisplayNamehasPersonalAccountbusinessAccountTitlecontinueUrlbackUrlconnectLaterUrl
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.
Plaid Link Button (frontend/app/application/PlaidLinkButton.tsx)
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]
getDefaultOpenBankingProviderForCountryandgetOpenBankingProvidersForCountryboth collapse to the Salt Edge option. Country-specific provider switching in this feature is performed byfrontend/app/application/connect-accounts/page.tsxusingPLAID_COUNTRIESand theproviderquery 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:
bankfinancialfinancecredittrustcapitalbancbancobancabanque
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
fetchApiWithFallbacktries multiple candidate URLs and keeps the last 404 response if every candidate fails with “not found”.- Salt Edge backend errors are surfaced as
HTTPExceptionresponses with the backend status and detail string. - Unsupported Salt Edge country errors are converted to
422with{ code: "unsupported_country", message: ... }, which the frontend maps to the manual credit-upload path. - Browser parsing errors from
localStorageare caught and the broken storage entry is removed. - Invalid credit-report uploads reset the file input and show an inline error message.
PlaidLinkButtonclears 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
- Check the cache before acquiring the lock.
- Re-check the cache after acquiring the lock.
- Populate the cache from
saltedge_client.list_all_customers(). - Return cached data until TTL expiry.
Frontend Browser Persistence
- Connected accounts are written to
localStorageafter 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.replaceafter processing.
Dependencies
- Next.js App Router
- React hooks:
useState,useEffect,useMemo,useCallback,useRef,Suspense next/navigationnext/dynamicreact-plaid-linklucide-reactConnectAccountsLayoutAddCountryModalresolveBackendApiUrlisLikelyNetworkError- Backend Salt Edge service and
SaltEdgeClient - Backend auth dependency
getCurrentUserEmail proxySaltEdgeRequest
Testing Considerations
- Route selection should switch to Plaid for
us,ca, orprovider=plaid. - Missing
countryshould resolve tous. - Salt Edge return URLs should clear duplicate query parameters after processing.
- A second return for the same
connection_idshould be ignored byprocessedConnections. - Invalid credit-report files should clear the file input and surface the validation error.
dw_application_connected_accounts_versionmismatches should invalidate old browser state.- Salt Edge
unsupported_countryerrors 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. |