User Dashboard Domain - Feature Availability and Display Semantics
Overview
This section covers how the user-facing dashboard and application review surfaces decide what to show, what to hide, and which fallback values to use when dashboard data is incomplete. The documented behavior centers on connected-account rendering, account-type labeling, and the review-page logic that reconstructs application state from browser storage before allowing submission.
A key product rule is that connected-account labels are not hard-coded in the UI. The dashboard consumes the backend payload for each connected account and falls back to the generic label account when the payload does not supply a type. That keeps the display aligned with upstream data sources and avoids embedding provider-specific labels in the frontend.
On the review surface, the UI also filters out demo and placeholder accounts, reconstructs stored form data, and blocks submission until at least one personal account is connected. The result is a stricter presentation layer that only surfaces data the user can act on, while preserving the backend-driven semantics used elsewhere in the dashboard domain.
Architecture Overview
flowchart TB
subgraph ProductNotes [Product Semantics]
FeatureAvailability[feature availability notes]
end
subgraph Presentation [Presentation Layer]
ReviewPage[ReviewPage]
ConnectedAccountHelpers[Connected account helpers]
end
subgraph BrowserState [Browser State]
LocalStorage[localStorage keys]
QueryParams[URL query params]
end
subgraph BackendApi [Backend API]
ApplicationsPost[POST api v1 applications]
end
FeatureAvailability --> ReviewPage
QueryParams --> ReviewPage
LocalStorage --> ReviewPage
ReviewPage --> LocalStorage
ReviewPage --> ApplicationsPost
ApplicationsPost --> ReviewPage
Feature Availability Semantics
File: documents/feature-availability.md
The feature availability note defines the dashboard contract for connected-account labels:
- The dashboard derives the connected account
typelabel from the backend payload for each connected account record. - When the backend omits
type, the UI falls back to the generic labelaccount. - There are no hard-coded account type labels such as
Trifectain the current implementation. - The label derivation is handled by
normalizeConnectedAccountsinfrontend/app/dashboard/page.tsx.
Component Structure
1. Presentation Layer
ReviewPage (frontend/app/application/review/page.tsx)
[!IMPORTANT] The documented product rule is backend-driven labeling, not frontend-enforced provider naming. If the payload does not provide a type, the UI renders the generic
accountlabel.
The review page is the main display surface in this section. It reads stored account and form data from browser storage, filters out unusable connected-account records, computes fallback display strings, and submits the completed application payload.
Key responsibilities
- Load connected accounts from
localStorage. - Enforce storage versioning with
CONNECTED_ACCOUNTS_STORAGE_VERSION. - Remove demo and placeholder accounts before rendering.
- Rehydrate stored form values and derive display fallbacks.
- Block submission when no personal account is present.
- Submit the application payload to
/api/v1/applications.
State shape
| Property | Type | Description |
|---|---|---|
connectedAccounts |
typeof emptyConnectedAccounts |
Partitioned account buckets for personal, business, and investments. |
storedForm |
`StoredFormData \ | null` |
submitError |
`string \ | null` |
isSubmitting |
boolean |
Submission in progress flag. |
Component responsibilities and behavior
- Reads
dw_application_connected_accountsand validates the stored version againstdw_application_connected_accounts_version. - Clears
dw_application_connected_accounts, the version key,dw_application_saltedge_customer_id, anddw_application_saltedge_category_overrideswhen the stored version does not match7. - Removes demo and placeholder entries before they reach the visible account summary.
- Builds display strings from account names only.
- Uses fallback strings when no data is available:
No personal accounts connectedNo business accounts connected- investment accounts are omitted entirely when empty
John Smithfor applicant nameNot providedfor missing phone and residence permit values
- Prevents submission unless at least one personal account remains after filtering.
- Serializes the submission payload and posts it to
/api/v1/applications.
Key methods
| Method | Description | Returns |
|---|---|---|
ReviewPage |
Renders the review surface, restores state from browser storage, and submits the completed application. | JSX.Element |
Helper Functions (frontend/app/application/review/page.tsx)
These functions control normalization, fallback behavior, and account filtering.
| Method | Description | Returns |
|---|---|---|
generateApplicationReference |
Creates a compact AP_-prefixed application reference using crypto.getRandomValues when available, with a Math.random fallback. |
string |
toOptionalString |
Converts strings, numbers, and booleans to trimmed string values and returns undefined for empty or unsupported values. |
`string \ |
matchesDemoKeyword |
Detects demo-style labels using keywords such as demo, fake, sample, test, sandbox, example, placeholder, and dummy. |
boolean |
isDemoAccount |
Flags accounts whose connectionName, name, or provider contains a demo keyword. |
boolean |
isPlaceholderAccount |
Flags accounts that do not expose identifying or balance fields. | boolean |
cleanConnectedAccounts |
Filters demo and placeholder accounts out of the personal, business, and investments buckets. |
{ personal: ConnectedAccount[]; business: ConnectedAccount[]; investments: ConnectedAccount[] } |
ConnectedAccount (frontend/app/application/review/page.tsx)
This interface defines the connected-account shape the review page consumes from browser storage.
| Property | Type | Description |
|---|---|---|
id |
string |
Local account identifier used by the UI. |
name |
string |
Display name shown in the review page summaries. |
type |
`string \ | null \ |
connectionName |
`string \ | null \ |
provider |
`string \ | null \ |
mask |
`string \ | null \ |
connectionId |
`string \ | null \ |
accountId |
`string \ | null \ |
availableBalance |
`number \ | null \ |
currentBalance |
`number \ | null \ |
status |
`string \ | null \ |
StoredFormData (frontend/app/application/review/page.tsx)
This interface captures the stored form state the review page reuses when building the final submission payload.
| Property | Type | Description |
|---|---|---|
email |
`string \ | null \ |
nationality |
`string \ | null \ |
businessOwnership |
`string \ | null \ |
residencePermitNumber |
`string \ | null \ |
agreeTerms |
`boolean \ | null \ |
agreeUserAgreement |
`boolean \ | null \ |
metadata |
`Record<string, unknown> \ | null \ |
Dashboard connected-account label semantics (frontend/app/dashboard/page.tsx)
The dashboard-facing normalization rule documented in documents/feature-availability.md is:
| Method | Description | Returns |
|---|---|---|
normalizeConnectedAccounts |
Derives connected-account labels from backend payload fields and falls back to account when the payload omits a type. |
Normalized connected-account records |
2. Display Semantics
Connected account filtering
The review page does not render every stored account record. It removes accounts that look like demo data or placeholders before building the visible summaries.
- Demo filtering uses the
DEMO_ACCOUNT_KEYWORDSlist. - Placeholder filtering rejects records that lack all of:
connectionIdaccountIdoridmaskavailableBalanceorcurrentBalancestatus
Display fallback values
The page uses deterministic fallback values when the stored data is incomplete.
| Field | Fallback |
|---|---|
| Applicant name | John Smith |
| Applicant phone | Not provided |
| Residence permit number | Not provided |
| Personal accounts summary | No personal accounts connected |
| Business accounts summary | No business accounts connected |
| Investment accounts summary | omitted when empty |
Submission gating
The user cannot submit unless connectedAccounts.personal contains at least one account after filtering. If that condition fails, the page sets submitError to:
Connect at least one personal account before submitting.
3. Browser Storage Contract
Storage keys
| Key | Purpose | Invalidation behavior |
|---|---|---|
dw_application_connected_accounts |
Stores partitioned connected-account buckets. | Cleared when the version key does not equal 7 or when parsing fails. |
dw_application_connected_accounts_version |
Tracks the shape/version of the connected-account payload. | Must equal 7; otherwise connected-account data and related Salt Edge keys are removed. |
dw_application_saltedge_customer_id |
Stores the Salt Edge customer reference used during onboarding. | Cleared with the connected-account version reset. |
dw_application_saltedge_category_overrides |
Stores connection category overrides. | Cleared with the connected-account version reset. |
userFormData |
Stores applicant form details reused by the review screen. | Cleared only when parsing fails. |
dw_application_reference |
Stores the generated application reference after successful submission. | Written after a successful POST to /api/v1/applications. |
Feature Flows
1. Review Page Initialization
sequenceDiagram
participant U as User
participant P as ReviewPage
participant S as localStorage
U->>P: Open review screen
P->>S: getItem dw_application_connected_accounts
P->>S: getItem dw_application_connected_accounts_version
alt version mismatch
P->>S: remove connected account keys
P->>S: remove Salt Edge keys
else version matches
P->>P: parse and clean connected accounts
end
P->>S: getItem userFormData
P->>P: derive applicant display values and fallback labels
P-->>U: Render review surface
[!NOTE] The review page treats browser storage as a versioned cache. A version mismatch forces a full reset of the connected-account state and the associated Salt Edge identifiers.
Initialization flow
- The page reads connected-account storage and the version key.
- A version mismatch triggers full cleanup of the connected-account and Salt Edge keys.
- Valid account data is parsed and passed through
cleanConnectedAccounts. - The page reads
userFormDataand derives display fields from stored values or query parameters. - The UI renders with the filtered accounts and computed fallback labels.
2. Application Submission
sequenceDiagram
participant U as User
participant P as ReviewPage
participant S as localStorage
participant A as api v1 applications
participant R as Router
U->>P: Click submit
alt no personal accounts
P-->>U: Show submit error
else personal account exists
P->>P: set isSubmitting true
P->>A: POST submission payload
A-->>P: Success response
P->>S: setItem dw_application_reference
P->>R: push application confirm route
R-->>U: Navigate to confirmation
end
Submission flow
- The page checks
hasPersonalAccount. - If no personal account is present, submission is blocked and an error is shown.
- If submission proceeds, the page builds a payload containing:
- applicant identity fields
connected_accountscreated_atmetadata.application_referencemetadata.residence_permit_number
- The page posts the payload to
/api/v1/applications. - On success, it stores the generated application reference and routes the user to
/application/confirm.
State Management
Browser-state pattern
The user-dashboard domain in this section uses browser storage as the primary state boundary.
connectedAccountsis initialized from a versioned local cache.storedFormis initialized from theuserFormDatacache.isSubmittingandsubmitErrorcontrol submission feedback.- Query parameters are preserved when navigating back and forth between application steps.
UI states
| State | Trigger | User-visible result |
|---|---|---|
| Initial | Component first mounts | Storage is read and cleaned before render. |
| Ready | Valid accounts and stored form are present | The review screen shows applicant details and account summaries. |
| Blocked | No personal account remains after filtering | Submission is rejected with a validation message. |
| Submitting | Submit action started | The page shows in-flight submission state. |
| Error | POST fails or storage parsing fails | The page surfaces a submit or parse error and stops the current flow. |
Integration Points
documents/feature-availability.md- Defines the backend-driven connected-account type-label rule.
frontend/app/application/review/page.tsx- Filters visible connected accounts and applies fallback values.
frontend/app/dashboard/page.tsx- Uses
normalizeConnectedAccountsto derive type labels from backend payloads.
- Uses
/api/v1/applications- Receives the application submission built from the review page.
Error Handling
The review page uses deterministic cleanup and user-facing messages rather than silent failures.
- Storage parse failures:
- logged to
console.error - clear the affected storage key
- logged to
- Version mismatches:
- clear connected-account and Salt Edge keys
- Submission without personal accounts:
- sets
submitError - aborts submission
- sets
- POST failure:
- reads the error payload when available
- falls back to
Unable to finalise your application. Please try again.
if (!hasPersonalAccount) {
setSubmitError("Connect at least one personal account before submitting.")
return
}
Caching Strategy
The dashboard-domain caching pattern here is browser storage with explicit versioning.
| Cache key | Type | Invalidated by |
|---|---|---|
dw_application_connected_accounts |
Connected-account cache | Version mismatch or parse failure |
dw_application_connected_accounts_version |
Cache version marker | Replaced by future schema revisions |
dw_application_saltedge_customer_id |
Connected-account related cache | Version mismatch |
dw_application_saltedge_category_overrides |
Connected-account related cache | Version mismatch |
userFormData |
Form state cache | Parse failure |
dw_application_reference |
Successful submission marker | Overwritten by the next successful submission |
Dependencies
next/navigationuseRouteruseSearchParams
- React state and effect hooks
- Browser
localStorage - Browser
crypto.getRandomValues - The application submission route at
/api/v1/applications ReviewPageShellandReviewFormContent- receive the derived display props from
ReviewPage
- receive the derived display props from
Testing Considerations
The code supports the following verification points:
dw_application_connected_accounts_versionmismatch clears connected-account state.- Demo accounts are filtered out before summaries are built.
- Placeholder records with no identifying or balance fields are filtered out.
hasPersonalAccountmust gate submission.- Missing name, phone, and permit values fall back to the documented display text.
- Empty business accounts render the
No business accounts connectedmessage. - Empty investment accounts are omitted from the display rather than rendered as an empty label.
Key Classes Reference
| Class | Responsibility |
|---|---|
feature-availability.md |
Documents the backend-driven connected-account type-label rule and its generic fallback. |
page.tsx |
Rehydrates review-state data, filters connected accounts, applies fallback labels, and submits the application payload. |
page.tsx |
Implements the product semantics that keep dashboard-visible data aligned with backend payloads rather than hard-coded UI labels. |