Frontend Architecture Overview

Frontend Architecture Overview

The frontend is a Next.js App Router application with a module-driven UI and provider-heavy client runtime.

Architecture Layers

1. App Routing Layer

• Next.js routes in src/app/* handle URL entry and auth-gated redirection.

2. Runtime Provider Layer

• Global providers in src/app/providers.tsx compose session, query cache, module access, tabs, lock state, notifications, chat socket, and UI overlays.

3. Module Navigation Layer

• moduleRegistry defines module keys, labels, icons, lazy components, and add-on nesting.
• ModuleAccessProvider filters available modules per user and produces sidebar-ready buttons.
• TabProvider tracks active ModuleKey in UI state.

4. Render Layer

• Handle validates route module access and synchronizes active tab.
• MainView and RenderComponent lazy-load module entry components.

5. Domain Layer

• Feature modules live under src/modules/*.
• Shared primitives live under src/components/* and src/context/*.

Key Frontend Concepts

• URL route and current tab are coordinated but distinct.
• Module visibility is permission-derived, not hardcoded in view components.
• Parent module entries can expose add-ons via nested children buttons.
• Many modules rely on shared component primitives (DynamicTable, TabManager, SidePanel, ListEngine).

Priority Risk Areas

• Provider ordering regressions in src/app/providers.tsx
• Module access filtering and add-on visibility
• Route/module mismatch handling in Handle
• Cross-tab state sync flows (lock, notifications, chat)