Desktop (home dashboard)

Platform & Access · Desktop (home dashboard)

The landing screen after login. It renders whichever dashboard is configured with category: 'home' — a custom panel, the data-quality panel or an embedded external URL — and nudges moderators when receipts are waiting.

Area	Platform & Access
Routes	index
Centre modules	always available
Staff levels	admin · manager · crmmanager
Models	dashboard · receipt
UI label	title.header.desktop
Coverage	3 use cases · 2 happy · 4 failure

Known issues (1)

• 🔵 Low — Desktop receipts query has no catch

How it works

beforeModel re-runs auth.load() because dashboards and the centre are often not in the store yet right after login. The panel value is validated against enums/dashboard-panels into isValidDashboard, and the controller branches on isCustomDashboard / isExternalUrlDashboard. For external-URL dashboards the page header is hidden (pageHeader.isHidden) and restored in deactivate. The pending-receipts modal is gated on a canShowReceiptsModal sessionStorage flag and shown once, 3 seconds after load, only if the query returns at least one pending receipt.

Use cases

Why someone opens this (3)

• A CRM manager landing on registration-quality KPIs each morning.
• A centre embedding an external BI dashboard as the default home screen.
• Reminding moderators that receipts are queued for verification.

Path map

flowchart LR
    F(["Desktop home dashboard"]):::feat
    F --> H1["Custom home dashboard"]:::ok
    F --> H2["Receipts nudge"]:::ok
    F -.-> X1["No home dashboard configured"]:::bad
    F -.-> X2["Unknown panel type"]:::bad
    F -.-> X3["External dashboard URL unreachable"]:::bad
    F -.-> X4["Receipt query fails"]:::bad
    classDef feat fill:#4a5c8a,stroke:#4a5c8a,color:#ffffff,font-weight:bold
    classDef ok fill:#e3f1ea,stroke:#0d6b42,color:#0d4a2e
    classDef bad fill:#f7e6e2,stroke:#9a2d1c,color:#6e1f13

Happy paths

Custom home dashboard

1. User logs in and lands on index.
2. A dashboard with category: 'home' and panel: 'custom' is found.
3. Its configured filters are pushed into the controller models and ctrl.settle() runs.
4. Charts and KPI tiles render with the current month’s date range as the default.

Receipts nudge

1. An admin/manager/crmmanager logs in with canShowReceiptsModal still true.
2. A query finds pending receipts for the centre.
3. After 3 seconds the modal opens and the flag is set to false so it does not reappear this session.

Failure paths

No home dashboard configured

Cause — No dashboard has category: 'home'.

What happens — hasDashboard is false and the desktop renders empty — the page header falls back to title.header.dashboards.show.

Unknown panel type

Cause — dashboard.panel is not one of data-quality / custom / url.

What happens — isValidDashboard is false, so the controller refuses to render the panel.

External dashboard URL unreachable

Cause — Embedded URL is wrong or the provider is down.

What happens — dashboard.error.not-found-external-dashboard; in older browsers the iframe fallback copy error_browser_iframe applies.

Receipt query fails

Cause — API error while counting pending receipts.

What happens — showModalReceipts is fired without awaiting and has no catch, so the rejection is unhandled — the modal just never appears.

QA checklist

Tick these off while regression-testing this feature. The boxes are plain Markdown, so progress is visible in git diffs.

• ✅ Custom home dashboard
• ✅ Receipts nudge
• ⛔ No home dashboard configured
• ⛔ Unknown panel type
• ⛔ External dashboard URL unreachable
• ⛔ Receipt query fails

Implementation

• app/routes/index.js
• app/controllers/index.js

Translation keys (4)

Key	English
title.header.desktop	Desktop
title.header.dashboards.show	Dashboard
dashboard.error.not-found-external-dashboard	External dashboard not found
error_browser_iframe	Your browser does not support iframes

Related

• Same area — Staff login · Password reset request · Password update from reset link · Change own password · Idle auto-logout · Centre switching & multi-centre scoping · Server-incident banner · Runtime environment & white-label boot · Back-office interface language · In-app help & support chat (Froged)
• Shares data with — Staff member editor (levels, scope, API token) · Dashboard configuration · Dashboard viewer · Customer receipts tab & ticket-stamp generation · Receipt verification queue

---

Generated from doc/feature-inventory.json · id platform-desktop · commit 276788ca6