Core Modules in Orca: Architecture and Source Code Guide

Orca is built around six core modules—Relay, Renderer, Shared, Types, CLI/Automation, and Resources—that separate backend Electron processes from the React-based UI while sharing utilities through a common TypeScript library.

The stablyai/orca repository implements a cross-platform development environment using a modular architecture that ensures type safety and clean separation of concerns. Understanding these core modules in Orca is essential for navigating the codebase, contributing features, or extending the application for headless automation workflows. Each module serves a distinct purpose in the Electron-based application lifecycle, from managing the main process to rendering the workspace interface.

Relay Module: The Backend Engine

The Relay module runs inside the Electron main process and handles all backend concerns for the Orca application.

Located in src/relay/, this module manages file-system streaming, Git integration, subprocess and PTY (pseudo-terminal) management, and agent-hook communication. The core entry point is src/relay/relay.ts, which initializes the Relay server and exposes RPC endpoints defined in src/relay/protocol.ts.

This module acts as the authoritative backend, receiving commands from the renderer process and translating them into system-level operations across macOS, Linux, and Windows.

Renderer Module: The React-Based UI Layer

The Renderer module contains the user-facing interface built with React and Redux, running inside the Electron renderer process.

Found in src/renderer/, this module implements the workspace UI, terminal emulation panels, editor views, and settings interfaces. The application entry point is src/renderer/src/web/main.tsx, which bootstraps the React application and establishes communication with the Relay server.

State management is centralized through the Redux store defined under src/renderer/src/store/, ensuring that UI components remain synchronized with backend state managed by the Relay process.

Shared Module: Cross-Cutting Utilities

The Shared module provides pure TypeScript utilities consumed by both Relay and Renderer processes.

Located in src/shared/, this library includes data structures for worktrees, terminal ID management, text-search algorithms, telemetry helpers, and platform-agnostic utilities like WSL path conversion. Key files such as src/shared/workspace-name.ts demonstrate how both processes coordinate on workspace lifecycle events without duplicating logic.

Using shared utilities ensures that operations like path resolution and workspace serialization behave identically across the main and renderer processes.

Types Module: Centralized Type Definitions

The Types module serves as the single source of truth for compile-time contracts throughout the Orca codebase.

Located in src/types/, this module contains TypeScript definitions for build constants, configuration schemas, and the public API surface. The file src/types/build-constants.d.ts defines constants that both Relay and Renderer must agree on, preventing type mismatches between processes.

By centralizing these definitions, Orca maintains strict type safety across its module boundaries, ensuring that changes to data shapes propagate correctly through the entire application.

CLI and Automation Module

The CLI and Automation module enables programmatic control of Orca without launching the full graphical interface.

Primarily located in src/relay/ with supporting scripts in tools/, this module includes command-line entry points like src/relay/external-automations-handler.ts. These components allow Orca to be driven by external scripts, automated tests, and CI pipelines, invoking Relay APIs directly rather than through the React UI.

This architecture makes Orca suitable for headless workflows where editor functionality is needed without user interaction.

Resources Module: Platform-Specific Assets

The Resources module houses binary dependencies and platform-specific packaging assets required for distribution.

Located in resources/, this directory includes platform binaries such as resources/win32/bin/orca.cmd along with icons, manifests, and packaging scripts. These assets are bundled during the build process and provide the native functionality required by the Relay module's system integration features.

How the Core Modules Interact

The modules communicate through a well-defined architecture that maintains process isolation while enabling rich functionality:

1. Relay starts the Electron main process, creates the Relay server, and exposes RPC endpoints through src/relay/protocol.ts.

2. Renderer loads in a separate process, connects to the Relay server via the Redux store actions defined in src/renderer/src/store/slices/agent-status.ts.

3. Shared utilities serialize workspace data, manage terminal identifiers, and handle text searches used by both processes.

4. Types enforce compile-time contracts, ensuring that WorkspaceSessionSchema and other data structures remain consistent across the application boundary.

5. CLI and Automation scripts invoke Relay APIs directly, bypassing the Renderer to enable headless execution environments.

Working with Orca Modules: Code Examples

The following snippets demonstrate how to interact with the core modules in practice.

Initialize the Relay server in the main Electron process:

// In the main process – starting the Relay server
import { startRelay } from 'src/relay/relay';

startRelay();   // ↳ src/relay/relay.ts

Connect the Renderer to the backend through the Redux store:

// In the renderer – connecting to the Relay RPC layer
import { useDispatch } from 'react-redux';
import { connectToRelay } from 'src/renderer/src/store/slices/agent-status';

const dispatch = useDispatch();
dispatch(connectToRelay());   // ↳ src/renderer/src/store/slices/agent-status.ts

Convert WSL paths using shared utilities:

// Shared utility – converting a WSL UNC path to a Windows path
import { wslPathToWindows } from 'src/shared/wsl-paths';

const winPath = wslPathToWindows('//wsl$/Ubuntu/home/user/project');

Summary

• Relay (src/relay/) manages the Electron main process, handling Git, file systems, and PTY operations through an RPC protocol.
• Renderer (src/renderer/) implements the React/Redux UI layer that users interact with in the renderer process.
• Shared (src/relay/) provides TypeScript utilities for worktrees, search, and path handling used across all processes.
• Types (src/types/) centralizes TypeScript definitions to ensure type safety between Relay and Renderer.
• CLI/Automation (src/relay/ and tools/) enables headless operation for CI pipelines and scripting.
• Resources (resources/) contains platform-specific binaries and packaging assets required for distribution.

Frequently Asked Questions

What is the difference between the Relay and Renderer modules in Orca?

The Relay module runs in the Electron main process and handles backend operations like file system access, Git commands, and terminal management, while the Renderer module runs in a sandboxed browser process and handles the React-based user interface. They communicate via RPC protocols defined in src/relay/protocol.ts, with the Renderer dispatching Redux actions to trigger Relay operations.

Where are the TypeScript type definitions located in the Orca codebase?

Type definitions are centralized in the Types module under src/types/, with src/types/build-constants.d.ts serving as the primary location for build-time constants and configuration interfaces. This ensures that both the Relay and Renderer processes share identical compile-time contracts for data structures like WorkspaceSessionSchema.

Can Orca be used programmatically without launching the UI?

Yes, the CLI and Automation module supports headless operation through components like src/relay/external-automations-handler.ts, which allows external scripts to invoke Relay APIs directly without initializing the React renderer process. This makes Orca suitable for integration into CI/CD pipelines and automated testing environments.

How does Orca handle cross-platform path compatibility between modules?

The Shared module includes platform-agnostic helpers such as wslPathToWindows in src/shared/wsl-paths.ts that normalize file paths between Windows, macOS, and Linux environments. Both Relay and Renderer consume these utilities to ensure consistent path handling regardless of which operating system Orca runs on.

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