React Webapp Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The React Webapp (referred to as webapp_v2) serves as a modern shell and target for the incremental migration of the legacy ClojureScript frontend. It provides a cohesive UI experience using a modern tech stack while hosting the original application through a bridge component. This architecture allows the development team to migrate features one by one without a complete stop-and-rewrite of the platform.
Sources: webapp_v2/CONTEXT_MIGRATION.md:3-10, webapp_v2/README.md:12-20
Core Tech Stack
The application is built using React 19 and Vite, focusing on developer experience and performance.
| Category | Technology |
|---|---|
| Framework | React 19 |
| Build Tool | Vite |
| UI Library | Mantine v8 |
| State Management | Zustand |
| Routing | React Router v7 |
| HTTP Client | Axios |
| Icons | Lucide React |
Sources: webapp_v2/README.md:5-10, webapp_v2/package.json:17-27
Hybrid Shell Architecture
The "React Shell" wraps the legacy ClojureScript application. While React-native routes are handled directly by React components, any route not explicitly migrated falls through to a ClojureApp bridge component.
Integration Mechanism
The integration relies on several contracts to synchronize state between the two environments:
localStorage.react-shell = true: Signals the CLJS app to suppress its own sidebar and header to avoid UI duplication.window.hoopSetRoute(path): Synchronizes the React Router path to the CLJS Pushy router.window.hoopDispatch: A bridge allowing React to trigger Re-frame events in the CLJS environment.- Shared Auth: Both applications use the same
jwt-tokenkey inlocalStorage.
Sources: webapp_v2/CONTEXT_MIGRATION.md:32-48, webapp_v2/CONTEXT_MIGRATION.md:162-170
Request Flow Diagram
The following diagram illustrates how the Vite dev server handles requests by proxying specific assets to the legacy shadow-cljs server and the backend gateway.
Explanation: This diagram shows the routing logic where Vite either serves React pages directly or proxies legacy assets and API calls to their respective backend services.
Sources: webapp_v2/CONTEXT_MIGRATION.md:12-25, webapp_v2/README.md:27-36
State Management and State Mappings
State is managed primarily via Zustand stores, replacing the Re-frame subscription model used in the legacy application.
Store Responsibilities
| Store | File | Responsibility |
|---|---|---|
useAuthStore | stores/useAuthStore.js | Manages JWT tokens and redirect URLs. |
useUserStore | stores/useUserStore.js | Holds user profiles and permission flags (isAdmin, isFreeLicense). |
useUIStore | stores/useUIStore.js | Persists sidebar state (open/collapsed) to localStorage. |
useAgentStore | stores/useAgentStore.js | Handles CRUD operations for Agents. |
Sources: webapp_v2/CONTEXT_MIGRATION.md:112-120, webapp_v2/COMPONENTS.md:465-475
CLJS to React Pattern Mapping
Developers follow a strict mapping when migrating features:
Explanation: The migration strategy involves direct translation of Re-frame patterns into Zustand hooks and Mantine-based components.
Sources: webapp_v2/CLJS_PATTERNS.md:10-50, webapp_v2/CLJS_PATTERNS.md:130-150
Component Strategy
The architecture dictates that the application code never imports UI primitives directly from Mantine. Instead, all primitives are wrapped in src/components/ to ensure central ownership of the visual layer.
Key Shared Components
PageLoader: Centered spinner withuseMinDelayhook integration to prevent UI flashing.EmptyState: Standardized component for zero-data views including icons and CTAs.StepAccordion: A multi-step wizard pattern used for complex configurations like Agent creation.SourcedInput: Specialized input that combines text/password fields with credential source pickers (e.g., HashiCorp Vault, AWS Secrets Manager).
Sources: webapp_v2/COMPONENTS.md:4-15, webapp_v2/COMPONENTS.md:100-110, webapp_v2/COMPONENTS.md:215-225
Navigation and Authentication
The application detects authentication methods (Local Auth vs OAuth/IDP) automatically from the gateway configuration.
Auth Flow Sequence
Explanation: This sequence demonstrates the guard logic where the Auth store and API interceptors collaborate to enforce session validity.
Sources: webapp_v2/README.md:58-65, webapp_v2/CONTEXT_MIGRATION.md:124-128
Project Structure
The codebase is organized by functional responsibility:
src/pages/: Page-level components and local stores.src/stores/: Global Zustand state.src/services/: Axios-based API abstractions (one function per endpoint).src/components/: Reusable UI wrappers.src/hooks/: Custom logic likeusePaginatedConnectionsoruseMinDelay.
Sources: webapp_v2/README.md:71-80, webapp_v2/MIGRATION_CHECKLIST.md:23-35
Summary
The React Webapp Architecture is designed for a safe, iterative transition from ClojureScript to a modern React ecosystem. By utilizing a shell approach, shared authentication, and standardized component wrappers, the project maintains feature parity during migration while providing a foundation for new Enterprise-grade features.