# Core Modules in Orca: Architecture and Source Code Guide

> Explore the core modules of Orca: Relay, Renderer, Shared, Types, CLI Automation, and Resources. Understand their architecture and source code for a robust backend and UI separation.

- Repository: [Stably/orca](https://github.com/stablyai/orca)
- Tags: architecture
- Published: 2026-05-25

---

**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`](https://github.com/stablyai/orca/blob/main/src/relay/relay.ts), which initializes the Relay server and exposes RPC endpoints defined in [`src/relay/protocol.ts`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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:

```typescript
// 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:

```typescript
// 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:

```typescript
// 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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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.