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 type label from the backend payload for each connected account record.
  • When the backend omits type, the UI falls back to the generic label account.
  • There are no hard-coded account type labels such as Trifecta in the current implementation.
  • The label derivation is handled by normalizeConnectedAccounts in frontend/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 account label.

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_accounts and validates the stored version against dw_application_connected_accounts_version.
  • Clears dw_application_connected_accounts, the version key, dw_application_saltedge_customer_id, and dw_application_saltedge_category_overrides when the stored version does not match 7.
  • 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 connected
    • No business accounts connected
    • investment accounts are omitted entirely when empty
    • John Smith for applicant name
    • Not provided for 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_KEYWORDS list.
  • Placeholder filtering rejects records that lack all of:
    • connectionId
    • accountId or id
    • mask
    • availableBalance or currentBalance
    • status

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

  1. The page reads connected-account storage and the version key.
  2. A version mismatch triggers full cleanup of the connected-account and Salt Edge keys.
  3. Valid account data is parsed and passed through cleanConnectedAccounts.
  4. The page reads userFormData and derives display fields from stored values or query parameters.
  5. 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

  1. The page checks hasPersonalAccount.
  2. If no personal account is present, submission is blocked and an error is shown.
  3. If submission proceeds, the page builds a payload containing:
    • applicant identity fields
    • connected_accounts
    • created_at
    • metadata.application_reference
    • metadata.residence_permit_number
  4. The page posts the payload to /api/v1/applications.
  5. 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.

  • connectedAccounts is initialized from a versioned local cache.
  • storedForm is initialized from the userFormData cache.
  • isSubmitting and submitError control 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 normalizeConnectedAccounts to derive type labels from backend payloads.
  • /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
  • Version mismatches:
    • clear connected-account and Salt Edge keys
  • Submission without personal accounts:
    • sets submitError
    • aborts submission
  • 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/navigation
    • useRouter
    • useSearchParams
  • React state and effect hooks
  • Browser localStorage
  • Browser crypto.getRandomValues
  • The application submission route at /api/v1/applications
  • ReviewPageShell and ReviewFormContent
    • receive the derived display props from ReviewPage

Testing Considerations

The code supports the following verification points:

  • dw_application_connected_accounts_version mismatch clears connected-account state.
  • Demo accounts are filtered out before summaries are built.
  • Placeholder records with no identifying or balance fields are filtered out.
  • hasPersonalAccount must gate submission.
  • Missing name, phone, and permit values fall back to the documented display text.
  • Empty business accounts render the No business accounts connected message.
  • 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.