Component Hierarchy¶

// frontend/src/components/layout/Layout.tsx:30-32
interface LayoutProps {
  children: ReactNode;
}

Layout
  |- SkipLink                 # Accessibility: skip to main content
  |- Header                   # Top navigation bar
  |- flex container
  |    |- Sidebar            # Desktop navigation (hidden on mobile)
  |    |- Mobile Overlay     # Backdrop for mobile menu
  |    |- Main Content
  |         |- ConnectionStatusBanner
  |         |- ServiceStatusAlert
  |         |- {children}    # Page content
  |- CommandPalette          # Global command palette (Cmd+K)
  |- ShortcutsHelpModal      # Keyboard shortcuts help
  |- MobileBottomNav         # Mobile navigation (shown on mobile)

// frontend/src/App.tsx:32-34
// Dashboard is loaded eagerly since it's the landing page
const DashboardPage = lazy(() => import('./components/dashboard/DashboardPage'));

// frontend/src/App.tsx:39-42
// Module re-export pattern for barrel exports
const AnalyticsPage = lazy(() =>
  import('./components/analytics').then((module) => ({ default: module.AnalyticsPage }))
);

// Typical page component structure
function PageComponent() {
  // 1. Navigation hooks
  const navigate = useNavigate();

  // 2. Data hooks (React Query or WebSocket)
  const { data, isLoading, error } = useDataQuery();
  const { events, isConnected } = useEventStream();

  // 3. Local state
  const [filter, setFilter] = useState('');

  // 4. Derived state (useMemo)
  const filteredData = useMemo(() => /* ... */, [data, filter]);

  // 5. Event handlers (useCallback)
  const handleAction = useCallback(() => /* ... */, []);

  // 6. Effects for side effects
  useEffect(() => { /* initial load */ }, []);

  // 7. Loading state
  if (isLoading) return <LoadingSkeleton />;

  // 8. Error state
  if (error) return <ErrorDisplay error={error} />;

  // 9. Main render
  return <PageLayout>/* ... */</PageLayout>;
}

// frontend/src/components/dashboard/DashboardPage.tsx:365-501
<DashboardLayout
  widgetProps={{
    statsRow: { /* props */ },
    cameraGrid: { /* props */ },
    activityFeed: { /* props */ },
  }}
  renderStatsRow={(props) => <StatsRow {...props} />}
  renderCameraGrid={(props) => <CameraGrid {...props} />}
  renderActivityFeed={(props) => <ActivityFeed {...props} />}
/>

// frontend/src/components/layout/sidebarNav.ts
export const navGroups: NavGroup[] = [
  {
    id: 'monitoring',
    label: 'Monitoring',
    defaultExpanded: true,
    items: [
      { id: 'dashboard', path: '/', label: 'Dashboard', icon: LayoutDashboard },
      { id: 'timeline', path: '/timeline', label: 'Timeline', icon: Clock },
      // ...
    ],
  },
  // ...
];

// frontend/src/components/layout/Sidebar.tsx:14-24
function loadExpansionState(): Record<string, boolean> {
  try {
    const stored = localStorage.getItem(STORAGE_KEY);
    if (stored) {
      return JSON.parse(stored) as Record<string, boolean>;
    }
  } catch {
    // Ignore parse errors
  }
  return {};
}

// frontend/src/components/dashboard/DashboardPage.tsx:513-531
function DashboardPageWithErrorBoundary() {
  return (
    <FeatureErrorBoundary
      feature="Dashboard"
      fallback={
        <div className="flex min-h-screen flex-col items-center justify-center bg-[#121212] p-8">
          <AlertTriangle className="mb-4 h-12 w-12 text-red-400" />
          <h3 className="mb-2 text-lg font-semibold text-red-400">Dashboard Unavailable</h3>
          <p className="max-w-md text-center text-sm text-gray-400">
            Unable to load the security dashboard. Please refresh the page or try again later.
          </p>
        </div>
      }
    >
      <DashboardPage />
    </FeatureErrorBoundary>
  );
}

// Example: SummaryCards compound component
<SummaryCards>
  <SummaryCards.Hourly data={hourly} />
  <SummaryCards.Daily data={daily} />
</SummaryCards>

// Pattern for filter inputs
function FilterInput({ value, onChange }: FilterInputProps) {
  return (
    <input
      type="text"
      value={value}
      onChange={(e) => onChange(e.target.value)}
      className="..."
    />
  );
}

// DashboardLayout render props pattern
interface DashboardLayoutProps {
  widgetProps: WidgetProps;
  renderStatsRow: (props: StatsRowProps) => ReactNode;
  renderCameraGrid: (props: CameraGridProps) => ReactNode;
}

// frontend/src/components/layout/Layout.tsx:88-99
{/* Hide sidebar on mobile, show MobileBottomNav instead */}
{!isMobile && <Sidebar />}

{/* Mobile overlay backdrop */}
{isMobileMenuOpen && (
  <div
    className="fixed inset-0 z-30 bg-black/50 md:hidden"
    onClick={() => setMobileMenuOpen(false)}
    aria-hidden="true"
    data-testid="mobile-overlay"
  />
)}