SaaS Dashboard UI Architect

=== SAAS DASHBOARD UI ARCHITECTURE ===

Product
PulseTrack Customer Success Platform

Product Category
B2B customer success SaaS

Primary Dashboard Job
Help customer success teams identify accounts requiring attention, understand the reason for risk, and initiate the correct intervention.

=== EXECUTIVE SUMMARY ===

PulseTrack should use an operational dashboard rather than a purely analytical dashboard.

The interface must help users complete a recurring decision loop:

Notice
Which customer accounts require attention?

Interpret
Why is the account considered at risk?

Decide
What intervention is appropriate?

Act
Assign a task, contact the customer, or launch a playbook.

Confirm
Verify ownership, deadline, and status.

Recover
Provide clear retry, reassignment, and escalation behavior when an action fails.

The dashboard should prioritize actionable exceptions and upcoming renewals above general summary metrics.

=== TARGET USERS ===

Customer Success Manager
Needs an operational queue, account context, tasks, risk drivers, and playbooks.

Team Lead
Needs team workload, account coverage, unresolved risks, and performance trends.

Administrator
Needs workspace setup, integrations, permissions, billing, and audit access.

Executive Viewer
Needs outcome-level metrics, renewal risk, trends, and exportable reports.

=== ACTIVATION AND RETENTION ===

Primary Activation Event
The first customer account is imported and receives a usable health score.

Activation Prerequisites

• Workspace created
• CRM connected or file imported
• Account data mapped
• Health model configured
• Initial synchronization completed

Primary Retention Behavior
Customer success managers review account health and complete intervention tasks weekly.

=== APPLICATION SHELL ===

Desktop

• Persistent 240-pixel sidebar
• Workspace switcher
• Global search
• Notification center
• Help menu
• Account menu
• Main content container
• Contextual page actions

Tablet

• Collapsible navigation rail
• Reduced top-bar controls
• Wrapped filter controls
• Two-column card grids

Mobile

• Modal navigation drawer
• Condensed top bar
• Stacked dashboard modules
• Filter drawer
• Full-width detail panels
• Sticky primary action only when it supports the current task

=== PRIMARY NAVIGATION ===

Home
Operational overview and priority work.

Accounts
Customer account list and segmentation.

Tasks
Personal and team task queues.

Playbooks
Reusable intervention workflows.

Reports
Analytical and executive reporting.

Integrations
CRM, product analytics, support, and communication connections.

Team
Users, roles, assignments, and workload.

Settings
Workspace, health model, notifications, billing, and security.

Audit Log
Administrator-only activity and configuration history.

=== ROUTE MAP ===

Route
/

Page
Dashboard Home

Primary Role
Customer Success Manager

Primary Action
Review accounts requiring attention

Route
Accounts

Page
Account Directory

Primary Role
Customer Success Manager

Primary Action
Open or segment customer accounts

Route
Accounts / Account ID

Page
Account Detail

Primary Role
Customer Success Manager

Primary Action
Review health drivers and initiate intervention

Route
Tasks

Page
Task Queue

Primary Role
Customer Success Manager

Primary Action
Complete, assign, or reschedule tasks

Route
Reports

Page
Reports Library

Primary Role
Team Lead and Executive Viewer

Primary Action
Open, schedule, or export reports

=== DASHBOARD HOME STRUCTURE ===

Section 1:
Page title, selected workspace, data freshness, and date context.

Section 2:
Setup or integration banner when critical data sources are incomplete.

Section 3:
Actionable priority cards.

Cards

• Accounts at Risk
• Upcoming Renewals
• High-Priority Tasks
• Accounts Without an Owner

Section 4:
Account Risk Queue

Purpose
Show customer accounts requiring immediate action.

Columns

• Account
• Health
• Primary Risk Driver
• Renewal Date
• Owner
• Last Activity
• Recommended Action

Section 5:
Health Score Trend

Question
How is portfolio health changing over time?

Chart
Line chart with current-period and comparison-period series.

Section 6:
Renewal Risk

Question
How much renewal value is associated with at-risk accounts?

Chart
Segmented bar chart with drill-down to filtered accounts.

Section 7:
Open Tasks

Purpose
Provide a direct operational queue.

Section 8:
Recent Account Activity

Purpose
Show material account events without becoming a noisy event stream.

Section 9:
Data Freshness and Integration Health

Purpose
Communicate delayed, disconnected, or partially synchronized data.

=== METRIC DICTIONARY ===

Metric
Accounts at Risk

Business Meaning
Customer accounts meeting the approved risk criteria.

User Meaning
Accounts likely to require intervention.

Formula
Defined by the approved health-scoring model.

Time Context
Current portfolio state.

Comparison
Change from the prior equivalent period.

Positive Direction
Lower, provided account coverage remains stable.

Drill-Down
Filtered account list.

Missing Data
Show an incomplete-data status rather than a misleading zero.

Metric
Renewal Value at Risk

Business Meaning
Expected renewal value associated with accounts currently classified as at risk.

Formula
Sum of approved renewal values for qualifying accounts.

Important Boundary
Do not calculate or display this metric unless renewal values and risk definitions are reliable.

=== KPI CARD SPECIFICATION ===

Component
Risk Summary Card

Anatomy

• Metric label
• Primary value
• Unit
• Comparison
• Trend indicator
• Data freshness
• Supporting context
• Optional drill-down

States

• Default
• Loading
• Empty
• Partial Data
• Stale Data
• Error
• Permission Restricted

Accessibility

• Trend direction must include text.
• Partial or stale data must be announced.
• Interactive cards require a clear accessible name.
• Loading updates should not repeatedly interrupt screen-reader users.

=== ANALYTICS PANEL ===

Panel
Health Score Trend

Business Question
Is the portfolio becoming healthier or riskier?

Chart Type
Line chart

X-Axis
Time

Y-Axis
Health score or approved health category share

Default Date Range
Last 90 days

Comparison
Previous 90 days

Tooltip

• Date
• Current value
• Comparison value
• Difference
• Data completeness note

Interaction
Select a period to open the filtered account list.

Accessibility

• Provide a textual trend summary.
• Provide an accessible data-table alternative.
• Do not rely on line color alone.
• Support keyboard access for interactive data points where required.

=== FILTER SYSTEM ===

Global Filters

• Workspace
• Date Range
• Account Segment
• Owner
• Health Status

Page-Level Filters

• Renewal Window
• Plan
• Industry
• Region
• Risk Driver
• Product Adoption Level

Filter Behavior

• Persist approved filters in the URL.
• Allow users to clear all filters.
• Show active-filter count.
• Save commonly used views.
• Filter options must respect permissions.
• On mobile, secondary filters open in a full-width drawer.

=== SAVED VIEWS ===

Fields

• View Name
• Owner
• Visibility
• Filters
• Sorting
• Visible Columns
• Grouping
• Date Range
• Default View
• Edit Permission

Visibility Options

• Private
• Team
• Workspace

=== ACCOUNT TABLE ===

Rows Represent
Customer accounts

Columns

• Account Name
• Health Status
• Health Score
• Primary Risk Driver
• Renewal Date
• Renewal Value
• Owner
• Open Tasks
• Last Activity
• Actions

Default Sort
Highest risk, then nearest renewal date

Available Features

• Search
• Filter
• Sort
• Column visibility
• Row selection
• Bulk owner assignment
• Bulk task creation
• Export subject to permission

Loading State
Use stable-row skeletons without shifting column widths.

Empty State
Explain whether there are no accounts, no matching filters, no permission, or no synchronized data.

Responsive Behavior

Desktop
Full table with configurable columns.

Tablet
Horizontal scroll with Account, Health, Renewal, and Owner prioritized.

Mobile
Transform rows into account cards with essential fields and a detail action.

=== CRITICAL USER FLOW ===

Flow
Respond to an At-Risk Account

User
Customer Success Manager

Entry
Dashboard risk queue or account list

Steps

1. Open account.
2. Review health score and risk drivers.
3. Review recent product and support activity.
4. Confirm renewal context.
5. Select an intervention.
6. Assign owner.
7. Set deadline.
8. Launch playbook or create task.
9. Confirm creation.
10. Return to updated queue.

Failure State
If task creation fails, preserve all entered values and provide retry.

Permission State
If the user cannot launch playbooks, explain the required role and provide an access-request path when available.

Analytics Events

• at_risk_account_opened
• risk_driver_viewed
• intervention_selected
• task_created
• playbook_launched
• intervention_failed

=== ONBOARDING ARCHITECTURE ===

Onboarding Model
Guided setup checklist with optional sample workspace.

Required Steps

1. Create workspace.
2. Connect CRM or import accounts.
3. Map account fields.
4. Configure health model.
5. Invite team.
6. Assign account owners.
7. Review first risk queue.

Sample Data
Provide a clearly labeled sample workspace so users can understand the product before integration.

Completion State
Show the first real account health results and recommend reviewing the risk queue.

=== EMPTY STATES ===

First-Use Dashboard

Headline
Connect customer data to build your first health dashboard.

Explanation
PulseTrack needs account and activity data before it can calculate meaningful health signals.

Primary Action
Connect CRM

Secondary Action
Import CSV

Optional Action
Explore Sample Workspace

Filtered Empty

Headline
No accounts match these filters.

Primary Action
Clear Filters

Secondary Action
Edit Saved View

Permission Empty

Headline
You do not have access to account health data.

Action
Request access or contact the workspace administrator.

=== LOADING AND ERROR STATES ===

Initial Dashboard Loading
Use skeletons matching the final module dimensions.

Background Refresh
Keep current data visible and show a non-blocking refresh indicator.

Partial Data
Identify affected sources and preserve reliable modules.

Integration Failure
Show the disconnected integration, last successful sync, impact, and reconnect action.

Offline
Preserve cached information when technically and legally appropriate and explain that updates are unavailable.

=== ROLE AND PERMISSION MATRIX ===

Customer Success Manager

• View assigned and permitted accounts
• Create and complete tasks
• Launch approved playbooks
• View operational reports

Team Lead

• View team accounts
• Reassign work
• Review team workload
• Access team reports

Administrator

• Manage workspace
• Manage integrations
• Manage users and permissions
• Configure health model
• Access billing
• Access audit log

Executive Viewer

• View approved executive reports
• No operational editing
• No billing or user-management access unless separately granted

=== MULTI-TENANT BEHAVIOR ===

• Display the current workspace at all times.
• Scope navigation, search, notifications, and data to the selected workspace.
• Confirm destructive actions using the workspace name.
• Prevent cross-workspace data leakage.
• Preserve deep links only when the user has access.
• Remember the last approved workspace.
• Revalidate permissions after workspace switching.

=== RESPONSIVE MATRIX ===

Sidebar

Extra Large
Persistent full sidebar.

Large
Persistent full sidebar.

Medium
Collapsed rail or temporary drawer.

Small
Modal navigation drawer.

KPI Cards

Extra Large
Four columns.

Large
Four columns.

Medium
Two columns.

Small
One column.

Filters

Extra Large
Inline.

Large
Inline.

Medium
Wrapped.

Small
Primary filter visible with secondary filters in a drawer.

Risk Table

Extra Large
Full table.

Large
Full table.

Medium
Horizontal scroll with prioritized columns.

Small
Account cards.

=== COMPONENT INVENTORY ===

Foundations

• Semantic Colors
• Typography
• Spacing
• Borders
• Radii
• Elevation
• Motion
• Breakpoints
• Grid

Layout

• AppShell
• PageContainer
• Stack
• Inline
• Grid
• SplitPane
• ScrollArea

Navigation

• Sidebar
• TopBar
• WorkspaceSwitcher
• Breadcrumbs
• Tabs
• MobileDrawer
• CommandPalette
• Pagination

Actions

• Button
• IconButton
• SplitButton
• MenuButton
• Link

Forms

• TextField
• Select
• Combobox
• Checkbox
• RadioGroup
• Switch
• DateRangePicker
• FilterBar
• ErrorSummary

Data

• KPI Card
• Chart Card
• Data Table
• Account Card
• Status Badge
• Activity Feed
• Audit Log
• Progress

Feedback

• Alert
• Toast
• Skeleton
• Spinner
• Empty State
• Error State
• Permission State
• Offline State

Overlays

• Modal
• Drawer
• Popover
• Tooltip
• Confirmation Dialog
• Detail Panel

Domain Components

• Account Health Card
• Risk Driver List
• Renewal Risk Panel
• Intervention Selector
• Playbook Launcher
• Integration Status Panel

=== ACCESSIBILITY REQUIREMENTS ===

• Use semantic landmarks.
• Maintain logical heading hierarchy.
• Provide skip navigation.
• Support complete keyboard access.
• Use visible focus indicators.
• Preserve logical focus order.
• Provide persistent form labels.
• Use sufficient contrast.
• Do not rely on color alone.
• Associate errors with fields.
• Provide error recovery.
• Announce loading and asynchronous completion appropriately.
• Provide chart summaries and data alternatives.
• Use semantic table structures.
• Manage modal and drawer focus.
• Respect reduced-motion settings.
• Support browser zoom and responsive reflow.
• Keep mobile reading order logical.
• Provide accessible names for icon-only controls.

=== ANALYTICS INSTRUMENTATION ===

Event
dashboard_viewed

Properties

• workspace_id
• role
• setup_status
• data_freshness

Purpose
Measure dashboard use and setup readiness.

Event
risk_account_opened

Properties

• source_module
• risk_category
• user_role

Purpose
Measure whether dashboard modules lead to investigation.

Event
empty_state_action_clicked

Properties

• empty_state_type
• action
• user_role

Purpose
Evaluate onboarding and recovery paths.

Privacy Note
Do not include customer names, private contact data, or sensitive account details in analytics-event properties unless explicitly justified and approved.

=== IMPLEMENTATION SEQUENCE ===

1. Confirm users, roles, jobs, and dashboard purpose.
2. Confirm entities, metrics, formulas, and data freshness.
3. Confirm application shell and routes.
4. Confirm permissions and workspace boundaries.
5. Define semantic design tokens.
6. Build primitive components.
7. Build navigation and page templates.
8. Build KPI cards, charts, filters, tables, and account cards.
9. Implement loading, empty, error, offline, and permission states.
10. Implement risk-review workflow.
11. Implement onboarding.
12. Implement responsive behavior.
13. Complete accessibility implementation.
14. Add approved analytics events.
15. Complete visual, functional, responsive, and accessibility QA.
16. Resolve open decisions and document deviations.

=== ACCEPTANCE CRITERIA ===

First-Use Dashboard

Given a new workspace has no imported data,
when the user opens the dashboard,
then the system explains why analytics are unavailable, provides CRM and CSV setup actions, offers an optional sample workspace, and does not display meaningless zero-value KPI cards.

At-Risk Workflow

Given a permitted customer success manager opens an at-risk account,
when the account detail loads,
then the interface displays risk drivers, recent activity, renewal context, account owner, open tasks, and available intervention actions.

Mobile Navigation

Given the viewport is below the small-screen breakpoint,
when the user activates the navigation control,
then a modal drawer opens, focus moves into it, background keyboard interaction is prevented, Escape closes it, and focus returns to the trigger.

Partial Data

Given one integration fails while other data sources remain available,
when the dashboard loads,
then reliable modules remain visible, affected modules show a partial-data state, and the integration status area provides recovery guidance.

Permission State

Given a user lacks permission to launch a playbook,
when the intervention controls are displayed,
then the restricted action is communicated before the user enters unnecessary information and an access path is provided when available.

=== QA CHECKLIST ===

Product QA

• Verify dashboard purpose.
• Verify role-specific modules.
• Verify activation path.
• Verify operational priority.
• Verify empty-state actions.

Data QA

• Verify formulas.
• Verify time ranges.
• Verify comparisons.
• Verify units.
• Verify missing-data behavior.
• Verify freshness indicators.

Interaction QA

• Verify navigation.
• Verify filters.
• Verify saved views.
• Verify tables.
• Verify search.
• Verify bulk actions.
• Verify task creation.
• Verify retry behavior.

Responsive QA

• Verify sidebar transformation.
• Verify card reflow.
• Verify filter drawer.
• Verify mobile account cards.
• Verify overlay dimensions.
• Verify keyboard obstruction.

Accessibility QA

• Verify landmarks.
• Verify headings.
• Verify keyboard access.
• Verify focus.
• Verify labels.
• Verify contrast.
• Verify chart alternatives.
• Verify error recovery.
• Verify reduced motion.
• Verify zoom and reflow.

Permission QA

• Verify every role.
• Verify workspace boundaries.
• Verify exports.
• Verify billing access.
• Verify audit access.
• Verify session behavior after role changes.

=== RISK ASSESSMENT ===

Metric Definition Risk
High

Reason
Health scores and renewal-risk metrics require approved formulas and reliable source data.

Mitigation
Create a formal metric dictionary and data-quality rules before final UI implementation.

Permission Risk
High

Reason
Multi-tenant customer data must remain isolated by workspace and role.

Mitigation
Define and test a complete permission matrix across routes, search, notifications, exports, and cached data.

Responsive Table Risk
High

Reason
Dense account data may not translate directly to mobile.

Mitigation
Use account cards for small screens and preserve full tables on larger devices.

Onboarding Risk
Moderate

Reason
The product may appear empty before integrations are connected.

Mitigation
Provide a guided checklist, import options, and a clearly labeled sample workspace.

Chart Interpretation Risk
Moderate

Reason
Health and renewal data can be misunderstood without definitions and context.

Mitigation
Provide metric definitions, time ranges, comparisons, freshness indicators, and accessible summaries.

=== OPEN QUESTIONS ===

• What exact formula determines account health?
• Which risk drivers are visible to each role?
• How frequently does each integration synchronize?
• Can users customize KPI cards?
• Are filters shared across users?
• Can saved views be workspace-wide?
• Which roles can export customer data?
• Are playbook actions reversible?
• What happens when an account belongs to multiple workspaces?
• Which events require audit-log entries?
• What data is available during an integration outage?

=== KNOWN LIMITATIONS ===

• Final formulas require analytics and domain validation.
• Final permissions require security and backend validation.
• Final responsive behavior requires browser and device testing.
• Accessibility requires implementation testing.
• Production performance depends on dataset size, architecture, and API behavior.
• The architecture does not guarantee activation, retention, revenue growth, adoption, customer satisfaction, or reduced support volume.

=== FINAL IMPLEMENTATION NOTE ===

Treat this architecture as an implementation contract only after product, design, engineering, analytics, accessibility, security, and domain owners resolve the open questions and approve the assumptions.