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
showBusinessis true, the business card label saysBusiness Account *Required, but the actual gate for continuing and submitting is onlyhasPersonalAccount.ConnectAccountsLayoutdisablesNextbased on the personal account check, andReviewPageblocks submission for missing personal accounts only. [!NOTE] The credit report guidance differs across the provider branches. The Plaid branch showsMax file size: 15 MB, while the validation message in both account-linking implementations rejects files only when they exceed25 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
userFormDatawithfullName,email, andphone. - Builds the passcode URL with
name,email, andphonequery parameters. - Switches to a resume view when
userFormDataor 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
uswhen none is present. - Renders
pagePlaid.tsxwhen the country is inPLAID_COUNTRIESorprovider=plaid. - Renders
pageSalt.tsxfor the SaltEdge branch otherwise. - Uses dynamic imports with
ssr: falsefor 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
StepProgresswithcurrentStep={3}. - Keeps the footer fixed while content scrolls.
- Disables the Next link by routing it to
#and preventing default navigation whencontinueDisabledis true. - Surfaces the delayed-link branch via a Connect Later link and explanatory copy.
Plaid Link Button
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_idin the URL. - Restores
linkTokenandreceivedRedirectUrifrom local storage when the redirect belongs to the active account type. - Clears
PLAID_OAUTH_TOKEN_KEYandPLAID_OAUTH_ACCOUNT_TYPE_KEYon 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_accountsand its version key synchronized with state. - Loads persisted accounts on mount, and clears them when the version mismatches.
- Stores
emailin 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 Laterlink and forwards the user topageSalt.tsxor 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
usand calculatesisEuFlowusing the country set. - Uses
getDefaultOpenBankingProviderForCountry(country)to determine the label of the redirect flow. - Stores
userFormDatawithemail,nationality, andbusinessOwnershipbefore leaving the page. - Uses
window.location.hreffor SaltEdge redirects rather thanrouter.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 newcountryquery 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, andprovider. - Returns users to
/application/connect-accountswith 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_accountsand clears stale storage when the version no longer matches. - Clears
SALTEDGE_CUSTOMER_STORAGE_KEYandCONNECTION_CATEGORY_STORAGE_KEYwhen the account cache is invalid or empty. - Reads
userFormDataand builds the final applicant display values. - Assembles a submission payload that includes:
emailphonecountryemployment_statusfinancing_consentfull_nameagree_policyreceive_updatesconnected_accountscreated_atmetadata.application_referencemetadata.residence_permit_number
- Stores the generated application reference in
dw_application_referenceafter a successful POST. - Routes to
/application/confirmwithreferenceandsubmittedAtquery 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
referencefrom the query string first, then fromdw_application_reference, then generates a new value. - Stores the reference back to local storage whenever it is resolved.
- Falls back to
June 11, 2026whensubmittedAtis 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
ApplicationPagewrites applicant details intouserFormData.- The account-link step writes connected accounts and provider-specific state into browser storage.
ReviewPagereloads and sanitizes the draft, then enforces the personal-account prerequisite.- Successful submission generates and stores
dw_application_reference. ConfirmPagereads 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
Create Plaid Link Token
{
"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
2. Account Link Branching and Delayed Return Flow
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.tsxstores applicant details inuserFormDatabefore route changes. - Linking state:
pagePlaid.tsxandpageSalt.tsxkeep account buckets in browser storage and rehydrate them on load. - Provider selection:
page.tsxchooses the provider fromcountryandproviderquery parameters. - Submission gate:
review/page.tsxrequires at least one personal account before sending the final payload. - Receipt continuity:
confirm/page.tsxkeeps the reference stable across refreshes by reading fromdw_application_reference.
Query Parameter Propagation
The funnel preserves the following query parameters where relevant:
emailcountryphoneshowBusinessproviderreferencesubmittedAt
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.
ApplicationPagedisables progression until the name, phone, email, and checkboxes are valid.PlaidLinkButtonshows an alert when it cannot create a link token or when Plaid exits with an error.pagePlaid.tsxsurfaces file validation errors for credit report uploads and connection errors for the provider flow.pageSalt.tsxsurfaces provider errors, unsupported-country fallback logic, and upload validation errors.ReviewPagecatches failed submission responses, uses backenddetailtext when available, and falls back to a generic error message.ConfirmPagetolerates missing or malformed dates and references by falling back to storage or generated values.
Integration Points
ApplicationStepLayoutframes the initial details step and the delayed resume view.CountryCodeSelectandAgreementCheckboxare part of the initial application capture.StepProgressrenders the current application step inConnectAccountsLayout.AddCountryModalextends the account-linking flow to additional countries.react-plaid-linkpowers the Plaid branch.resolveBackendApiUrlandgetConfiguredBackendApiUrlsupply backend addresses for the connection flows.localStorageis the primary draft persistence layer until the final POST request succeeds.ReviewFormContentandReviewPageShellreceive the data assembled inreview/page.tsxand drive the final submit UI.
Testing Considerations
- Verify that
ApplicationPageblocksNextwhen 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
ConnectAccountsRouterselects Plaid for supported countries orprovider=plaid, and SaltEdge otherwise. - Verify that
ConnectAccountsLayoutdisablesNextwhen no personal account exists. - Verify that the connect-later branch preserves
email,country,showBusiness, andprovider. - 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
ReviewPagerefuses submission without a personal account and that successful submission storesdw_application_reference. - Verify that
ConfirmPageshows the stored reference after refresh and uses the expected fallback date formatting whensubmittedAtis 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. |