SaaS Dashboard UI Architect

Product name: PulseTrack Customer Success Platform Product category: B2B customer success SaaS Target users: Customer success managers Customer success team leads Revenue operations managers Executives Primary user roles: Customer Success Manager Team Lead Administrator Executive Viewer Core user jobs: Identify accounts at risk Understand health-score changes Review upcoming renewals Assign follow-up tasks Launch customer-success playbooks Monitor product adoption Prepare executive reports Business model: Subscription-based SaaS with team and enterprise plans Primary activation event: The first customer account is imported and receives a calculated health score. Primary retention behavior: Customer success managers review account health and complete intervention tasks every week. Core data entities: Organizations Workspaces Users Customer Accounts Contacts Health Scores Risk Signals Tasks Playbooks Renewals Activities Integrations Reports Key metrics: Accounts at risk Upcoming renewals Open high-priority tasks Average health score Health-score change Adoption risk Renewal value at risk Completed interventions Critical workflows: Connect CRM Import customer accounts Review at-risk accounts Open account detail Review risk drivers Assign follow-up task Launch playbook Update renewal status Export executive report Existing pages: Login Dashboard Accounts Account Detail Tasks Reports Integrations Settings Required pages: Onboarding Workspace Setup Dashboard Home Accounts Account Detail Tasks Playbooks Reports Integrations Team Management Billing Settings Audit Log Navigation preference: Persistent desktop sidebar with mobile navigation drawer Tenant model: Multi-tenant organizations with multiple workspaces Permission model: Granular role-based permissions Data density: High Real-time requirements: Risk signals and task updates should refresh frequently. Formal real-time behavior requires technical confirmation. Frontend stack: Next.js React TypeScript Tailwind CSS Component library: Custom components based on Radix primitives Design system: Partial Responsive targets: Desktop Tablet Mobile Accessibility target: WCAG 2.2 AA implementation review Localization: English at launch Future multilingual support Allow approximately 30% text expansion Need output: Complete SaaS dashboard architecture Application shell Navigation and route map Dashboard home Metric dictionary Card and chart specifications Filter system Table specifications User flows Onboarding Empty states Loading and error states Permissions Responsive behavior Component inventory Accessibility requirements Analytics events Developer handoff Acceptance criteria QA checklist Risk assessment Special constraints: Clearly separate observed facts from assumptions. Do not invent metrics or customer behavior. Avoid dark patterns. Include sample-data onboarding. Make permissions visible before users attempt restricted actions. Include loading, empty, error, offline, partial-data, and plan-limited states.

=== 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.