Application Management Domain Submission Funnel, Confirmation, Review, and Account Link Decision Points

Overview

This frontend funnel captures an applicant’s identity, preserves draft state across route changes, branches into the appropriate account-linking provider, and ends with a final submission receipt. The user starts on frontend/app/application/page.tsx, moves through account-linking in frontend/app/application/connect-accounts/page.tsx and its provider-specific implementations, reviews the assembled application in frontend/app/application/review/page.tsx, and lands on frontend/app/application/confirm/page.tsx after submission.

The business logic in these files is intentionally client-driven: browser storage carries the draft between steps, query parameters preserve routing context, and the review screen is the first place where the app posts a full application payload to the backend. The funnel enforces the underwriting prerequisite that at least one personal account must be present before continuing or submitting, while optional business accounts, investment accounts, and credit report upload increase the completeness of the profile.

Architecture Overview

flowchart TB
    User[Applicant]

    subgraph PresentationLayer[Presentation Layer]
        ApplicationPage[Application Entry Page]
        PasscodeRoute[Application Passcode Route]
        ConnectAccountsRouter[Connect Accounts Router]
        PlaidConnectAccounts[Plaid Connect Accounts Page]
        SaltEdgeConnectAccounts[SaltEdge Connect Accounts Page]
        ConnectAccountsLayout[Connect Accounts Layout]
        ConnectLaterPage[Connect Later Page]
        ReviewPage[Review Page]
        ConfirmPage[Confirm Page]
        PlaidLinkButton[Plaid Link Button]
    end

    subgraph BrowserState[Browser Storage and Query State]
        UserFormData[userFormData]
        ConnectedAccounts[Connected accounts storage]
        ApplicationReference[Application reference storage]
        PlaidOAuth[Plaid OAuth storage]
        SaltEdgeState[SaltEdge customer state]
    end

    subgraph BackendLayer[Backend API Layer]
        PlaidTokenApi[GET api plaid create link token]
        SaltEdgeSessionApi[POST api saltedge connect session]
        SaltEdgeConnectionsApi[GET api saltedge customer connections]
        ApplicationSubmitApi[POST api v1 applications]
    end

    User --> ApplicationPage
    ApplicationPage --> UserFormData
    ApplicationPage --> PasscodeRoute
    PasscodeRoute --> ConnectAccountsRouter

    ConnectAccountsRouter --> PlaidConnectAccounts
    ConnectAccountsRouter --> SaltEdgeConnectAccounts

    PlaidConnectAccounts --> PlaidLinkButton
    PlaidLinkButton --> PlaidTokenApi
    PlaidLinkButton --> PlaidOAuth
    PlaidConnectAccounts --> ConnectedAccounts

    SaltEdgeConnectAccounts --> SaltEdgeSessionApi
    SaltEdgeConnectAccounts --> SaltEdgeConnectionsApi
    SaltEdgeConnectAccounts --> SaltEdgeState
    SaltEdgeConnectAccounts --> ConnectedAccounts

    ConnectAccountsLayout --> ReviewPage
    ConnectAccountsLayout --> ConnectLaterPage
    ConnectLaterPage --> ConnectAccountsRouter
    ReviewPage --> ApplicationSubmitApi
    ReviewPage --> ApplicationReference
    ApplicationSubmitApi --> ConfirmPage
    ConfirmPage --> ApplicationReference

Component Structure

1. Presentation Layer

Application Entry Page

[!NOTE] The UI copy and the enforcement logic are not fully aligned in the connect-accounts step: when showBusiness is true, the business card label says Business Account *Required, but the actual gate for continuing and submitting is only hasPersonalAccount. ConnectAccountsLayout disables Next based on the personal account check, and ReviewPage blocks submission for missing personal accounts only. [!NOTE] The credit report guidance differs across the provider branches. The Plaid branch shows Max file size: 15 MB, while the validation message in both account-linking implementations rejects files only when they exceed 25 MB. Applicants can see conflicting upload limits depending on the route they enter.

frontend/app/application/page.tsx

This page collects the applicant’s name, email, phone number, country code, and consent checkboxes. It persists draft data to localStorage before routing to the passcode step, and it also detects existing draft data to offer a resume link back into account linking.

Property Type Description
resumeLink `string \ null`
name string Applicant full name input.
selectedCountry Country Selected country code and dial code from CountryCodeSelect.
email string Applicant email input.
phone string Applicant phone input, formatted as the user types.
agreeTerms boolean Consent checkbox for terms and privacy.
agreeUserAgreement boolean Consent checkbox for the user agreement.
fullNumber string Combined dial code and phone value used for persistence and routing.
isEmailValid boolean Email validation result used to enable or disable progress.
isDisabled boolean Derived state that blocks progression when required fields are missing.
Method Description
formatPhoneNumber Formats digits into grouped phone segments.
handleContinue Stores draft data in localStorage and routes the user to the passcode step.

Key behavior:

  • Prefetches the passcode route on mount.
  • Persists userFormData with fullName, email, and phone.
  • Builds the passcode URL with name, email, and phone query parameters.
  • Switches to a resume view when userFormData or connected account storage already exists.

Connect Accounts Router

frontend/app/application/connect-accounts/page.tsx

This router decides whether the user sees the Plaid branch or the SaltEdge branch. The choice is based on the normalized country and the provider query parameter.

Property Type Description
country string Normalized country key resolved from the query string.
provider `string \ undefined`
usePlaid boolean Derived branch selection.
Method Description
normalizeCountryKey Normalizes country inputs such as United States and ca into canonical keys.

Key behavior:

  • Defaults the country query parameter to us when none is present.
  • Renders pagePlaid.tsx when the country is in PLAID_COUNTRIES or provider=plaid.
  • Renders pageSalt.tsx for the SaltEdge branch otherwise.
  • Uses dynamic imports with ssr: false for both provider-specific pages.

Connect Accounts Layout

frontend/app/application/connect-accounts/components/ConnectAccountsLayout.tsx

This shared layout frames the account-linking step with a progress header, a sticky footer, and navigation controls. It is used by both provider branches and also exposes the delayed-link path.

Property Type Description
backUrl string Route used by the footer Back link.
children ReactNode Provider-specific account-linking content.
title string Page heading, defaulting to Link your accounts.
continueUrl `string \ undefined`
continueDisabled boolean Disables navigation when the underwriting prerequisite is not met.
connectLaterUrl `string \ undefined`
Method Description
ConnectAccountsLayout Renders the shell, progress indicator, footer controls, and optional Connect Later text.

Key behavior:

  • Shows StepProgress with currentStep={3}.
  • Keeps the footer fixed while content scrolls.
  • Disables the Next link by routing it to # and preventing default navigation when continueDisabled is true.
  • Surfaces the delayed-link branch via a Connect Later link and explanatory copy.

frontend/app/application/PlaidLinkButton.tsx

This client component handles Plaid Link token acquisition, OAuth redirect recovery, and success or exit callbacks. It is the only file in this funnel that directly integrates with react-plaid-link.

Property Type Description
displayVariant `'default' \ 'toggle'`
onSuccess (publicToken: string, metadata: any) => void Called after Plaid returns a public token.
onExit (err: any, metadata: any) => void Called when the user exits the Plaid flow.
onEvent (eventName: string, metadata: any) => void Receives Plaid event callbacks for logging.
accountType AccountCategory Target account bucket.
isConnecting boolean External connection-in-progress state.
setIsConnecting (isConnecting: boolean) => void Updates the parent’s connection state.
connectedAccounts { personal: ConnectedAccountSummary[]; business: ConnectedAccountSummary[]; investments: ConnectedAccountSummary[]; } Used to determine whether the button shows Connect or Change.
Method Description
fetchLinkToken Requests a Plaid Link token from the backend and stores it for OAuth recovery.
handleClick Opens Plaid Link when ready or fetches a token first.
handleReconnect Clears the visible error and retries token acquisition.
Property Type Description
AccountCategory `'personal' \ 'business' \
Property Type Description
ConnectedAccountSummary.id string Account identifier used to decide whether the button is in Connect or Change mode.
ConnectedAccountSummary.name string Human-readable account label.

Key behavior:

  • Detects a returning OAuth redirect by checking oauth_state_id in the URL.
  • Restores linkToken and receivedRedirectUri from local storage when the redirect belongs to the active account type.
  • Clears PLAID_OAUTH_TOKEN_KEY and PLAID_OAUTH_ACCOUNT_TYPE_KEY on success or exit.
  • Shows an inline error panel when token creation fails or the backend is unavailable.
  • Supports both a standard button and a compact switch display.

Plaid Connect Accounts Page

frontend/app/application/connect-accounts/pagePlaid.tsx

This branch handles Plaid-based linking, credit report upload, connected-account persistence, and the route to review. It also exposes the country-switching modal so applicants can add accounts from another country.

Property Type Description
connectingStates Record<AccountCategory, boolean> Per-category connection-in-progress flags.
plaidError `string \ null`
connectedAccounts { personal: ConnectedAccount[]; business: ConnectedAccount[]; investments: ConnectedAccount[]; } Local account buckets used across the funnel.
creditReportInputRef `HTMLInputElement \ null`
creditReportFileName `string \ null`
addCountryOpen boolean Controls the country modal.
creditReportUploadError `string \ null`
Method Description
handleCreditReportUploadClick Opens the hidden file picker.
clearCreditReportUpload Clears the selected file and resets the input element.
handleCreditReportFileChange Validates file type and size before storing the selected file name.
buildUrlWithParams Preserves email, country, and showBusiness while navigating within the funnel.
handlePlaidSuccess Resolves a successful Plaid connection, normalizes metadata, and persists connected accounts.
handlePlaidExit Clears the connecting state and records Plaid exit failures.
handlePlaidEvent Logs Plaid event callbacks.
removeAccount Removes a connected account from the selected bucket.
renderConnectedAccounts Renders the connected-account list for a bucket.
renderPersonalAccountCard Renders the personal-account card and its action control.
renderBusinessAccountCard Renders the business-account card and its action control.
cleanConnectedAccounts Removes demo and placeholder accounts before persistence.
isDemoAccount Detects demo-like account names.
isPlaceholderAccount Detects account records that do not contain meaningful financial data.
matchesDemoKeyword Checks account labels against the demo keyword list.
upsertResolvedAccounts Replaces stale connection entries with freshly resolved accounts.
AccountLogo Chooses the icon for each bucket.

Key behavior:

  • Keeps dw_application_connected_accounts and its version key synchronized with state.
  • Loads persisted accounts on mount, and clears them when the version mismatches.
  • Stores email in local storage for later resume flows.
  • Uses resolveBackendApiUrl() for backend requests and falls back to local account resolution when the backend URL is unavailable.
  • Opens the hidden credit report file input and validates PDF, JPG, and PNG uploads.
  • Shows the Connect Later link and forwards the user to pageSalt.tsx or back to the review step with query parameters intact.
  • Routes account creation and replacement through handlePlaidSuccess, which keeps only non-demo, non-placeholder records.

SaltEdge Connect Accounts Page

frontend/app/application/connect-accounts/pageSalt.tsx

This branch handles open-banking linking through SaltEdge. It creates or restores a SaltEdge customer, requests a connect session, follows the returned connect URL, and re-hydrates the customer’s connections on return.

Property Type Description
processedConnections Set<string> Tracks processed redirect states.
redirectingStates Record<AccountCategory, boolean> Per-category redirect flags.
error `string \ null`
isProcessingConnection boolean Shows the processing banner during session creation.
customerId `string \ null`
categoryOverrides Record<string, AccountCategory> Manual connection-to-bucket mapping.
connectedAccounts { personal: ConnectedAccount[]; business: ConnectedAccount[]; investments: ConnectedAccount[]; } Current account buckets.
creditReportInputRef `HTMLInputElement \ null`
creditReportFileName `string \ null`
creditReportUploadError `string \ null`
addCountryOpen boolean Controls the country modal.
overridesLoaded boolean Tracks whether category overrides have been loaded.
Method Description
handleCreditReportUploadClick Opens the hidden file picker.
clearCreditReportUpload Resets the selected credit report file.
handleCreditReportFileChange Validates file type and size before accepting a credit report.
buildUrlWithParams Preserves email, country, and showBusiness while navigating.
fetchApiWithFallback Tries multiple candidate URLs when calling backend SaltEdge endpoints.
cleanupReturnParams Removes SaltEdge redirect markers from the browser URL after return.
fetchAllConnections Loads and categorizes SaltEdge connections for the stored customer.
startSaltEdgeConnect Creates or reuses a SaltEdge session and starts the redirect flow.
startOpenBankingConnect Chooses the correct branch, including the EU client redirect path for existing personal accounts.

Key behavior:

  • Defaults the country to us and calculates isEuFlow using the country set.
  • Uses getDefaultOpenBankingProviderForCountry(country) to determine the label of the redirect flow.
  • Stores userFormData with email, nationality, and businessOwnership before leaving the page.
  • Uses window.location.href for SaltEdge redirects rather than router.push.
  • Handles unsupported-country responses by sending the user to a manual credit-upload fallback path.
  • Allows adding another country via AddCountryModal, which reloads the page with a new country query parameter.

Connect Later Page

frontend/app/application/connect-later/page.tsx

This page is the delayed-link branch. It preserves the applicant’s context and returns them to account linking later without losing the application draft.

Property Type Description
connectAccountsUrl string Resume URL returned to the account-linking step.
Method Description
ConnectLaterContent Builds the return link from the current query string and renders the delayed-link message.
ConnectLaterPage Wraps the content in Suspense with a loading fallback.

Key behavior:

  • Preserves email, country, showBusiness, and provider.
  • Returns users to /application/connect-accounts with the same query context.
  • Presents the same draft-preservation message used by the Connect Later link in ConnectAccountsLayout.

Review Page

frontend/app/application/review/page.tsx

This is the final validation and submission step. It loads cleaned draft state, ensures the applicant has at least one personal account, and sends the final application payload to the backend.

Property Type Description
connectedAccounts { personal: ConnectedAccount[]; business: ConnectedAccount[]; investments: ConnectedAccount[]; } Cleaned account buckets loaded from local storage.
storedForm `StoredFormData \ null`
submitError `string \ null`
isSubmitting boolean Controls submission in progress state.
Method Description
buildUrlWithParams Preserves email, country, phone, and showBusiness for internal navigation.
handleSubmit Validates the personal-account prerequisite, posts the application, stores the reference, and routes to confirmation.
cleanConnectedAccounts Removes demo and placeholder accounts from each bucket before submission.
isPlaceholderAccount Detects account records that are too sparse to count as real connections.

Key behavior:

  • Rejects submission immediately when no personal account is connected.
  • Reads dw_application_connected_accounts and clears stale storage when the version no longer matches.
  • Clears SALTEDGE_CUSTOMER_STORAGE_KEY and CONNECTION_CATEGORY_STORAGE_KEY when the account cache is invalid or empty.
  • Reads userFormData and builds the final applicant display values.
  • Assembles a submission payload that includes:
    • email
    • phone
    • country
    • employment_status
    • financing_consent
    • full_name
    • agree_policy
    • receive_updates
    • connected_accounts
    • created_at
    • metadata.application_reference
    • metadata.residence_permit_number
  • Stores the generated application reference in dw_application_reference after a successful POST.
  • Routes to /application/confirm with reference and submittedAt query parameters.

Confirm Page

frontend/app/application/confirm/page.tsx

This page is the final receipt screen. It shows the application reference, submission date, and a short list of what happens next.

Property Type Description
reference string The persisted application reference shown to the user.
Method Description
formatSubmissionDate Converts the submittedAt query parameter into a readable date string.
generateApplicationReference Creates an AP_ reference using crypto.getRandomValues when available.
ConfirmPage Resolves the reference from query, local storage, or a generated fallback.

Key behavior:

  • Pulls reference from the query string first, then from dw_application_reference, then generates a new value.
  • Stores the reference back to local storage whenever it is resolved.
  • Falls back to June 11, 2026 when submittedAt is missing.
  • Keeps the reference display stable across refreshes.

Confirm Layout

frontend/app/application/confirm/layout.tsx

This layout only supplies metadata for the confirmation screen.

Property Type Description
metadata.title string Sign up for Lita
metadata.description string Your housing application has been submitted successfully.

Review Layout

frontend/app/application/review/layout.tsx

This layout only supplies metadata for the review screen.

Property Type Description
metadata.title string Sign up for Lita
metadata.description string Review your application information and submit your Lita application.

2. Supporting Route Targets

These route targets are part of the funnel flow but do not have source bodies in the provided context:

  • /application/passcode — the next route after applicant details are entered.
  • /application/employment — a route target used by the review and back-navigation links.
  • /application/connect-accounts — the main account-linking route.
  • /application/connect-later — the delayed-link branch.
  • /application/confirm — the final confirmation screen.

State Management and Storage

Browser Storage Keys

Key Used By Purpose
userFormData page.tsx, pagePlaid.tsx, pageSalt.tsx, review/page.tsx Draft applicant data and form continuity.
email page.tsx, pagePlaid.tsx, pageSalt.tsx Email reused across resume and account-linking routes.
dw_application_connected_accounts pagePlaid.tsx, review/page.tsx Serialized connected account buckets.
dw_application_connected_accounts_version pagePlaid.tsx, review/page.tsx Version gate for the connected-account cache.
dw_application_reference confirm/page.tsx, review/page.tsx Persisted application receipt reference.
PLAID_OAUTH_TOKEN_KEY PlaidLinkButton.tsx Stores Plaid Link token for OAuth redirect recovery.
PLAID_OAUTH_ACCOUNT_TYPE_KEY PlaidLinkButton.tsx Tracks the account type during Plaid OAuth redirect recovery.
SALTEDGE_CUSTOMER_STORAGE_KEY pageSalt.tsx, review/page.tsx SaltEdge customer ID persistence.
CONNECTION_CATEGORY_STORAGE_KEY pageSalt.tsx, review/page.tsx Remembers account category assignments.

Draft and Submission Lifecycle

  1. ApplicationPage writes applicant details into userFormData.
  2. The account-link step writes connected accounts and provider-specific state into browser storage.
  3. ReviewPage reloads and sanitizes the draft, then enforces the personal-account prerequisite.
  4. Successful submission generates and stores dw_application_reference.
  5. ConfirmPage reads the reference from the query string or local storage and shows it back to the user.

Decision Points

Decision Point Condition Outcome
Provider selection country is in PLAID_COUNTRIES or provider=plaid Load pagePlaid.tsx.
Provider selection Otherwise Load pageSalt.tsx.
Continue from connect-accounts connectedAccounts.personal.length > 0 Enable Next.
Continue from connect-accounts No personal account Disable Next.
Submit from review connectedAccounts.personal.length > 0 Send the final POST request.
Submit from review No personal account Show a validation error and stop.
Delay linking User clicks Connect Later Route to /application/connect-later.
Final confirmation reference Query parameter, then storage, then generation Persist and display the reference.

API Integration

{
    "title": "Create Plaid Link Token",
    "description": "Starts the Plaid account-link flow by requesting a Link token from the backend.",
    "method": "GET",
    "baseUrl": "<BackendApiUrl>",
    "endpoint": "/api/plaid/create_link_token",
    "headers": [],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Returns a Plaid Link token",
            "body": "{\n    \"link_token\": \"link-sandbox-0f2a1b3c4d5e6f7g\"\n}"
        }
    }
}

Create SaltEdge Connect Session

{
    "title": "Create SaltEdge Connect Session",
    "description": "Creates a SaltEdge connect session and returns the redirect URL used to start the open-banking flow.",
    "method": "POST",
    "baseUrl": "<BackendApiUrl>",
    "endpoint": "/api/saltedge/v6/connect-session",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"customer_id\": \"cust_123456\",\n    \"return_to\": \"https://app.joinlita.com/application/connect-accounts?saltedge_redirect=true&category=personal&country=us&[email protected]&showBusiness=true\",\n    \"consent_scopes\": [\n        \"accounts\",\n        \"transactions\",\n        \"holder_info\"\n    ],\n    \"categorization\": \"personal\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Returns the SaltEdge connect URL",
            "body": "{\n    \"connect_url\": \"https://connect.saltedge.com/session/abc123\"\n}"
        }
    }
}

List SaltEdge Connections

{
    "title": "List SaltEdge Connections",
    "description": "Loads the current SaltEdge connections for a customer so the UI can populate the personal, business, and investment buckets.",
    "method": "GET",
    "baseUrl": "<BackendApiUrl>",
    "endpoint": "/api/saltedge/customer/{customerId}/connections",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "customerId",
            "value": "cust_123456",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Returns customer connections",
            "body": "{\n    \"connections\": [\n        {\n            \"id\": \"con_12345\",\n            \"categorization\": \"personal\"\n        }\n    ]\n}"
        }
    }
}

Submit Application

{
    "title": "Submit Application",
    "description": "Posts the completed application from the review screen to the backend and triggers the confirmation route after a successful response.",
    "method": "POST",
    "baseUrl": "<NextJsAppBaseUrl>",
    "endpoint": "/api/v1/applications",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        },
        {
            "key": "Accept",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"email\": \"[email protected]\",\n    \"phone\": \"+1 512 555 0101\",\n    \"country\": \"us\",\n    \"employment_status\": \"employee\",\n    \"financing_consent\": \"granted\",\n    \"full_name\": \"Jane Doe\",\n    \"agree_policy\": true,\n    \"receive_updates\": true,\n    \"connected_accounts\": {\n        \"personal\": [\n            {\n                \"id\": \"acct_1001\",\n                \"name\": \"Main Checking\",\n                \"type\": \"depository\",\n                \"mask\": \"4321\",\n                \"connectionId\": \"conn_1001\"\n            }\n        ],\n        \"business\": [\n            {\n                \"id\": \"acct_2001\",\n                \"name\": \"Lita Holdings\",\n                \"type\": \"business\",\n                \"mask\": \"8899\",\n                \"connectionId\": \"conn_2001\"\n            }\n        ],\n        \"investments\": [\n            {\n                \"id\": \"acct_3001\",\n                \"name\": \"Brokerage\",\n                \"type\": \"investment\",\n                \"mask\": \"7788\",\n                \"connectionId\": \"conn_3001\"\n            }\n        ]\n    },\n    \"created_at\": \"2026-04-26T12:00:00.000Z\",\n    \"metadata\": {\n        \"application_reference\": \"AP_1A2B3C4\",\n        \"residence_permit_number\": \"RP-998877\"\n    }\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Application stored successfully",
            "body": "[]"
        }
    }
}

Feature Flows

1. Applicant Details to Passcode and Resume Flow

sequenceDiagram
    participant U as Applicant
    participant A as Application Page
    participant LS as Browser Storage
    participant R as Router

    U->>A: Enter name email phone and consents
    A->>A: formatPhoneNumber
    A->>A: validate required fields
    U->>A: Click Next
    A->>LS: Save userFormData
    A->>R: push application passcode route

    LS-->>A: Resume state exists later
    A->>A: Render resume link
    U->>A: Click Connect Bank Account
    A->>R: push application connect accounts route
sequenceDiagram
    participant U as Applicant
    participant C as Connect Accounts Router
    participant P as Plaid Branch
    participant S as SaltEdge Branch
    participant L as Connect Later Page
    participant LS as Browser Storage
    participant B as Backend API

    U->>C: Open connect accounts route
    C->>C: normalizeCountryKey
    C->>C: Choose Plaid or SaltEdge branch

    alt Plaid branch
        C->>P: Load pagePlaid
        U->>P: Start link flow
        P->>B: GET api plaid create link token
        B-->>P: link_token
        P->>LS: Store Plaid OAuth state
        P->>P: Open Plaid Link
        U->>P: Finish or exit flow
        P->>LS: Persist connected accounts
    else SaltEdge branch
        C->>S: Load pageSalt
        U->>S: Start connect session
        S->>B: POST api saltedge connect session
        B-->>S: connect_url
        S->>U: Redirect to provider
        U->>S: Return from redirect
        S->>B: GET api saltedge customer connections
        B-->>S: connections
        S->>LS: Persist connected accounts
    end

    U->>L: Click Connect Later
    L->>LS: Preserve query context
    L->>C: Return to connect accounts route later

3. Review Submission and Confirmation Flow

sequenceDiagram
    participant U as Applicant
    participant V as Review Page
    participant LS as Browser Storage
    participant B as Backend API
    participant C as Confirm Page

    V->>LS: Load connected accounts and draft form
    V->>V: cleanConnectedAccounts
    V->>V: Check personal account prerequisite

    alt No personal account
        V-->>U: Show submit error
    else Personal account present
        U->>V: Submit application
        V->>B: POST api v1 applications
        B-->>V: Success
        V->>LS: Save dw_application_reference
        V->>C: push application confirm route
        C->>LS: Read or generate reference
        C-->>U: Show submission receipt and date
    end

State Management

Funnel State Pattern

  • Draft capture: page.tsx stores applicant details in userFormData before route changes.
  • Linking state: pagePlaid.tsx and pageSalt.tsx keep account buckets in browser storage and rehydrate them on load.
  • Provider selection: page.tsx chooses the provider from country and provider query parameters.
  • Submission gate: review/page.tsx requires at least one personal account before sending the final payload.
  • Receipt continuity: confirm/page.tsx keeps the reference stable across refreshes by reading from dw_application_reference.

Query Parameter Propagation

The funnel preserves the following query parameters where relevant:

  • email
  • country
  • phone
  • showBusiness
  • provider
  • reference
  • submittedAt

These parameters keep the browser flow aligned with the stored draft and the final confirmation display.

Error Handling

The funnel uses local validation and inline error state rather than generic redirects.

  • ApplicationPage disables progression until the name, phone, email, and checkboxes are valid.
  • PlaidLinkButton shows an alert when it cannot create a link token or when Plaid exits with an error.
  • pagePlaid.tsx surfaces file validation errors for credit report uploads and connection errors for the provider flow.
  • pageSalt.tsx surfaces provider errors, unsupported-country fallback logic, and upload validation errors.
  • ReviewPage catches failed submission responses, uses backend detail text when available, and falls back to a generic error message.
  • ConfirmPage tolerates missing or malformed dates and references by falling back to storage or generated values.

Integration Points

  • ApplicationStepLayout frames the initial details step and the delayed resume view.
  • CountryCodeSelect and AgreementCheckbox are part of the initial application capture.
  • StepProgress renders the current application step in ConnectAccountsLayout.
  • AddCountryModal extends the account-linking flow to additional countries.
  • react-plaid-link powers the Plaid branch.
  • resolveBackendApiUrl and getConfiguredBackendApiUrl supply backend addresses for the connection flows.
  • localStorage is the primary draft persistence layer until the final POST request succeeds.
  • ReviewFormContent and ReviewPageShell receive the data assembled in review/page.tsx and drive the final submit UI.

Testing Considerations

  • Verify that ApplicationPage blocks Next when either consent checkbox is unchecked or the email format is invalid.
  • Verify that a saved draft causes the resume view to appear and that the resume link points back into account linking.
  • Verify that ConnectAccountsRouter selects Plaid for supported countries or provider=plaid, and SaltEdge otherwise.
  • Verify that ConnectAccountsLayout disables Next when no personal account exists.
  • Verify that the connect-later branch preserves email, country, showBusiness, and provider.
  • Verify that the Plaid branch stores and clears OAuth recovery values correctly.
  • Verify that the SaltEdge branch can restore and categorize connections after redirect.
  • Verify that invalid credit report types or oversize files clear the input and surface the validation message.
  • Verify that ReviewPage refuses submission without a personal account and that successful submission stores dw_application_reference.
  • Verify that ConfirmPage shows the stored reference after refresh and uses the expected fallback date formatting when submittedAt is absent.

Key Classes Reference

Class Responsibility
page.tsx Captures applicant details, stores the draft, and routes into the application funnel.
page.tsx Chooses the account-linking provider branch from route context.
ConnectAccountsLayout.tsx Provides the shared step frame, navigation footer, and delayed-link entry point.
PlaidLinkButton.tsx Handles Plaid Link token acquisition, OAuth recovery, and result callbacks.
pagePlaid.tsx Manages the Plaid account-link branch, credit report upload, and connected-account persistence.
pageSalt.tsx Manages the SaltEdge branch, customer session flow, and connection hydration.
page.tsx Renders the delayed-link confirmation page and returns the user to account linking later.
page.tsx Validates the final review payload, posts the application, and routes to confirmation.
page.tsx Displays the submitted application reference and submission date.
layout.tsx Supplies review metadata for the route.
layout.tsx Supplies confirmation metadata for the route.