SlpSoftware/aidlc-docs/features/react-frontend/construction/react-frontend-app/nfr-design/logical-components.md

Logical Components — react-frontend-app

Component/Provider Overview

graph TD
    router["Router Instance\n(TanStack Router, hash history)"]
    query_client["QueryClientProvider\n(staleTime: Infinity for placeholder queries)"]
    theme_provider["ThemeProvider\n(theme state + localStorage persistence)"]
    error_boundary["ErrorBoundary\n(on-brand fallback UI)"]
    root_route["Root Route (__root.tsx)"]
    fonts["Self-hosted Fonts\n(bundled static assets)"]

    router --> root_route
    root_route --> error_boundary
    error_boundary --> theme_provider
    theme_provider --> query_client
    root_route -.->|"loads"| fonts

    classDef infra fill:#9C27B0,stroke:#4a148c,stroke-width:1px,color:#000;
    classDef guard fill:#FF9800,stroke:#e65100,stroke-width:1px,color:#000;
    classDef layout fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000;
    classDef asset fill:#4CAF50,stroke:#2e7d32,stroke-width:1px,color:#000;

    class router,query_client infra;
    class error_boundary guard;
    class theme_provider,root_route layout;
    class fonts asset;

Text alternative: The router hosts the root route, which is wrapped by an ErrorBoundary, which wraps ThemeProvider, which wraps QueryClientProvider; the root route also loads self-hosted font assets (purple = infra provider, orange = guard/boundary, blue = layout/route, green = static asset).

Logical Component Definitions

Component	Type	Responsibility
Router Instance	Infrastructure	Created via TanStack Router with createHashHistory(); defines the root route and index route tree.
QueryClientProvider	Infrastructure	Wraps the app with a single shared QueryClient; configures default staleTime: Infinity for this iteration's placeholder queries.
ThemeProvider	Layout/Context	Owns theme state ('red' | 'purple'), reads/writes localStorage, applies the active theme class to the document root; exposes theme + toggleTheme() via React context (implements BR-1, BR-2, BR-3).
ErrorBoundary	Guard	Top-level React error boundary; renders the on-brand fallback UI on unexpected render errors (implements the Resilience Pattern).
Root Route (__root.tsx)	Layout/Route	Composes ErrorBoundary → ThemeProvider → QueryClientProvider → RootLayout (Nav/Footer) → routed content (<Outlet />).
Self-hosted Fonts	Static Asset	Sora, Instrument Sans, and JetBrains Mono font files bundled with the app and declared via local @font-face/@fontsource imports — no external CDN dependency.