# Logical Components — react-frontend-app

## Component/Provider Overview

```mermaid
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. |