Dashboard Patterns

Dashboard Patterns - Real-Time Data Visualisation

Codifies the project's existing dashboard architecture: the Status Command Centre component library, backend analytics APIs, and the Scientific Luxury design rules that govern every data surface. Enforces timeline layout, spectral colours, physics-based animations, and Australian locale formatting.

Description

Codifies real-time dashboard patterns for NodeJS-Starter-V1 including the Status Command Centre component library, timeline/orbital layouts, Supabase Realtime integration, spectral colour mapping, and Scientific Luxury design enforcement for all data visualisation surfaces.

---

When to Apply

Positive Triggers

• Building new dashboard pages or metric displays
• Adding real-time data visualisation components
• Integrating Supabase Realtime for live updates
• Creating loading skeletons or empty states for dashboards
• Composing MetricTile, DataStrip, or ProgressOrb components
• Reviewing dashboard layouts for Scientific Luxury compliance
• User mentions: "dashboard", "metrics display", "real-time", "monitoring UI", "command centre"

Negative Triggers

• Collecting or storing metrics data (use metrics-collector instead)
• Designing email templates (use email-template instead)
• Adding log statements (use structured-logging instead)
• Implementing non-dashboard UI components (use scientific-luxury instead)

Core Directives

The Three Laws of Dashboards

1. Timeline, never grid: No grid-cols-2/grid-cols-4 layouts. Use vertical timelines, horizontal data strips, and orbital arrangements. 2. Spectral, never static: Every status maps to a spectral colour with breathing animation. No grey placeholder states. 3. Real-time, never stale: Live data via Supabase Realtime or 30-second polling. Always show connection status.

---

Existing Project Infrastructure

Component Library

Location: apps/web/components/status-command-centre/

Dashboard Pages

Backend APIs

---

Layout Patterns

BANNED: Card Grid

// REJECTED — violates Scientific Luxury and Timeline law
<div className="grid grid-cols-2 lg:grid-cols-4 gap-4">
  <Card>...</Card>
  <Card>...</Card>
</div>

REQUIRED: Timeline Layout

The StatusCommandCentre implements a vertical timeline spine with agent nodes:

<div className="relative pl-4">
  {/* Vertical Timeline Spine */}
  <motion.div
    initial={{ scaleY: 0 }}
    animate={{ scaleY: 1 }}
    transition={{ delay: 0.3, duration: 0.8, ease: [0.19, 1, 0.22, 1] }}
    className="absolute top-0 bottom-0 left-8 w-px origin-top
               bg-gradient-to-b from-white/10 via-white/5 to-transparent"
  />
  {/* Agent Nodes along the spine */}
  <div className="space-y-8">
    {runs.map((run, index) => (
      <AgentNode key={run.id} run={run} index={index} />
    ))}
  </div>
</div>

REQUIRED: Horizontal Data Strip

Replace metric grids with DataStrip — inline horizontal layout with spectral-coloured values:

<DataStrip
  metrics={[
    { label: 'Total', value: runs.length },
    { label: 'Active', value: activeRuns.length, variant: 'info' },
    { label: 'Completed', value: completedRuns.length, variant: 'success' },
    { label: 'Failed', value: failedRuns.length, variant: 'error' },
  ]}
/>

DataStrip uses JetBrains Mono for values, text-[10px] tracking-widest uppercase for labels, pipe separators between metrics, and spectral glow on non-zero highlighted values.

---

Spectral Colour Mapping

Every AgentRunStatus maps to a spectral colour defined in constants.ts:

Access via getStatusConfig(status) from constants.ts. Each config includes colour (primary, glow, background), icon, animation, and intensity.

DataStrip variants use simplified spectral colours: info=#00F5FF, success=#00FF88, warning=#FFB800, error=#FF4444.

---

Animation Patterns

All animations use Framer Motion. CSS transitions are BANNED.

Staggered Entry

Components animate in sequence with delay offsets:

<motion.div
  initial={{ opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
  transition={{ delay: 0.1 * index, ease: [0.19, 1, 0.22, 1] }}
>

Breathing Orbs

Status indicators use breathing animation for active states:

<motion.span
  className="h-1.5 w-1.5 rounded-full"
  style={{ backgroundColor: config.colour.primary }}
  animate={{ opacity: [1, 0.4, 1], scale: [1, 1.2, 1] }}
  transition={{ duration: 2, repeat: Infinity, ease: 'easeInOut' }}
/>

Ambient Glow

Active agents trigger a radial gradient background glow:

{activeRuns.length > 0 && (
  <motion.div
    initial={{ opacity: 0 }}
    animate={{ opacity: 0.1 }}
    className="pointer-events-none absolute inset-0"
    style={{ background: 'radial-gradient(ellipse at 20% 10%, hsl(217 91% 60% / 0.15) 0%, transparent 50%)' }}
  />
)}

Status Transitions

Use useStatusTransitions hook to detect state changes and apply transition animations (success ripple, error shake).

---

Data Fetching Patterns

Server Components (Initial Load)

Use Next.js Server Components for initial data fetch with cache: 'no-store':

async function fetchAgentStats() {
  const backendUrl = process.env.BACKEND_URL || 'http://localhost:8000';
  const res = await fetch(`${backendUrl}/api/agents/stats`, { cache: 'no-store' });
  if (!res.ok) return FALLBACK_STATS;
  return res.json();
}

Always provide fallback data so the page renders even when the backend is unavailable.

Polling (Analytics Dashboard)

For non-realtime pages, poll at 30-second intervals:

useEffect(() => {
  fetchMetrics();
  const interval = setInterval(fetchMetrics, 30_000);
  return () => clearInterval(interval);
}, []);

Supabase Realtime (Command Centre)

For the Status Command Centre, subscribe to agent_runs table changes:

const channel = supabase
  .channel('agent-runs')
  .on('postgres_changes', { event: '*', schema: 'public', table: 'agent_runs' },
    (payload: RealtimePayload) => {
      if (payload.eventType === 'INSERT') addRun(payload.new);
      if (payload.eventType === 'UPDATE') updateRun(payload.new);
    })
  .subscribe();

Types RealtimeEvent, RealtimePayload, and ConnectionStatus are defined in types.ts.

Connection Status

Always display connection state using the ConnectionIndicator component:

• Connected (Emerald breathing dot + "Live" label)
• Reconnecting (Amber dot + "Reconnecting" label)
• Disconnected (Red dot + "Offline" label)

---

Loading & Empty States

Loading Skeleton

Every dashboard page must show a skeleton that matches the final layout structure:

function LoadingSkeleton() {
  return (
    <div className="space-y-8">
      <motion.div
        className="h-10 w-64 rounded-sm bg-white/5"
        animate={{ opacity: [0.5, 1, 0.5] }}
        transition={{ duration: 1.5, repeat: Infinity }}
      />
      {/* More skeleton elements matching the real layout */}
    </div>
  );
}

Rules: Use bg-white/5 for skeleton blocks, rounded-sm only, breathing opacity animation, staggered delays per element.

Empty State

When no data is available, show a centred empty state with a breathing orb:

<div className="flex flex-col items-center justify-center py-20">
  <motion.div
    className="h-3 w-3 rounded-full bg-white/20"
    animate={{ scale: [1, 1.5, 1], opacity: [0.5, 1, 0.5] }}
    transition={{ duration: 2, repeat: Infinity, ease: 'easeInOut' }}
  />
  <h3 className="text-xl font-light text-white">No Active Agents</h3>
  <p className="font-mono text-xs text-white/40">Description text.</p>
</div>

---

Component Composition

New Dashboard Page Template

Every dashboard page follows this structure:

// 1. Server Component wrapper (data fetch)
export default async function DashboardPage() {
  const data = await fetchData();
  return (
    <div className="relative min-h-screen bg-[#050505]">
      {/* Header */}
      <header className="border-b border-white/[0.06] px-8 py-6">
        <p className="text-[10px] tracking-[0.3em] text-white/30 uppercase">Category Label</p>
        <h1 className="text-4xl font-extralight tracking-tight text-white">Page Title</h1>
        <DataStrip metrics={[...]} />
      </header>

      {/* Content — timeline or orbital, never grid */}
      <Suspense fallback={<LoadingSkeleton />}>
        <DashboardContent data={data} />
      </Suspense>

      {/* Footer */}
      <footer className="px-8 py-4">
        <p className="font-mono text-[10px] text-white/20">
          {new Date().toLocaleDateString('en-AU')}
        </p>
      </footer>
    </div>
  );
}

When to Use Each Component

---

Anti-Patterns

---

Checklist for New Dashboard Pages

Layout

• [ ] OLED black background (bg-[#050505])
• [ ] Timeline or orbital layout (no card grids)
• [ ] DataStrip for summary metrics (not metric grid)
• [ ] Single pixel borders (border-[0.5px] border-white/[0.06])
• [ ] rounded-sm only (no rounded-lg, rounded-xl)
• [ ] JetBrains Mono for data values

Data

• [ ] Server Component for initial fetch with fallback data
• [ ] Polling interval (30s) or Supabase Realtime subscription
• [ ] Connection status indicator shown
• [ ] Loading skeleton matching final layout
• [ ] Empty state with breathing orb

Animation

• [ ] Framer Motion for all transitions (no CSS transitions)
• [ ] Staggered entry for list items
• [ ] Breathing animation for active status indicators
• [ ] Ambient glow when agents are active

Integration

• [ ] Uses metrics-collector MetricsRegistry for data source
• [ ] Spectral colours from STATUS_CONFIG constants
• [ ] Australian locale formatting (formatDateAU, formatTimestampAU)
• [ ] Types imported from status-command-centre/types.ts

---

Response Format

[AGENT_ACTIVATED]: Dashboard Patterns
[PHASE]: {Design | Implementation | Review}
[STATUS]: {in_progress | complete}

{dashboard analysis or implementation guidance}

[NEXT_ACTION]: {what to do next}

Integration Points

Scientific Luxury

• OLED black background, spectral colours, single-pixel borders, physics-based animations
• All dashboard components enforce the design system automatically via constants.ts

Metrics Collector

• MetricsRegistry provides the data layer (counters, gauges, histograms)
• Time-series aggregation powers trend charts
• Summary endpoint feeds DataStrip and MetricTile components

State Machine

• AgentRunStatus (10 states) maps directly to STATUS_CONFIG colour/animation entries
• useStatusTransitions hook handles state change animations

Structured Logging

• Dashboard pages log dashboard_loaded, dashboard_error events
• Connection status changes logged for debugging

Cron Scheduler

• Cron job metrics displayed via DataStrip or MetricTile
• Daily report data powers the analytics dashboard trends

Australian Localisation (en-AU)

• Date Format: DD/MM/YYYY via formatDateAU() utility
• Time: H:MM am/pm AEST/AEDT via formatTimeAU() and getAustralianTimezone()
• Currency: AUD ($) — total_cost_usd converted to AUD for display
• Spelling: colour, behaviour, analyse, optimise, centre
• Footer: Australian date format in dashboard footers