slp-modular-cms/aidlc-docs/features/cms-frontend/construction/unit-1/nfr-design/logical-components.md

Logical Components — Unit 1: Project Scaffold & Infrastructure

Component Overview

The frontend scaffold is composed of the following logical components that realize the NFR design patterns.

Mermaid Diagram — Component Interaction (colored by layer)

graph TD
    Root[Root App] --> Router[TanStack Router]
    Router --> AuthLayout[Auth Layout]
    Router --> PublicRoutes[Public Routes]
    AuthLayout --> Dash[Dashboard]
    AuthLayout --> Users[Users]
    AuthLayout --> Cms[CMS Mgmt]

    Root --> I18n[i18next Provider]
    Root --> Toast[Toast Provider]
    Root --> Api[ApiClient]

    Api --> MSW[MSW Handlers]
    Api --> AuthCtx[AuthContext]

    classDef root fill:#e9d5ff,stroke:#6b21a8,stroke-width:2px,color:#6b21a8;
    classDef provider fill:#bae6fd,stroke:#0369a1,stroke-width:2px,color:#0369a1;
    classDef client fill:#fed7aa,stroke:#c2410c,stroke-width:2px,color:#c2410c;
    classDef route fill:#c6f6d5,stroke:#22543d,stroke-width:2px,color:#22543d;

    class Root root;
    class I18n,Toast,AuthCtx provider;
    class Api,MSW client;
    class Router,AuthLayout,PublicRoutes,Dash,Users,Cms route;

Text alternative: Root bootstraps providers (i18n, toast, auth) and TanStack Router; authenticated routes live under a layout protected by AuthContext; API client is shared and uses MSW in tests.

Key Logical Components

Component	Responsibility	NFR / BR Link
ApiClient	fetch wrapper with credentials, throws ProblemDetailsError	BR-U1-03, BR-U1-04, NFR-U1-05 (error mapping)
AuthContext	in-memory token + user state, silent refresh on mount	BR-U1-01, BR-U1-02
I18nProvider	react-i18next + detector + lazy locale loader	NFR-U1-05, Q4-B
ToastProvider	shadcn/ui toast primitive exposed via useToast()	NFR-U1-03, Q5-B
MSW Handlers	feature-scoped mock handlers under src/mocks/	NFR-U1-04, Q3-B
Route Modules	lazy-loaded per-feature route files	NFR-U1-01, Q1-A
FocusTrap	radix/shadcn dialog primitive for modals only	NFR-U1-02, Q2-A
vite-env.d.ts	typed import.meta.env + optional Zod config hook	NFR-U1-07, Q6-A

Integration Points

• All authenticated pages receive AuthContext via layout.
• Language switcher lives in the top-right user menu and updates both i18next and persisted preference.
• Error toasts are triggered from within pages or forms; 401 errors bubble to AuthContext.logout().
• Tests import handlers from src/mocks/index and wrap the component tree with all providers.

These components form a minimal, maintainable foundation that satisfies all NFR-U1 requirements without introducing heavy dependencies.