# stablyai/orca architecture

> Architecture diagram of the GitHub repository stablyai/orca, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stablyai/orca
- Repository: https://github.com/stablyai/orca
- Video tour (about a minute): https://gitdiagram.com/stablyai/orca/video

## Overview

Orca is a cross-platform AI coding workspace: users run coding agents in chat or terminals, split work across isolated worktrees, and review the resulting changes. The README also describes remote execution, GitHub and Linear integrations, browser design tools, mobile follow-up, and plugins. The graph preserves those product branches, but the sampled source is sparse for most of them; edges are therefore limited to README-documented relationships rather than inferred implementation calls.

Main entry points: [`src/cli/orchestration/orchestration-handlers.ts`](https://github.com/stablyai/orca/blob/main/src/cli/orchestration/orchestration-handlers.ts) (Agent Orchestration), [`src/renderer/src/components/editor/rich-markdown/review/useRichMarkdownReviewController.ts`](https://github.com/stablyai/orca/blob/main/src/renderer/src/components/editor/rich-markdown/review/useRichMarkdownReviewController.ts) (Diff Review), [`mobile/src/source-control/review/use-mobile-diff-review-controller.ts`](https://github.com/stablyai/orca/blob/main/mobile/src/source-control/review/use-mobile-diff-review-controller.ts) (Mobile Companion), [`src/preload/index.ts`](https://github.com/stablyai/orca/blob/main/src/preload/index.ts) (Orca App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent_work["Agent Work"]
  node_chat_terminal["Chat or Terminal<br/>[dispatch.ts]"]
  node_orchestration["Agent Orchestration"]
  node_workers["Worker Sessions"]
end

subgraph group_review_git["Review and Git"]
  node_diff_review["Diff Review"]
  node_review_notes["Review Notes"]
  node_github["GitHub Tasks"]
  node_gitlab["GitLab Reviews"]
  node_repo_queries["Repository Queries"]
end

subgraph group_execution["Execution Environments"]
  node_worktrees["Parallel Worktrees"]
  node_remote["Remote Execution<br/>[execution-host.ts]"]
end

subgraph group_companion["Companion Features"]
  node_mobile["Mobile Companion"]
  node_push["Push Notifications<br/>[push-server.ts]"]
  node_browser["Browser Design Mode"]
end

subgraph group_platform["App Platform"]
  node_orca["Orca App<br/>[index.ts]"]
  node_plugins["Community Plugins"]
  node_cli["Orca CLI<br/>[client.ts]"]
  node_session_search["Session Search"]
end

node_user(("Builder"))

node_user -->|"uses"| node_orca
node_orca -->|"runs agents"| node_chat_terminal
node_user -->|"assigns task"| node_orchestration
node_orchestration -->|"starts workers"| node_workers
node_orchestration -->|"isolates work"| node_worktrees
node_user -->|"chooses host"| node_remote
node_user -->|"reviews changes"| node_diff_review
node_diff_review -->|"records notes"| node_review_notes
node_user -->|"views tasks"| node_github
node_user -.->|"reviews changes"| node_gitlab
node_user -->|"follows up"| node_mobile
node_mobile -->|"receives alerts"| node_push
node_user -->|"inspects elements"| node_browser
node_user -->|"installs extensions"| node_plugins
node_user -->|"runs commands"| node_cli
node_user -.->|"searches sessions"| node_session_search
node_user -.->|"queries refs"| node_repo_queries

click node_orca "https://github.com/stablyai/orca/blob/main/src/preload/index.ts"
click node_chat_terminal "https://github.com/stablyai/orca/blob/main/src/cli/dispatch/dispatch.ts"
click node_orchestration "https://github.com/stablyai/orca/blob/main/src/cli/orchestration/orchestration-handlers.ts"
click node_workers "https://github.com/stablyai/orca/blob/main/src/cli/orchestration/workers/orchestration-worker-settlement.ts"
click node_worktrees "https://github.com/stablyai/orca/blob/main/src/main/workspaces/execution-host/project-runtime-git-options.ts"
click node_remote "https://github.com/stablyai/orca/blob/main/src/shared/execution-host/execution-host.ts"
click node_diff_review "https://github.com/stablyai/orca/blob/main/src/renderer/src/components/editor/rich-markdown/review/useRichMarkdownReviewController.ts"
click node_review_notes "https://github.com/stablyai/orca/blob/main/src/shared/file-review/diff-comment-types.ts"
click node_github "https://github.com/stablyai/orca/blob/main/src/main/runtime/integrations/github/runtime-github-repository-query-commands.ts"
click node_gitlab "https://github.com/stablyai/orca/blob/main/src/main/ipc/source-control/gitlab-merge-request-query-handlers.ts"
click node_mobile "https://github.com/stablyai/orca/blob/main/mobile/src/source-control/review/use-mobile-diff-review-controller.ts"
click node_push "https://github.com/stablyai/orca/blob/main/cloud/apps/push/src/push-server.ts"
click node_plugins "https://github.com/stablyai/orca/blob/main/src/shared/plugins/manifest/plugin-engine-floor.ts"
click node_cli "https://github.com/stablyai/orca/blob/main/src/cli/runtime/client.ts"
click node_session_search "https://github.com/stablyai/orca/blob/main/src/main/ai-vault-search/query/session-search-engine.ts"
click node_repo_queries "https://github.com/stablyai/orca/blob/main/src/main/ipc/repos/base-ref-query-handlers.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_chat_terminal,node_orchestration,node_workers toneBlue
class node_diff_review,node_review_notes,node_github,node_gitlab,node_repo_queries toneAmber
class node_worktrees,node_remote toneMint
class node_mobile,node_push,node_browser toneRose
class node_orca,node_plugins,node_cli,node_session_search,node_user toneIndigo
```

## Components

### Agent Work

- [Chat or Terminal](https://github.com/stablyai/orca/blob/main/src/cli/dispatch/dispatch.ts): `src/cli/dispatch/dispatch.ts`
- [Agent Orchestration](https://github.com/stablyai/orca/blob/main/src/cli/orchestration/orchestration-handlers.ts): `src/cli/orchestration/orchestration-handlers.ts`
- [Worker Sessions](https://github.com/stablyai/orca/blob/main/src/cli/orchestration/workers/orchestration-worker-settlement.ts): `src/cli/orchestration/workers/orchestration-worker-settlement.ts`

### Review and Git

- [Diff Review](https://github.com/stablyai/orca/blob/main/src/renderer/src/components/editor/rich-markdown/review/useRichMarkdownReviewController.ts): `src/renderer/src/components/editor/rich-markdown/review/useRichMarkdownReviewController.ts`
- [Review Notes](https://github.com/stablyai/orca/blob/main/src/shared/file-review/diff-comment-types.ts): `src/shared/file-review/diff-comment-types.ts`
- [GitHub Tasks](https://github.com/stablyai/orca/blob/main/src/main/runtime/integrations/github/runtime-github-repository-query-commands.ts): `src/main/runtime/integrations/github/runtime-github-repository-query-commands.ts`
- [GitLab Reviews](https://github.com/stablyai/orca/blob/main/src/main/ipc/source-control/gitlab-merge-request-query-handlers.ts): `src/main/ipc/source-control/gitlab-merge-request-query-handlers.ts`
- [Repository Queries](https://github.com/stablyai/orca/blob/main/src/main/ipc/repos/base-ref-query-handlers.ts): `src/main/ipc/repos/base-ref-query-handlers.ts`

### Execution Environments

- [Parallel Worktrees](https://github.com/stablyai/orca/blob/main/src/main/workspaces/execution-host/project-runtime-git-options.ts): `src/main/workspaces/execution-host/project-runtime-git-options.ts`
- [Remote Execution](https://github.com/stablyai/orca/blob/main/src/shared/execution-host/execution-host.ts): `src/shared/execution-host/execution-host.ts`

### Companion Features

- [Mobile Companion](https://github.com/stablyai/orca/blob/main/mobile/src/source-control/review/use-mobile-diff-review-controller.ts): `mobile/src/source-control/review/use-mobile-diff-review-controller.ts`
- [Push Notifications](https://github.com/stablyai/orca/blob/main/cloud/apps/push/src/push-server.ts): `cloud/apps/push/src/push-server.ts`
- **Browser Design Mode**

### App Platform

- [Orca App](https://github.com/stablyai/orca/blob/main/src/preload/index.ts): `src/preload/index.ts`
- [Community Plugins](https://github.com/stablyai/orca/blob/main/src/shared/plugins/manifest/plugin-engine-floor.ts): `src/shared/plugins/manifest/plugin-engine-floor.ts`
- [Orca CLI](https://github.com/stablyai/orca/blob/main/src/cli/runtime/client.ts): `src/cli/runtime/client.ts`
- [Session Search](https://github.com/stablyai/orca/blob/main/src/main/ai-vault-search/query/session-search-engine.ts): `src/main/ai-vault-search/query/session-search-engine.ts`

### Other components

- **Builder**

## Connections

- Builder → Orca App: uses
- Orca App → Chat or Terminal: runs agents
- Builder → Agent Orchestration: assigns task
- Agent Orchestration → Worker Sessions: starts workers
- Agent Orchestration → Parallel Worktrees: isolates work
- Builder → Remote Execution: chooses host
- Builder → Diff Review: reviews changes
- Diff Review → Review Notes: records notes (evidence: `src/renderer/src/components/editor/rich-markdown/review/useRichMarkdownReviewController.ts`)
- Builder → GitHub Tasks: views tasks
- Builder → GitLab Reviews: reviews changes
- Builder → Mobile Companion: follows up
- Mobile Companion → Push Notifications: receives alerts
- Builder → Browser Design Mode: inspects elements
- Builder → Community Plugins: installs extensions
- Builder → Orca CLI: runs commands
- Builder → Session Search: searches sessions
- Builder → Repository Queries: queries refs
