perf(analytics): add cache pre-warming and SWR pattern for instant page load

- Add server-side cache pre-warming on startup (non-blocking)
- Implement stale-while-revalidate pattern (1hr stale window)
- Add /api/usage/status endpoint for cache status
- Remove full-page blocking skeleton, use per-component loading
- Add "Updated X ago" timestamp indicator in UI header
- Export AnalyticsSkeleton component for potential future use

Author: kaitranntt

docs/project-roadmap.md

@@ -440,6 +440,7 @@ src/types/
    - Intelligent profile selection algorithms
    - Cost estimation with typed calculation models
    - Performance optimization through type-aware caching
+   - Recently implemented significant UI improvements for analytics dashboard, enhancing data presentation.
 
 2. **Enhanced Session Management**
    - Type-safe session persistence with serialization
@@ -584,21 +585,29 @@ src/types/
 - **User Experience**: One-command channel switching without data loss
 - **Backward Compatibility**: Zero breaking changes, existing workflows preserved
 
-### Version 4.5.1 - UI Layout Improvements
+### Version 4.5.1 - UI Quality Gate Fixes & Layout Improvements
 **Release Date**: 2025-12-08
 
 #### UI Fixes & Improvements
+- ✅ **Auto-formatting**: 31 UI files auto-formatted for consistent styling.
+- ✅ **Fast Refresh Exports**: Resolved `react-refresh/only-export-components` by extracting `buttonVariants`, `useSidebar`, and `useWebSocketContext` to separate files.
+- ✅ **React Hooks Issues**: Fixed `react-hooks/purity` (`Math.random()` in `useMemo` for `sidebar.tsx`) and `react-hooks/set-state-in-effect` (`use-theme.ts`, `settings.tsx`).
+- ✅ **useWebSocket Hook Restructure**: Addressed `react-hooks/immutability` errors and dependency array warnings in `use-websocket.ts`.
+- ✅ **TypeScript Strict Mode**: Implemented null-check for `document.getElementById('root')` in `src/main.tsx` for strict mode compliance.
+- ✅ **Duplicate Directory Removal**: Cleaned up extraneous `ui/@/` directory.
 - ✅ **CLIProxy Card Padding**: Removed excessive padding from CLIProxy cards for better visual integration.
-- ✅ **CLIProxy Dashboard Layout**: Improved overall layout and styling of the CLIProxy dashboard for enhanced user experience.
-- ✅ **Dropdown Styling**: Refined dropdown component styling for consistency and readability.
+- ✅ **CLIProxy Dashboard Layout**: Improved overall layout and styling of the CLIProxy dashboard.
+- ✅ **Dropdown Styling**: Refined dropdown component styling.
+- ✅ **Model Usage Card**: Corrected icon display and refined donut chart styling.
 
 #### Technical Improvements
 - **Improved UI Responsiveness**: Adjustments ensure better display across various screen sizes.
 - **Enhanced User Experience**: Minor visual tweaks lead to a more polished and intuitive interface.
 
 #### Validation Results
-- **UI Rendering**: ✅ All UI components render correctly after layout adjustments.
+- **UI Rendering**: ✅ All UI components render correctly after adjustments and fixes.
 - **Functional Impact**: ✅ No regressions introduced, core functionality remains stable.
+- **Code Quality**: ✅ All ESLint and TypeScript quality gates passed after fixes.
 
 ---
 

src/web-server/index.ts

@@ -77,6 +77,13 @@ export async function startServer(options: ServerOptions): Promise<ServerInstanc
   // Start listening
   return new Promise<ServerInstance>((resolve) => {
     server.listen(options.port, () => {
+      // Non-blocking prewarm: load usage cache in background
+      import('./usage-routes').then(({ prewarmUsageCache }) => {
+        prewarmUsageCache().catch(() => {
+          // Error already logged in prewarmUsageCache
+        });
+      });
+
       resolve({ server, wss, cleanup });
     });
   });

src/web-server/usage-routes.ts

@@ -50,6 +50,17 @@ const CACHE_TTL = {
   session: 60 * 1000, // 1 minute - user may refresh
 };
 
+// Stale-while-revalidate: max age for stale data (1 hour)
+const STALE_TTL = 60 * 60 * 1000;
+
+// Track when data was last fetched (for UI indicator)
+let lastFetchTimestamp: number | null = null;
+
+/** Get timestamp of last successful data fetch */
+export function getLastFetchTimestamp(): number | null {
+  return lastFetchTimestamp;
+}
+
 // In-memory cache
 const cache = new Map<string, CacheEntry<unknown>>();
 
@@ -59,15 +70,38 @@ const pendingRequests = new Map<string, Promise<unknown>>();
 /**
  * Get cached data or fetch from loader with TTL
  * Also coalesces concurrent requests to prevent duplicate library calls
+ * Implements stale-while-revalidate pattern for instant responses
  */
 async function getCachedData<T>(key: string, ttl: number, loader: () => Promise<T>): Promise<T> {
-  // Check cache first
   const cached = cache.get(key) as CacheEntry<T> | undefined;
-  if (cached && Date.now() - cached.timestamp < ttl) {
+  const now = Date.now();
+
+  // Fresh cache - return immediately
+  if (cached && now - cached.timestamp < ttl) {
     return cached.data;
   }
 
-  // Check if request is already pending (coalesce)
+  // Stale cache - return immediately, refresh in background (SWR pattern)
+  if (cached && now - cached.timestamp < STALE_TTL) {
+    // Fire and forget background refresh if not already pending
+    if (!pendingRequests.has(key)) {
+      const promise = loader()
+        .then((data) => {
+          cache.set(key, { data, timestamp: Date.now() });
+          lastFetchTimestamp = Date.now();
+        })
+        .catch((err) => {
+          console.error(`[!] Background refresh failed for ${key}:`, err);
+        })
+        .finally(() => {
+          pendingRequests.delete(key);
+        });
+      pendingRequests.set(key, promise);
+    }
+    return cached.data;
+  }
+
+  // No usable cache - check if request is already pending (coalesce)
   const pending = pendingRequests.get(key) as Promise<T> | undefined;
   if (pending) {
     return pending;
@@ -77,6 +111,7 @@ async function getCachedData<T>(key: string, ttl: number, loader: () => Promise<
   const promise = loader()
     .then((data) => {
       cache.set(key, { data, timestamp: Date.now() });
+      lastFetchTimestamp = Date.now();
       return data;
     })
     .finally(() => {
@@ -115,6 +150,28 @@ export function clearUsageCache(): void {
   cache.clear();
 }
 
+/**
+ * Pre-warm usage caches on server startup
+ * Loads all usage data into cache so first user request is instant
+ * Returns timestamp when cache was populated
+ */
+export async function prewarmUsageCache(): Promise<{ timestamp: number; elapsed: number }> {
+  const start = Date.now();
+  console.log('[i] Pre-warming usage cache...');
+
+  try {
+    await Promise.all([getCachedDailyData(), getCachedMonthlyData(), getCachedSessionData()]);
+
+    const elapsed = Date.now() - start;
+    lastFetchTimestamp = Date.now();
+    console.log(`[OK] Usage cache ready (${elapsed}ms)`);
+    return { timestamp: lastFetchTimestamp, elapsed };
+  } catch (err) {
+    console.error('[!] Failed to prewarm usage cache:', err);
+    throw err;
+  }
+}
+
 // ============================================================================
 // Validation Helpers
 // ============================================================================
@@ -494,3 +551,19 @@ usageRoutes.post('/refresh', (_req: Request, res: Response) => {
     message: 'Usage cache cleared',
   });
 });
+
+/**
+ * GET /api/usage/status
+ *
+ * Returns cache status including last fetch timestamp.
+ * Used by UI to show "Last updated: X ago" indicator.
+ */
+usageRoutes.get('/status', (_req: Request, res: Response) => {
+  res.json({
+    success: true,
+    data: {
+      lastFetch: lastFetchTimestamp,
+      cacheSize: cache.size,
+    },
+  });
+});

ui/src/components/analytics/model-breakdown-chart.tsx

@@ -6,7 +6,7 @@
  */
 
 import { useMemo } from 'react';
-import { PieChart, Pie, Cell, ResponsiveContainer, Tooltip, Legend } from 'recharts';
+import { PieChart, Pie, Cell, ResponsiveContainer, Tooltip } from 'recharts';
 import { Skeleton } from '@/components/ui/skeleton';
 import type { ModelUsage } from '@/hooks/use-usage';
 import { cn } from '@/lib/utils';
@@ -66,45 +66,41 @@ export function ModelBreakdownChart({ data, isLoading, className }: ModelBreakdo
 
     const data = payloadArray[0].payload;
     return (
-      <div className="rounded-lg border bg-background p-3 shadow-lg">
-        <p className="font-medium mb-2">{data.name}</p>
-        <p className="text-sm text-muted-foreground">
-          Tokens: {formatNumber(data.value)} ({data.percentage.toFixed(1)}%)
+      <div className="rounded-lg border bg-background p-2 shadow-lg text-xs">
+        <p className="font-medium mb-1">{data.name}</p>
+        <p className="text-muted-foreground">
+          {formatNumber(data.value)} ({data.percentage.toFixed(1)}%)
         </p>
-        <p className="text-sm text-muted-foreground">Cost: ${data.cost.toFixed(4)}</p>
-        <p className="text-sm text-muted-foreground">Requests: {data.requests}</p>
+        <p className="text-muted-foreground">${data.cost.toFixed(4)}</p>
       </div>
     );
   };
 
   const renderLabel = (entry: { percentage: number }) => {
-    return `${entry.percentage.toFixed(1)}%`;
+    return entry.percentage > 5 ? `${entry.percentage.toFixed(1)}%` : '';
   };
 
   return (
     <div className={cn('w-full', className)}>
-      <ResponsiveContainer width="100%" height={300}>
+      <ResponsiveContainer width="100%" height={250}>
         <PieChart>
           <Pie
             data={chartData}
             cx="50%"
             cy="50%"
             labelLine={false}
             label={renderLabel}
-            outerRadius={100}
-            fill="#8884d8"
+            innerRadius={60}
+            outerRadius={80}
+            paddingAngle={2}
             dataKey="value"
           >
             {chartData.map((entry, index) => (
-              <Cell key={`cell-${index}`} fill={entry.fill} />
+              <Cell key={`cell-${index}`} fill={entry.fill} strokeWidth={1} />
             ))}
           </Pie>
           <Tooltip content={renderTooltip} />
-          <Legend
-            verticalAlign="bottom"
-            height={36}
-            formatter={(value) => <span className="text-sm">{value}</span>}
-          />
+          {/* Legend removed from here, moved to AnalyticsPage for better layout control */}
         </PieChart>
       </ResponsiveContainer>
     </div>

ui/src/components/analytics/sessions-table.tsx

@@ -33,7 +33,7 @@ export function SessionsTable({ data, isLoading }: SessionsTableProps) {
   const [currentPage, setCurrentPage] = useState(0);
 
   // Get sessions array (stable reference for memoization)
-  const sessions = data?.sessions ?? [];
+  const sessions = useMemo(() => data?.sessions ?? [], [data?.sessions]);
 
   // Filter sessions based on search term
   const filteredSessions = useMemo(() => {

ui/src/components/analytics/usage-summary-cards.tsx

@@ -73,19 +73,19 @@ export function UsageSummaryCards({ data, isLoading }: UsageSummaryCardsProps) {
   ];
 
   return (
-    <div className="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-4 gap-4">
+    <div className="grid grid-cols-2 md:grid-cols-4 gap-4">
       {cards.map((card, index) => {
         const Icon = card.icon;
         return (
           <Card key={index} className="hover:shadow-md transition-shadow">
-            <CardContent className="p-6">
-              <div className="flex items-center justify-between">
-                <div className="space-y-1">
-                  <p className="text-sm font-medium text-muted-foreground">{card.title}</p>
-                  <p className="text-2xl font-bold">{card.format(card.value)}</p>
+            <CardContent className="p-4">
+              <div className="flex items-center justify-between space-x-2">
+                <div className="space-y-1 min-w-0">
+                  <p className="text-xs font-medium text-muted-foreground truncate">{card.title}</p>
+                  <p className="text-xl font-bold truncate">{card.format(card.value)}</p>
                 </div>
-                <div className={cn('p-2 rounded-lg', card.bgColor)}>
-                  <Icon className={cn('h-5 w-5', card.color)} />
+                <div className={cn('p-2 rounded-lg shrink-0', card.bgColor)}>
+                  <Icon className={cn('h-4 w-4', card.color)} />
                 </div>
               </div>
             </CardContent>

ui/src/components/analytics/usage-trend-chart.tsx

@@ -38,7 +38,7 @@ export function UsageTrendChart({
   const chartData = useMemo(() => {
     if (!data || data.length === 0) return [];
 
-    return data.map((item) => ({
+    return [...data].reverse().map((item) => ({
       ...item,
       dateFormatted: formatDate(item.date, granularity),
       costRounded: Number(item.cost.toFixed(4)),

ui/src/hooks/use-usage.ts

@@ -65,6 +65,11 @@ export interface UsageQueryOptions {
   offset?: number;
 }
 
+export interface UsageStatus {
+  lastFetch: number | null;
+  cacheSize: number;
+}
+
 // API
 const BASE_URL = '/api';
 
@@ -125,6 +130,8 @@ export const usageApi = {
       throw new Error('Failed to refresh usage cache');
     }
   },
+  /** Get cache status including last fetch timestamp */
+  status: () => request<UsageStatus>('/usage/status'),
 };
 
 // Helper function to match existing API client pattern
@@ -200,3 +207,16 @@ export function useRefreshUsage() {
 
   return refresh;
 }
+
+/**
+ * Hook to get usage cache status
+ * Returns last fetch timestamp for "Last updated" UI indicator
+ */
+export function useUsageStatus() {
+  return useQuery({
+    queryKey: ['usage', 'status'],
+    queryFn: () => usageApi.status(),
+    staleTime: 10 * 1000, // 10 seconds - poll frequently for updates
+    refetchInterval: 30 * 1000, // Auto-refetch every 30 seconds
+  });
+}