Kordant/tasks/shieldai-unified-restructure/24-dashboard-widgets.md

24. Dashboard — Unified Widgets for All Services

meta: id: shieldai-unified-restructure-24 feature: shieldai-unified-restructure priority: P1 depends_on: [shieldai-unified-restructure-23] tags: [frontend, dashboard, widgets, solidjs]

objective:

• Build rich, interactive dashboard widgets that give users a unified view of their security posture across all ShieldAI services. Replace placeholder stat cards with real, actionable widgets.

deliverables:

• web/src/components/dashboard/ThreatScoreWidget.tsx — Circular gauge showing overall threat score (0-100):
  • Color-coded: green (0-30), amber (31-70), red (71-100)
  • Trend indicator (up/down vs last week)
  • Click to view detailed breakdown
• web/src/components/dashboard/AlertFeedWidget.tsx — Real-time alert stream:
  • List of latest 5-10 alerts with severity icons
  • Grouped by correlation group
  • "Mark as read" and "View details" actions
  • "View all" link to alerts page
• web/src/components/dashboard/ExposureWidget.tsx — DarkWatch summary:
  • Count of exposures by severity
  • Latest exposure with source and date
  • "Run scan" button
  • Link to full DarkWatch page
• web/src/components/dashboard/VoicePrintWidget.tsx — VoicePrint summary:
  • Enrollment count
  • Recent analyses count
  • Synthetic detection rate
  • "Analyze audio" button
• web/src/components/dashboard/SpamShieldWidget.tsx — SpamShield summary:
  • Blocked calls/SMS count (today/this week)
  • Top spam sources
  • Custom rules count
  • "View rules" link
• web/src/components/dashboard/HomeTitleWidget.tsx — HomeTitle summary:
  • Watched properties count
  • Recent changes count
  • Latest change with severity
  • "View properties" link
• web/src/components/dashboard/RemoveBrokersWidget.tsx — RemoveBrokers summary:
  • Total brokers in registry
  • Pending/completed removals count
  • Progress bar for overall removal completion
  • "Manage removals" link
• web/src/components/dashboard/QuickActionsWidget.tsx — Shortcut buttons:
  • "Add to watchlist", "Upload voice sample", "Check number", "Add property", "Start removal"
• web/src/routes/(webapp)/dashboard.tsx — Updated dashboard layout:
  • Grid layout: 2 columns on desktop, 1 on mobile
  • Widgets arranged by priority (threat score top-left, quick actions top-right)
  • Auto-refresh every 60 seconds

steps:

1. Create web/src/components/dashboard/ directory.
2. ThreatScoreWidget:
   • Use SVG for circular gauge with stroke-dasharray animation
   • Query api.correlation.getStats for score and trend
   • Color transitions based on score value
3. AlertFeedWidget:
   • Query api.correlation.getAlerts with limit: 10
   • Each item: severity icon (shield with color), title, time ago, source badge
   • Use Card primitive with compact padding
   • "Mark as read" calls api.correlation.resolveAlert
4. ExposureWidget:
   • Query api.darkwatch.getExposures with limit: 1 for latest
   • Show severity breakdown as small horizontal bars
   • "Run scan" button triggers api.darkwatch.runScan mutation
5. VoicePrintWidget:
   • Query api.voiceprint.getEnrollments and api.voiceprint.getAnalyses
   • Show counts and a mini bar chart of recent analyses
6. SpamShieldWidget:
   • Query api.spamshield.getStats
   • Show blocked count with trend
   • List top 3 spam sources as small rows
7. HomeTitleWidget:
   • Query api.hometitle.getProperties and api.hometitle.getChanges
   • Show property count and latest change
8. RemoveBrokersWidget:
   • Query api.removebrokers.getRemovalRequests and api.removebrokers.getBrokerRegistry
   • Calculate completion percentage
   • Show progress bar using theme colors
9. QuickActionsWidget:
   • Grid of icon buttons linking to service pages or opening modals
   • Each button uses Button primitive with icon
10. Update dashboard route:
    • Compose all widgets in responsive grid
    • Add createInterval or setInterval for auto-refresh
    • Handle loading states with skeleton cards

steps:

• Unit: Each widget renders correctly with mock data
• Unit: ThreatScoreWidget displays correct color for score ranges
• Unit: AlertFeedWidget calls mark-read mutation on click
• Visual: Dashboard grid is responsive and widgets align correctly
• E2E: Dashboard loads with real data and auto-refreshes

acceptance_criteria:

• Dashboard displays 8 widgets in a responsive grid layout
• Threat score gauge animates on load and updates with real data
• Alert feed shows latest alerts with correct severity colors
• Each service widget summarizes the most important metrics
• Quick actions provide one-click access to common tasks
• Dashboard auto-refreshes every 60 seconds
• Loading states show skeleton cards while data fetches
• All widgets use theme tokens and shift correctly in dark mode

validation:

• Open /dashboard and verify all widgets render with real data
• Resize browser to mobile width and verify single-column layout
• Wait 60 seconds and verify auto-refresh updates data
• Click "Mark as read" on an alert and verify it disappears from feed
• Run cd web && pnpm test for widget unit tests

notes:

• Keep widgets focused on summary data. Deep interactions belong on service-specific pages.
• The threat score gauge is the visual centerpiece. Invest in making it polished and informative.
• Consider adding a "Security Tip of the Day" widget that rotates educational content.
• Widgets should be collapsible or reorderable in a future enhancement. Design them as self-contained units.
• Use Suspense boundaries around widget groups to prevent the entire dashboard from blocking on one slow API call.