@littlebearapps/platform-admin-sdk 2.0.0 → 2.1.0

package/templates/shared/dashboard/src/components/usage/unified/UnifiedShell.tsx

@@ -0,0 +1,893 @@
+/**
+ * UnifiedShell Component
+ *
+ * Main orchestrator for the Unified Observability Dashboard.
+ * Handles data fetching, state management, auto-refresh, and URL sync.
+ *
+ * Industrial Command Centre aesthetic - data-dense, dark-first design.
+ */
+
+import { useState, useEffect, useCallback, useMemo, useRef } from 'react';
+import { AlertTriangle } from 'lucide-react';
+import { fetchWithDedup, clearFetchCache } from '../../../lib/usage/fetchWithDedup';
+import { CF_ALLOWANCES, type ServiceType } from '../../../lib/usage/allowance-config';
+import type {
+  Period,
+  Tab,
+  SortField,
+  SortDir,
+  BurnRateData,
+  ServiceUtilisation,
+  ProjectSummary,
+  ProjectTableRow,
+  ProjectBreakdown,
+  UsageRow,
+  StatusResponse,
+  QueryResponse,
+  UtilisationResponse,
+  ResourceMetric,
+  ResourceType,
+  DailyCostData,
+  DailyCostTotals,
+  OperationalStatus,
+  BillingContextResponse,
+  GranularResponse,
+} from './types';
+import { LiveHeader } from './LiveHeader';
+import { HeroCardsRow } from './HeroCardsRow';
+import { AlertBanner } from './AlertBanner';
+import { Recommendations } from './Recommendations';
+import { ProjectsTable } from './ProjectsTable';
+import { UsageChart } from '../react/UsageChart';
+import { FeatureBudgets } from './FeatureBudgets';
+import { CircuitBreakerEvents } from './CircuitBreakerEvents';
+
+interface UnifiedShellProps {
+  initialPeriod?: Period;
+  initialTab?: Tab;
+  initialSearch?: string;
+  initialSort?: SortField;
+  initialDir?: SortDir;
+  initialExpanded?: string[];
+}
+
+const REFRESH_INTERVAL = 60_000; // 60 seconds
+const CACHE_TTL = 60_000; // 60 seconds for resource breakdown cache
+
+/**
+ * Error state component
+ */
+function ErrorState({ message, onRetry }: { message: string; onRetry: () => void }) {
+  return (
+    <div className="bg-rose-500/10 border border-rose-500/30 rounded-sm p-6 flex items-start gap-4">
+      <AlertTriangle className="w-5 h-5 text-rose-400 flex-shrink-0 mt-0.5" />
+      <div className="flex-1">
+        <h3 className="text-rose-800 dark:text-rose-200 font-semibold text-sm">
+          Failed to load data
+        </h3>
+        <p className="text-rose-700/80 dark:text-rose-300/80 text-xs mt-1 font-mono">{message}</p>
+        <button
+          type="button"
+          onClick={onRetry}
+          className="mt-3 px-3 py-1.5 bg-rose-500/20 hover:bg-rose-500/30 text-rose-800 dark:text-rose-200 text-xs font-mono rounded-sm transition-colors"
+        >
+          Retry
+        </button>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Loading skeleton
+ */
+function LoadingSkeleton() {
+  return (
+    <div className="space-y-6 animate-pulse">
+      {/* Header skeleton */}
+      <div className="flex justify-between items-center">
+        <div className="h-8 bg-gray-100 dark:bg-slate-800 rounded w-48" />
+        <div className="h-8 bg-gray-100 dark:bg-slate-800 rounded w-32" />
+      </div>
+
+      {/* Chart skeleton */}
+      <div className="space-y-3">
+        <div className="h-5 bg-gray-100 dark:bg-slate-800 rounded w-36" />
+        <div className="h-48 bg-gray-50 dark:bg-slate-900 rounded-sm border border-gray-200 dark:border-slate-800" />
+      </div>
+
+      {/* Hero cards skeleton */}
+      <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
+        <div className="h-32 bg-gray-100/50 dark:bg-slate-800/50 rounded-lg border border-gray-300 dark:border-slate-700" />
+        <div className="h-32 bg-gray-100/50 dark:bg-slate-800/50 rounded-lg border border-gray-300 dark:border-slate-700" />
+        <div className="h-32 bg-gray-100/50 dark:bg-slate-800/50 rounded-lg border border-gray-300 dark:border-slate-700" />
+      </div>
+
+      {/* Table skeleton */}
+      <div className="space-y-3">
+        <div className="h-5 bg-gray-100 dark:bg-slate-800 rounded w-24" />
+        <div className="h-64 bg-gray-50 dark:bg-slate-900 rounded-sm border border-gray-200 dark:border-slate-800" />
+      </div>
+    </div>
+  );
+}
+
+export function UnifiedShell({
+  initialPeriod = '24h',
+  initialTab = 'overview',
+  initialSearch = '',
+  initialSort = 'cost',
+  initialDir = 'desc',
+  initialExpanded = [],
+}: UnifiedShellProps) {
+  // Core state
+  const [period, setPeriod] = useState<Period>(initialPeriod);
+  const [tab, setTab] = useState<Tab>(initialTab);
+  const [search, setSearch] = useState(initialSearch);
+  const [sort, setSort] = useState<SortField>(initialSort);
+  const [sortDir, setSortDir] = useState<SortDir>(initialDir);
+  const [expanded, setExpanded] = useState<Set<string>>(new Set(initialExpanded));
+
+  // Loading & error state
+  const [loading, setLoading] = useState(true);
+  const [isRefreshing, setIsRefreshing] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // Data state
+  const [burnRate, setBurnRate] = useState<BurnRateData | null>(null);
+  const [services, setServices] = useState<ServiceUtilisation[]>([]);
+  const [projects, setProjects] = useState<ProjectSummary[]>([]);
+  const [usageData, setUsageData] = useState<UsageRow[]>([]);
+  const [statusMap, setStatusMap] = useState<
+    Record<string, { status: string; circuitBreaker: string }>
+  >({});
+
+  // Billing context state (for Plan Health cards)
+  const [billingContext, setBillingContext] = useState<BillingContextResponse | null>(null);
+
+  // Granular usage data (for stacked bar chart)
+  const [granularData, setGranularData] = useState<GranularResponse | null>(null);
+
+  // Lazy-loaded resource breakdown cache
+  const [resourceCache, setResourceCache] = useState<Map<string, ProjectBreakdown>>(new Map());
+  // Use ref to avoid dependency cycle in fetchResourceBreakdown
+  const resourceCacheRef = useRef(resourceCache);
+  resourceCacheRef.current = resourceCache;
+
+  // Dismissed alerts (persisted to localStorage)
+  const [dismissedAlerts, setDismissedAlerts] = useState<Set<string>>(() => {
+    if (typeof window === 'undefined') return new Set();
+    try {
+      const stored = localStorage.getItem('unified-dismissed-alerts');
+      return stored ? new Set(JSON.parse(stored)) : new Set();
+    } catch {
+      return new Set();
+    }
+  });
+
+  /**
+   * Sync state to URL
+   */
+  const syncToURL = useCallback(() => {
+    const url = new URL(window.location.href);
+    url.searchParams.set('period', period);
+    url.searchParams.set('tab', tab);
+
+    if (search) {
+      url.searchParams.set('search', search);
+    } else {
+      url.searchParams.delete('search');
+    }
+
+    url.searchParams.set('sort', sort);
+    url.searchParams.set('dir', sortDir);
+
+    if (expanded.size > 0) {
+      url.searchParams.set('expanded', Array.from(expanded).join(','));
+    } else {
+      url.searchParams.delete('expanded');
+    }
+
+    history.replaceState(null, '', url.toString());
+  }, [period, tab, search, sort, sortDir, expanded]);
+
+  // Sync URL on state change
+  useEffect(() => {
+    syncToURL();
+  }, [syncToURL]);
+
+  /**
+   * Fetch utilisation data (hero cards + projects)
+   */
+  const fetchUtilisation = useCallback(async () => {
+    const data = await fetchWithDedup<UtilisationResponse>('/api/usage/utilization');
+    if (!data.success) throw new Error('Utilisation API returned unsuccessful response');
+
+    setBurnRate(data.burnRate);
+    setServices(data.cloudflareServices);
+    setProjects(data.projects);
+  }, []);
+
+  /**
+   * Fetch status data (circuit breakers, operational status)
+   */
+  const fetchStatus = useCallback(async () => {
+    const data = await fetchWithDedup<StatusResponse>(`/api/usage/status?period=${period}`);
+    if (!data.success) throw new Error('Status API returned unsuccessful response');
+
+    setStatusMap(data.projects as Record<string, { status: string; circuitBreaker: string }>);
+  }, [period]);
+
+  /**
+   * Fetch usage query data (chart)
+   * Uses hour grouping for 24h period, day grouping for longer periods
+   */
+  const fetchQuery = useCallback(async () => {
+    // Use hourly granularity for 24h, daily for longer periods
+    const groupBy = period === '24h' ? 'hour' : 'day';
+    const data = await fetchWithDedup<QueryResponse>(
+      `/api/usage/query?period=${period}&groupBy=${groupBy}`
+    );
+    if (!data.success) throw new Error('Query API returned unsuccessful response');
+
+    setUsageData(data.data);
+  }, [period]);
+
+  /**
+   * Fetch billing context (for Plan Health cards)
+   */
+  const fetchBillingContext = useCallback(async () => {
+    const data = await fetchWithDedup<BillingContextResponse>(
+      `/api/usage/billing-context?period=${period}`
+    );
+    if (!data.success) throw new Error('Billing context API returned unsuccessful response');
+
+    setBillingContext(data);
+  }, [period]);
+
+  /**
+   * Fetch granular usage data (for stacked bar chart)
+   */
+  const fetchGranular = useCallback(async () => {
+    const data = await fetchWithDedup<GranularResponse>(`/api/usage/granular?period=${period}`);
+    if (!data.success) throw new Error('Granular API returned unsuccessful response');
+
+    setGranularData(data);
+  }, [period]);
+
+  /**
+   * Main data fetch
+   */
+  const fetchData = useCallback(
+    async (isBackground = false) => {
+      if (isBackground) {
+        setIsRefreshing(true);
+      } else {
+        setLoading(true);
+        setError(null);
+      }
+
+      try {
+        await Promise.all([
+          fetchUtilisation(),
+          fetchStatus(),
+          fetchQuery(),
+          fetchBillingContext(),
+          fetchGranular(),
+        ]);
+        setError(null);
+      } catch (err) {
+        if (!isBackground) {
+          setError(err instanceof Error ? err.message : 'Unknown error occurred');
+        }
+        console.error('[UnifiedShell] Fetch error:', err);
+      } finally {
+        setLoading(false);
+        setIsRefreshing(false);
+      }
+    },
+    [fetchUtilisation, fetchStatus, fetchQuery, fetchBillingContext, fetchGranular]
+  );
+
+  /**
+   * Fetch resource breakdown for a project (lazy loading)
+   * Uses ref for cache check to avoid dependency cycle
+   */
+  const fetchResourceBreakdown = useCallback(
+    async (projectId: string): Promise<ProjectBreakdown | null> => {
+      // Check cache first (use ref to avoid dependency cycle)
+      const cached = resourceCacheRef.current.get(projectId);
+      if (cached && Date.now() - cached.fetchedAt < CACHE_TTL) {
+        return cached;
+      }
+
+      try {
+        const response = await fetch(`/api/usage/daily?period=${period}&project=${projectId}`, {
+          credentials: 'include',
+        });
+
+        if (!response.ok) {
+          console.error(`Failed to fetch breakdown for ${projectId}: ${response.status}`);
+          return null;
+        }
+
+        const data = await response.json();
+        if (!data.success) return null;
+
+        // Transform the API response (object with totals) into ResourceMetric[] format
+        const dailyData = data.data as DailyCostData;
+        const resources: ResourceMetric[] = [];
+        const totals: DailyCostTotals = dailyData?.totals || {
+          workers: 0,
+          d1: 0,
+          kv: 0,
+          r2: 0,
+          durableObjects: 0,
+          vectorize: 0,
+          queues: 0,
+          total: 0,
+        };
+        const days = dailyData?.days || [];
+
+        // Build sparkline trends from daily data (last 6 points)
+        const buildTrend = (field: keyof DailyCostTotals): number[] => {
+          if (days.length === 0) return [];
+          const recentDays = days.slice(-6);
+          return recentDays.map((d) => d[field] || 0);
+        };
+
+        // Cost-to-usage conversion factors (reverse-engineered from Cloudflare pricing)
+        // These convert dollar costs back to approximate usage units
+        const costToUsage = (cost: number, type: ResourceType): number => {
+          switch (type) {
+            case 'd1':
+              // D1: $0.75 per 1M rows written → cost * 1M / 0.75 ≈ cost * 1.33M
+              return cost * 1_333_333;
+            case 'kv':
+              // KV: $5 per 1M writes → cost * 1M / 5 = cost * 200K
+              return (cost / 5) * 1_000_000;
+            case 'workers':
+              // Workers: $0.30 per 1M requests → cost * 1M / 0.30 ≈ cost * 3.33M
+              return (cost / 0.3) * 1_000_000;
+            case 'vectorize':
+              // Vectorize: $0.01 per 1M dimensions queried → cost * 1M / 0.01 = cost * 100M
+              return (cost / 0.01) * 1_000_000;
+            case 'r2':
+              // R2: $4.50 per 1M Class A ops → cost * 1M / 4.5 ≈ cost * 222K
+              return (cost / 4.5) * 1_000_000;
+            case 'durableObjects':
+              // DO: $0.15 per 1M requests → cost * 1M / 0.15 ≈ cost * 6.67M
+              return (cost / 0.15) * 1_000_000;
+            case 'queues':
+              // Queues: $0.40 per 1M messages → cost * 1M / 0.4 = cost * 2.5M
+              return (cost / 0.4) * 1_000_000;
+            default:
+              return cost;
+          }
+        };
+
+        // Map each service with cost > 0 to a ResourceMetric
+        const serviceMap: Array<{
+          key: keyof DailyCostTotals;
+          type: ResourceType;
+          label: string;
+          unit: string;
+        }> = [
+          { key: 'd1', type: 'd1', label: 'D1 Database', unit: 'rows written' },
+          { key: 'kv', type: 'kv', label: 'KV Storage', unit: 'writes' },
+          { key: 'r2', type: 'r2', label: 'R2 Storage', unit: 'Class A ops' },
+          { key: 'workers', type: 'workers', label: 'Workers', unit: 'requests' },
+          {
+            key: 'durableObjects',
+            type: 'durableObjects',
+            label: 'Durable Objects',
+            unit: 'requests',
+          },
+          { key: 'vectorize', type: 'vectorize', label: 'Vectorize', unit: 'dimensions' },
+          { key: 'queues', type: 'queues', label: 'Queues', unit: 'messages' },
+        ];
+
+        for (const svc of serviceMap) {
+          const cost = totals[svc.key] || 0;
+          if (cost > 0 || days.some((d) => (d[svc.key] || 0) > 0)) {
+            const usage = costToUsage(cost, svc.type);
+            const allowance = CF_ALLOWANCES[svc.type as ServiceType];
+            const limit = allowance?.monthlyLimit ?? Infinity;
+            const limitPct = limit !== Infinity && limit > 0 ? (usage / limit) * 100 : undefined;
+
+            // Format usage with appropriate units
+            let usageFormatted: string;
+            if (usage >= 1_000_000) {
+              usageFormatted = `${(usage / 1_000_000).toFixed(1)}M ${svc.unit}`;
+            } else if (usage >= 1_000) {
+              usageFormatted = `${(usage / 1_000).toFixed(1)}K ${svc.unit}`;
+            } else {
+              usageFormatted = `${Math.round(usage)} ${svc.unit}`;
+            }
+
+            resources.push({
+              type: svc.type,
+              label: svc.label,
+              cost,
+              usage,
+              usageFormatted,
+              unit: svc.unit,
+              limit,
+              limitPct,
+              trend: buildTrend(svc.key),
+            });
+          }
+        }
+
+        const breakdown: ProjectBreakdown = {
+          projectId,
+          resources,
+          totalCost: totals.total || 0,
+          fetchedAt: Date.now(),
+        };
+
+        setResourceCache((prev) => new Map(prev).set(projectId, breakdown));
+        return breakdown;
+      } catch (err) {
+        console.error(`Error fetching breakdown for ${projectId}:`, err);
+        return null;
+      }
+    },
+    [period]
+  );
+
+  // Initial fetch and refetch on period change
+  // Note: fetchData already depends on period via fetchStatus/fetchQuery
+  // Intentionally only depending on `period` to avoid refetch loops
+  useEffect(() => {
+    fetchData();
+  }, [period]);
+
+  // Auto-refresh interval
+  useEffect(() => {
+    const interval = setInterval(() => {
+      fetchData(true);
+    }, REFRESH_INTERVAL);
+
+    return () => clearInterval(interval);
+  }, [fetchData]);
+
+  /**
+   * Handle period change
+   */
+  const handlePeriodChange = useCallback((newPeriod: Period) => {
+    setPeriod(newPeriod);
+    // Clear resource cache on period change
+    setResourceCache(new Map());
+    // Clear fetch dedup cache to ensure fresh data for new period
+    clearFetchCache('/api/usage/');
+  }, []);
+
+  /**
+   * Handle search change (debounced in LiveHeader)
+   */
+  const handleSearchChange = useCallback((value: string) => {
+    setSearch(value);
+  }, []);
+
+  /**
+   * Handle sort change
+   */
+  const handleSortChange = useCallback(
+    (field: SortField) => {
+      if (field === sort) {
+        // Toggle direction
+        setSortDir((d) => (d === 'asc' ? 'desc' : 'asc'));
+      } else {
+        setSort(field);
+        setSortDir('desc');
+      }
+    },
+    [sort]
+  );
+
+  /**
+   * Handle row expand/collapse
+   * Side effect (fetchResourceBreakdown) is called outside setState to avoid anti-pattern
+   */
+  const handleExpand = useCallback(
+    (projectId: string) => {
+      setExpanded((prev) => {
+        const next = new Set(prev);
+        const wasExpanded = next.has(projectId);
+
+        if (wasExpanded) {
+          next.delete(projectId);
+        } else {
+          next.add(projectId);
+        }
+
+        // Schedule lazy load outside of setState (after render)
+        if (!wasExpanded) {
+          // Use queueMicrotask to ensure state update completes first
+          queueMicrotask(() => {
+            fetchResourceBreakdown(projectId);
+          });
+        }
+
+        return next;
+      });
+    },
+    [fetchResourceBreakdown]
+  );
+
+  /**
+   * Handle tab change
+   */
+  const handleTabChange = useCallback((newTab: Tab) => {
+    setTab(newTab);
+  }, []);
+
+  /**
+   * Handle alert dismissal
+   */
+  const handleDismissAlert = useCallback((alertId: string) => {
+    setDismissedAlerts((prev) => {
+      const next = new Set(prev);
+      next.add(alertId);
+      // Persist to localStorage
+      try {
+        localStorage.setItem('unified-dismissed-alerts', JSON.stringify([...next]));
+      } catch {
+        // Ignore localStorage errors
+      }
+      return next;
+    });
+  }, []);
+
+  /**
+   * Hero Card Interactivity Handlers
+   */
+
+  // MTD Spend Card: Scroll to recommendations
+  const handleMTDSpendClick = useCallback(() => {
+    const el = document.getElementById('recommendations-section');
+    if (el) {
+      el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+      // Add highlight effect
+      el.classList.add('ring-2', 'ring-blue-500/50');
+      setTimeout(() => el.classList.remove('ring-2', 'ring-blue-500/50'), 2000);
+    }
+  }, []);
+
+  // Plan Utilisation Card: Show service in table, could filter or highlight
+  const handlePlanUtilisationClick = useCallback((_serviceId: string) => {
+    // Scroll to projects table
+    const el = document.getElementById('projects-section');
+    if (el) {
+      el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    }
+  }, []);
+
+  // Top Spender Card: Sort table by cost
+  const handleTopSpenderClick = useCallback(() => {
+    setSort('cost');
+    setSortDir('desc');
+    // Scroll to projects table
+    const el = document.getElementById('projects-section');
+    if (el) {
+      el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    }
+  }, []);
+
+  // System Health Card: Filter to critical/warning projects
+  const [statusFilter, setStatusFilter] = useState<'all' | 'critical' | 'warning'>('all');
+
+  const handleSystemHealthClick = useCallback((filter: 'critical' | 'warning' | 'all') => {
+    setStatusFilter(filter);
+    // Scroll to projects table
+    const el = document.getElementById('projects-section');
+    if (el) {
+      el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    }
+  }, []);
+
+  /**
+   * Handle export
+   */
+  const handleExport = useCallback(() => {
+    if (!projects || projects.length === 0) {
+      console.warn('[Export] No projects data available');
+      return;
+    }
+
+    // Build CSV from current data
+    const rows: string[] = ['Project,MTD Cost,Delta %,Status'];
+    for (const proj of projects) {
+      // Escape any commas in project names
+      const name = proj.projectName.includes(',') ? `"${proj.projectName}"` : proj.projectName;
+      rows.push(
+        `${name},${proj.mtdCost.toFixed(2)},${proj.costDeltaPct.toFixed(1)},${proj.status}`
+      );
+    }
+
+    const csv = rows.join('\n');
+    const blob = new Blob([csv], { type: 'text/csv;charset=utf-8;' });
+    const url = URL.createObjectURL(blob);
+
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = `usage-${period}-${new Date().toISOString().split('T')[0]}.csv`;
+    link.style.display = 'none';
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+
+    // Cleanup
+    setTimeout(() => URL.revokeObjectURL(url), 100);
+  }, [projects, period]);
+
+  /**
+   * Derive operational status based on metrics
+   */
+  const deriveStatus = useCallback(
+    (
+      project: ProjectSummary,
+      circuitBreakerState: 'active' | 'tripped' | 'degraded' | undefined
+    ): OperationalStatus => {
+      const utilizationPct = project.utilizationPct;
+
+      // CRITICAL/STOP: Over 100% of plan limits
+      if (utilizationPct > 100) return 'STOP';
+
+      // WARN: Approaching limits (>80%) or circuit breaker tripped/degraded
+      if (
+        utilizationPct > 80 ||
+        circuitBreakerState === 'tripped' ||
+        circuitBreakerState === 'degraded'
+      ) {
+        return 'WARN';
+      }
+
+      // RUN: Operating normally
+      return 'RUN';
+    },
+    []
+  );
+
+  /**
+   * Calculate delta from sparkline data
+   */
+  const calculateDeltaFromSparkline = useCallback((sparkline: number[]): number => {
+    if (!sparkline || sparkline.length < 2) return 0;
+    const recent = sparkline[sparkline.length - 1];
+    const previous = sparkline[sparkline.length - 2];
+    if (previous === 0) return recent > 0 ? 100 : 0;
+    return ((recent - previous) / previous) * 100;
+  }, []);
+
+  /**
+   * Transform projects to table rows
+   */
+  const tableRows: ProjectTableRow[] = useMemo(() => {
+    let filtered = projects.map((p) => {
+      const cbStatus =
+        p.circuitBreakerStatus ||
+        (statusMap[p.projectId]?.circuitBreaker as 'active' | 'tripped' | 'degraded') ||
+        'active';
+
+      // Derive status from utilization metrics, not just from statusMap
+      const derivedStatus = deriveStatus(p, cbStatus === 'active' ? undefined : cbStatus);
+
+      // Calculate delta from sparkline if costDeltaPct is 0
+      const delta =
+        p.costDeltaPct !== 0 ? p.costDeltaPct : calculateDeltaFromSparkline(p.sparklineData || []);
+
+      return {
+        id: p.projectId,
+        name: p.projectName,
+        status: derivedStatus,
+        mtdCost: p.mtdCost,
+        costDeltaPct: delta,
+        activity: p.utilizationCurrent,
+        activityTrend: p.sparklineData || [],
+        circuitBreaker: cbStatus === 'degraded' ? 'tripped' : (cbStatus as 'active' | 'tripped'),
+      };
+    });
+
+    // Apply search filter
+    if (search) {
+      const term = search.toLowerCase();
+      filtered = filtered.filter((r) => r.name.toLowerCase().includes(term));
+    }
+
+    // Apply status filter from card clicks
+    if (statusFilter === 'critical') {
+      filtered = filtered.filter((r) => r.status === 'STOP');
+    } else if (statusFilter === 'warning') {
+      filtered = filtered.filter((r) => r.status === 'WARN' || r.status === 'STOP');
+    }
+
+    // Apply sort
+    filtered.sort((a, b) => {
+      let cmp = 0;
+      if (sort === 'name') {
+        cmp = a.name.localeCompare(b.name);
+      } else if (sort === 'cost') {
+        cmp = a.mtdCost - b.mtdCost;
+      } else if (sort === 'activity') {
+        cmp = a.activity - b.activity;
+      }
+      return sortDir === 'desc' ? -cmp : cmp;
+    });
+
+    return filtered;
+  }, [
+    projects,
+    statusMap,
+    search,
+    sort,
+    sortDir,
+    statusFilter,
+    deriveStatus,
+    calculateDeltaFromSparkline,
+  ]);
+
+  // Render loading state
+  if (loading) {
+    return (
+      <div className="p-6 bg-white dark:bg-slate-950 min-h-screen">
+        <LoadingSkeleton />
+      </div>
+    );
+  }
+
+  // Render error state
+  if (error) {
+    return (
+      <div className="p-6 bg-white dark:bg-slate-950 min-h-screen">
+        <ErrorState message={error} onRetry={() => fetchData()} />
+      </div>
+    );
+  }
+
+  return (
+    <div className="p-6 bg-white dark:bg-slate-950 min-h-screen space-y-6">
+      {/* Header with controls */}
+      <LiveHeader
+        period={period}
+        onPeriodChange={handlePeriodChange}
+        search={search}
+        onSearchChange={handleSearchChange}
+        isRefreshing={isRefreshing}
+        onExport={handleExport}
+      />
+
+      {/* Tab Navigation */}
+      <div className="flex gap-1 p-1 bg-gray-100/50 dark:bg-slate-800/50 rounded-sm w-fit">
+        <button
+          type="button"
+          onClick={() => handleTabChange('overview')}
+          className={`px-4 py-1.5 text-xs font-mono uppercase tracking-wider rounded-sm transition-all ${
+            tab === 'overview'
+              ? 'bg-gray-200 dark:bg-slate-700 text-gray-900 dark:text-slate-100'
+              : 'text-gray-600 dark:text-slate-400 hover:text-gray-700 dark:hover:text-slate-300 hover:bg-gray-200/50 dark:hover:bg-slate-700/50'
+          }`}
+        >
+          Overview
+        </button>
+        <button
+          type="button"
+          onClick={() => handleTabChange('features')}
+          className={`px-4 py-1.5 text-xs font-mono uppercase tracking-wider rounded-sm transition-all ${
+            tab === 'features'
+              ? 'bg-gray-200 dark:bg-slate-700 text-gray-900 dark:text-slate-100'
+              : 'text-gray-600 dark:text-slate-400 hover:text-gray-700 dark:hover:text-slate-300 hover:bg-gray-200/50 dark:hover:bg-slate-700/50'
+          }`}
+        >
+          Features
+        </button>
+      </div>
+
+      {/* Alert Banner - shows critical alerts */}
+      <AlertBanner
+        services={services}
+        burnRate={burnRate}
+        onDismiss={handleDismissAlert}
+        dismissedAlerts={dismissedAlerts}
+      />
+
+      {tab === 'overview' && (
+        <>
+          {/* Activity Chart */}
+          <section>
+            <h2 className="text-sm font-semibold text-gray-600 dark:text-slate-400 uppercase tracking-wider mb-3">
+              Activity Timeline
+            </h2>
+            <UsageChart
+              data={usageData}
+              loading={isRefreshing && usageData.length === 0}
+              period={period}
+              granularData={granularData}
+              chartType="stacked"
+            />
+          </section>
+
+          {/* Hero Cards */}
+          <HeroCardsRow
+            burnRate={burnRate}
+            services={services}
+            projects={tableRows}
+            billingContext={billingContext}
+            usageTotals={
+              granularData?.totals?.byTool
+                ? (Object.fromEntries(
+                    Object.entries(granularData.totals.byTool).map(([k, v]) => [k, v.requests])
+                  ) as Record<
+                    | 'workers'
+                    | 'd1'
+                    | 'kv'
+                    | 'r2'
+                    | 'vectorize'
+                    | 'durableObjects'
+                    | 'queues'
+                    | 'workersAI'
+                    | 'pages',
+                    number
+                  >)
+                : undefined
+            }
+            onMTDSpendClick={handleMTDSpendClick}
+            onPlanUtilisationClick={handlePlanUtilisationClick}
+            onTopSpenderClick={handleTopSpenderClick}
+            onSystemHealthClick={handleSystemHealthClick}
+          />
+
+          {/* Projects Table */}
+          <section id="projects-section">
+            <div className="flex items-center justify-between mb-3">
+              <h2 className="text-sm font-semibold text-gray-600 dark:text-slate-400 uppercase tracking-wider">
+                Projects
+              </h2>
+              {statusFilter !== 'all' && (
+                <button
+                  type="button"
+                  onClick={() => setStatusFilter('all')}
+                  className="text-xs text-blue-500 dark:text-blue-400 hover:text-blue-600 dark:hover:text-blue-300 transition-colors"
+                >
+                  Clear filter ({statusFilter})
+                </button>
+              )}
+            </div>
+            <ProjectsTable
+              rows={tableRows}
+              expanded={expanded}
+              onExpand={handleExpand}
+              onSort={handleSortChange}
+              sort={sort}
+              sortDir={sortDir}
+              resourceCache={resourceCache}
+              fetchResourceBreakdown={fetchResourceBreakdown}
+            />
+          </section>
+
+          {/* Recommendations */}
+          <section id="recommendations-section" className="transition-all duration-300 rounded-sm">
+            <Recommendations services={services} projects={projects} burnRate={burnRate} />
+          </section>
+        </>
+      )}
+
+      {tab === 'features' && (
+        <div className="space-y-6">
+          {/* Feature Budgets Table */}
+          <section>
+            <FeatureBudgets />
+          </section>
+
+          {/* Circuit Breaker Events Log */}
+          <section>
+            <CircuitBreakerEvents />
+          </section>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default UnifiedShell;