OpenWork React 19 Vite Application Structure: Kernel, Shell, and Domains Explained

OpenWork's frontend uses a three-layer architecture—kernel, shell, and domains—to separate platform services, UI scaffolding, and feature modules within its React 19 + Vite codebase.

OpenWork's modern React 19 application structure leverages Vite (the I9 build preset) to deliver a cross-platform experience that runs both as a web app and as a desktop Electron application. The codebase organizes functionality into three distinct architectural layers that ensure platform-specific logic remains isolated in the kernel while feature development stays decoupled from infrastructure concerns.

The Three-Layer Architecture

The OpenWork React 19 Vite application structure divides the codebase into kernel, shell, and domains, each with specific responsibilities and directory locations under src/react-app/.

Kernel Layer: Platform-Agnostic Services

The kernel (src/react-app/kernel) provides low-level services that abstract platform differences between desktop and web environments, handle state persistence, and manage communication with the OpenWork server.

• platform.tsx – Defines the Platform context with OS detection, link handling, notifications, and storage abstractions. This file exposes the usePlatform hook that components throughout the app consume to perform platform-aware operations.
• local-provider.tsx – Manages UI state and user preferences, persisting data to window.localStorage and syncing with React state via the useLocal hook.
• server-provider.tsx – Bridges the client to the OpenWork server using WebSocket and RPC protocols.
• global-sync-provider.tsx and global-sdk-provider.tsx – Synchronize global state across multiple windows or Electron renderer processes and expose the OpenWork SDK to the application.

Shell Layer: Application Scaffolding

The shell (src/react-app/shell) assembles the top-level UI scaffolding, including provider injection, routing, and application chrome such as menus and overlays.

• app-root.tsx – The entry point that composes <PlatformProvider>, <LocalProvider>, and the router into the main application tree.
• providers.tsx – Wraps the application in kernel providers, ensuring all shell and domain components have access to platform services.
• command-palette.tsx – Implements the global command UI using the kernel's usePlatform hook to execute actions like app restarts and link opening.
• reload-coordinator.tsx – Handles hot-reload and graceful application restarts during development.
• app-menu.tsx, notification-center.tsx, cloud-workspace-overlay.tsx – UI chrome components that interact directly with kernel services to display menus, notifications, and workspace overlays.

Domains Layer: Feature Modules

The domains (src/react-app/domains) contain feature-level modules that implement user-facing product areas. Each domain lives in its own subdirectory and consumes kernel APIs exclusively through hooks like usePlatform and useLocal.

• session/ – Contains UI components for chat sessions, model pickers, and artifact handling.
• settings/ – Implements preference panels, notification settings, and user onboarding flows.
• cloud/ – Manages cloud sign-in, organization onboarding, and branding interfaces.

All domain components import kernel hooks using path aliases such as import { usePlatform } from "@/react-app/kernel/platform", maintaining strict boundaries between feature code and platform services.

How the Layers Interact

The OpenWork React 19 Vite application structure enforces unidirectional dependencies where domains depend on the shell, and the shell depends on the kernel, but never the reverse.

1. Kernel to Shell – The shell instantiates React context providers (PlatformProvider, LocalProvider, ServerProvider) defined in the kernel. Shell components like command-palette.tsx consume these contexts to perform actions such as opening external links or showing desktop notifications.

2. Shell to Domains – The shell's router maps URLs to domain entry points. Domain pages render inside the shell's layout defined in app-root.tsx, automatically inheriting kernel contexts through React's provider hierarchy.

3. Domains to Kernel – Domain components use usePlatform and useLocal hooks to read OS capabilities, persist user preferences, or trigger platform-specific behavior. For example, session pages import usePlatform to open external resources using the desktop API when running in Electron, or standard browser tabs when running on the web.

4. Global Synchronization – The global-sync-provider ensures UI state such as open workspaces remains consistent across multiple windows or renderer processes, leveraging the kernel's storage abstractions to coordinate state changes.

Practical Implementation Examples

The following patterns demonstrate how the OpenWork React 19 Vite application structure handles common tasks across architectural layers.

Creating a Platform-Aware Link

Domain components use the kernel's usePlatform hook to open links with the appropriate handler for the current environment:

import { usePlatform } from "@/react-app/kernel/platform";

export function DocsLink() {
  const platform = usePlatform();
  const openDocs = () => platform.openLink("https://openwork.ai/docs");
  return <button onClick={openDocs}>Open Docs</button>;
}

The openLink method in platform.tsx automatically determines whether to use the desktop API (Electron) or a standard browser tab based on the detected environment.

Persisting User Preferences

The local-provider.tsx kernel service enables domains to persist preferences without directly accessing storage APIs:

import { useLocal } from "@/react-app/kernel/local-provider";

export function ThinkingToggle() {
  const { prefs, setPrefs } = useLocal();
  const toggle = () => setPrefs(p => ({ ...p, showThinking: !p.showThinking }));
  return <Switch checked={prefs.showThinking} onChange={toggle} />;
}

Preferences automatically synchronize to window.localStorage and propagate across the component tree via React context.

Implementing Shell-Level Commands

The shell consumes kernel services to expose high-level commands through the command palette:

import { usePlatform } from "@/react-app/kernel/platform";

export function CommandPalette() {
  const platform = usePlatform();
  const reload = () => platform.restart();
  // Command UI implementation uses reload for graceful app restarts
}

This pattern keeps platform-specific restart logic encapsulated in the kernel while allowing the shell to present a unified command interface.

Summary

• Kernel layer (src/react-app/kernel) provides platform abstraction through providers like platform.tsx and local-provider.tsx, exposing capabilities via the usePlatform and useLocal hooks.
• Shell layer (src/react-app/shell) composes kernel providers in app-root.tsx and providers.tsx, handling routing, command palettes, and application chrome.
• Domains layer (src/react-app/domains) implements product features in isolated modules (session, settings, cloud) that consume kernel APIs exclusively through React hooks.
• Cross-platform compatibility is achieved by confining platform-specific logic to the kernel, allowing the same React 19 + Vite codebase to deploy as both a web application and an Electron desktop app.

Frequently Asked Questions

What is the purpose of the kernel layer in OpenWork's architecture?

The kernel layer abstracts platform differences between web and desktop environments, providing unified APIs for OS detection, link handling, notifications, and state persistence. By isolating platform-specific code in files like platform.tsx and local-provider.tsx, the architecture ensures that domain components remain platform-agnostic and reusable across deployment targets.

How do domain components access platform services in OpenWork?

Domain components import hooks from the kernel layer using path aliases such as import { usePlatform } from "@/react-app/kernel/platform". These hooks provide access to platform capabilities without requiring domains to import platform-specific APIs directly, maintaining strict architectural boundaries between feature code and infrastructure.

What role does the shell play in the OpenWork React application?

The shell acts as the composition layer that assembles kernel providers, configures routing, and renders application chrome including menus, command palettes, and notification centers. Files like app-root.tsx and providers.tsx establish the React context hierarchy that makes kernel services available to all domain components through React's provider pattern.

How does OpenWork handle state synchronization across multiple windows?

The kernel's global-sync-provider.tsx coordinates state across multiple renderer processes or browser windows by leveraging the storage abstractions defined in the kernel layer. This ensures that UI state such as open workspaces remains consistent regardless of how many application instances are running, whether in Electron or web contexts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}