Frontend Domain Architecture
Relevant source files
The following files were used as context for generating this wiki page:
OpenWork's frontend architecture is built on a modular, domain-driven React runtime designed to replace the legacy Solid.js implementation. This architecture emphasizes explicit domain ownership, where feature-scoped code is organized into specific folders to ensure maintainability and a clear separation of concerns.
The architecture follows a "local-first, cloud-ready" philosophy, functioning as a practical control surface for agentic workflows. It is structured to consume OpenWork server APIs directly, treating the desktop application as a client of the server's API surface.
Sources: apps/app/src/react-app/ARCHITECTURE.md:1-10, AGENTS.md:5-15
Domain Structure and Organization
The React application is organized into several top-level directories under src/react-app/. Each directory has a specific role in the application lifecycle, from bootstrapping to feature implementation.
| Directory | Purpose |
|---|---|
shell/ | App bootstrap, providers composition, and startup effects. |
kernel/ | App-wide state management and provider contracts. |
infra/ | React-only runtime infrastructure (e.g., QueryClient). |
design-system/ | Reusable presentational primitives and modal components. |
domains/ | Feature-scoped code (Session, Workspace, Settings, etc.). |
Sources: apps/app/src/react-app/ARCHITECTURE.md:13-30
Feature Domains
The domains/ folder is partitioned by product functional areas. This ensures that every feature has a single, obvious home, reducing the "pseudo-flat" structure found in previous iterations.
- session/: Owns the session route, transcript rendering, composer, and session state plumbing (
sync/). - workspace/: Manages workspace-specific flows such as creation, sharing, and renaming.
- settings/: Contains settings state, individual tab pages (Plugins, Extensions, Config), and modals.
- connections/: Handles MCP (Model Context Protocol) and provider authentication UI.
- shell-feedback/: Manages global UI elements like toasts, notifications, and reload banners.
Sources: apps/app/src/react-app/ARCHITECTURE.md:32-46
Data Flow and Component Composition
The application utilizes a nested provider pattern to manage global state and SDK access. The entry point (index.react.tsx) wraps the application in a series of context providers that follow a specific composition order.
This diagram shows the hierarchical structure of React providers and how they flow into specific functional domains.
Sources: apps/app/src/react-app/ARCHITECTURE.md:48-75
State Management
OpenWork utilizes several specialized tools for state management, prioritizing performance and framework-agnostic logic where possible:
- Zustand: Used in
react-app/kernel/store.tsas the primary React replacement for legacy state bags. - TanStack Query: Managed as a singleton in
react-app/infra/query-client.tsfor server-state caching and synchronization. - Domain-Specific Hooks: Feature-specific state that is tightly coupled to a single domain lives within that domain (e.g.,
domains/session/sync/). - Framework-Agnostic Logic: Core logic resides in
src/app/(outside the React tree) and is consumed by both the React and legacy runtimes. This includesopencodelibraries, Tauri integration, and utility functions.
Sources: apps/app/src/react-app/ARCHITECTURE.md:77-104
Routing and Resource Identity
Workspace and session identity are treated as route state rather than global mutable state. This ensures that URLs are the source of truth for the application's current context.
Canonical Routes
The application uses specific URL patterns to define scope:
/workspace/:workspaceId/session/:sessionId/workspace/:workspaceId/settings/:tab
Routing Rules
- Authority: The URL
workspaceIdandsessionIdparameters are authoritative. Legacy state values (e.g.,activeWorkspace) are used only as fallbacks. - Strict Resolution: Missing URL resources do not fall back to defaults; instead, they trigger a "not-found" state to prompt user selection.
- Redirection: Compatibility entry points (like
/session) redirect to full workspace-scoped URLs once the workspace context is resolved.
Sources: apps/app/src/react-app/ARCHITECTURE.md:106-135
System Gates and Safety
The architecture includes safety mechanisms to ensure the frontend environment matches the underlying system requirements, specifically for the desktop application.
Architecture Mismatch Gate
The ArchitectureMismatchGate prevents the application from starting if the Electron build architecture does not match the system architecture (e.g., running x64 on arm64). This is critical for preventing runtime issues with sidecars and browser tooling.
This diagram illustrates the startup check performed by the Architecture Mismatch Gate.
Sources: apps/app/src/react-app/shell/architecture-mismatch-gate.tsx:55-85
Implementation Guidelines
The frontend development follows strict coding and UI guidelines to ensure consistency:
- Technology Stack: Preferences include Tailwind CSS, TypeScript, React, shadcn/ui (Base UI), TanStack Query, Zustand, Zod, and Framer Motion.
- Conciseness: Developers are instructed to use the smallest possible diffs and avoid fallback expressions when types guarantee a value.
- Component Reuse: New components should prefer shadcn/ui and existing primitives from
@/components. - Testing Requirement: PRs must include evidence of end-to-end flows, preferably via video or screenshots, ensuring regressions in wiring (not just types) are caught.
Sources: AGENTS.md:37-65, apps/app/package.json:50-95, evals/react-session-flows.md:5-15
Summary
The Frontend Domain Architecture of OpenWork represents a transition toward a more structured, scalable React-based system. By utilizing explicit domain ownership, route-driven state, and a robust provider hierarchy, the project achieves a clear separation between infrastructure and feature logic. This modularity supports the application's "local-first" philosophy while maintaining compatibility with remote agent workflows.
Sources: apps/app/src/react-app/ARCHITECTURE.md:1-20, AGENTS.md:5-15