Frontend Application Architecture
Relevant source files
The following files were used as context for generating this wiki page:
- AGENTS.md
- frontend/package.json
- frontend/vite.config.ts
- frontend/src/features/workflows/hooks/useWorkflowsPage.ts
- frontend/src/features/workflows/components/WorkflowFlowEditor.tsx
- frontend/src/features/scraped-data/containers/ScrapedDataPageContainer.tsx
- frontend/src/hooks/useWebSocket.ts
- frontend/src/components/layout/app-sidebar.tsx
- convex/schema.ts
The frontend of this project is a modern React-based Single Page Application (SPA) built using React Router 7. It serves as the primary management interface for automation workflows, profile management, and data visualization. The architecture emphasizes a feature-based organization, where complex logic is encapsulated within specific feature directories such as workflows, scraped-data, and profiles.
The application leverages a real-time data layer powered by Convex for state management and database synchronization, supplemented by a custom WebSocket implementation for streaming live automation logs and progress updates. The UI is constructed using a suite of Radix UI primitives and Tailwind CSS, following a "semicolon-light" TypeScript style.
Sources: AGENTS.md:1-40, frontend/package.json:1-80
Core Technology Stack
The application is built on a modern toolchain designed for performance and developer experience.
| Category | Technology | Purpose |
|---|---|---|
| Framework | React Router 7 | Routing and application framework |
| State/Backend | Convex | Real-time database and reactive state |
| Styling | Tailwind CSS / Lucide | Utility-first styling and iconography |
| Workflow UI | React Flow | Visual graph-based workflow editor |
| Auth | Clerk | Authentication and identity management |
| Real-time | WebSockets | Live log streaming and agent status |
Sources: frontend/package.json:10-70, frontend/vite.config.ts:80-110
Project Structure and Routing
The frontend follows a modular architecture where the src/features/ directory contains the core business logic. Navigation is handled via a persistent sidebar that routes users between different management modules.
Component Layout Hierarchy
The UI is structured with a root layout that includes an AppSidebar and an AmbientGlow background effect.
The sidebar acts as the primary navigation hub, defining paths for profile management, workflow editing, and data monitoring.
Sources: frontend/src/components/layout/app-sidebar.tsx:40-100, AGENTS.md:25-35
Data Flow and State Management
The application utilizes three distinct data synchronization strategies:
- Convex Queries/Mutations: Used for persistent application state (workflows, profiles, artifacts). Queries are reactive, automatically updating the UI when data changes in the Convex backend.
- WebSockets: Used for ephemeral, high-frequency data such as live automation logs and real-time progress of running agents.
- Local State (React Hooks): Manages UI-specific states like dialog visibility, search queries, and flow editor viewports.
Real-time Log Streaming
The useWebSocket hook manages the connection to the server's /ws endpoint, handling reconnection logic with exponential backoff and jitter.
The hook includes a maxBuffer (default 500) to prevent memory leaks during long-running automation sessions.
Sources: frontend/src/hooks/useWebSocket.ts:140-300, frontend/src/features/profiles/hooks/useProfilesPage.ts:150-170
Feature: Workflow System
The workflow system is the most complex part of the frontend, consisting of a visual editor and a management dashboard.
Visual Flow Editor
The WorkflowFlowEditor uses reactflow to render a directed graph of "Activity Nodes".
- Node Types:
start(entry point) andactivity(custom blocks). - Persistence: Viewport positions are stored in
localStorageper workflow ID to maintain user context between sessions. - Editor Logic: Managed via
useFlowEditorState, which handles node insertion, edge connections, and node duplication.
Sources: frontend/src/features/workflows/components/WorkflowFlowEditor.tsx:20-50, frontend/src/features/workflows/hooks/useFlowEditorState.ts:1-100
Workflow Lifecycle Management
Workflows can be created, duplicated, exported to JSON, or imported. The import/export logic is strictly validated to ensure schema compatibility.
| Action | Function | Logic |
|---|---|---|
| Export | buildWorkflowExportEnvelope | Wraps nodes/edges in a versioned JSON envelope. |
| Import | validateWorkflowImport | Validates JSON structure, node counts (max 500), and activity IDs. |
| Scheduling | useWorkflowScheduling | Updates cron configurations and toggles active status in Convex. |
Sources: frontend/src/features/workflows/utils/workflowImportExport.ts:140-250, frontend/src/features/workflows/hooks/useWorkflowsPage.ts:250-320
Feature: Scraped Data Management
The ScrapedDataPageContainer manages the display and retrieval of artifacts generated by workflow runs.
- Artifact List: Displays a filtered and sorted list of
workflowArtifacts. - Data Retrieval: Downloads are handled via a custom
apiDownloadutility that communicates with the Express server's/api/workflows/artifacts/downloadendpoint, utilizing Convex storage IDs. - State Hook:
useScrapedDataStateprovides complex filtering logic, allowing users to search across artifact names, workflow names, and source profiles.
Sources: frontend/src/features/scraped-data/containers/ScrapedDataPageContainer.tsx:30-100, convex/schema.ts:124-150
Build and Deployment Configuration
The application uses Vite for building and development. The vite.config.ts includes sophisticated manualChunks logic to optimize the bundle size by splitting large dependencies.
| Chunk Name | Included Packages |
|---|---|
workflow-editor | reactflow, d3-*, zustand |
codemirror | @codemirror/*, @lezer/* |
react-core | react, react-dom, react-router, @clerk/* |
vnc | @novnc/novnc |
Sources: frontend/vite.config.ts:30-75
Conclusion
The Frontend Application Architecture is a robust, feature-oriented system that bridges visual workflow design with real-time automation monitoring. By centralizing core state in Convex and offloading high-frequency updates to WebSockets, the application maintains a responsive user interface while managing complex background automation tasks.