# sant0x00/orca architecture

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

- Interactive diagram: https://gitdiagram.com/sant0x00/orca
- Repository: https://github.com/sant0x00/orca

## Overview

Orca is a cross-platform AI coding-agent workspace: users start agents in chat or terminals, isolate parallel work in worktrees, and review and hand feedback back to agents. The README also describes orchestration, remote execution, mobile notifications and replies, Git integrations, browser design mode, task integrations, CLI, and plugins. The graph preserves those product branches, while sampled source supports a few internal review and query details. Most subsystems are represented at their existing source directories because their implementations were not sampled; documented links use the README as evidence.

Main entry points: [`src/cli/handlers`](https://github.com/sant0x00/orca/tree/main/src/cli/handlers) (Agent orchestration), [`mobile`](https://github.com/sant0x00/orca/tree/main/mobile) (Mobile companion), [`src/main/native-chat`](https://github.com/sant0x00/orca/tree/main/src/main/native-chat) (Chat and terminal), [`src/renderer/src/components/editor/rich-markdown/review/useRichMarkdownReviewController.ts`](https://github.com/sant0x00/orca/blob/main/src/renderer/src/components/editor/rich-markdown/review/useRichMarkdownReviewController.ts) (Diff review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_desktop["Desktop app"]
  node_chat_terminal["Chat and terminal"]
  node_diff_review["Diff review"]
  node_mobile_app["Mobile companion"]
  node_session_search["Session search"]
  node_markdown_rail["Review rail"]
  node_mobile_review["Mobile diff review"]
end

subgraph group_agent_work["Agent work"]
  node_orchestration["Agent orchestration"]
  node_worktrees["Parallel worktrees"]
  node_agent_runtime["Agent runtime"]
  node_cli["Orca CLI"]
end

subgraph group_platform["Execution platform"]
  node_remote_server["Remote Orca Server"]
  node_relay_edge["Relay edge"]
  node_fence_broker["Fence broker"]
  node_push_service["Push service"]
end

subgraph group_services["Integrations"]
  node_git_review["Git and PRs"]
  node_task_integrations["GitHub and Linear tasks"]
  node_browser_design["Browser design mode"]
  node_plugins["Plugin system"]
end

node_user(("Builder"))

node_user -->|"uses"| node_desktop
node_desktop -->|"starts agents"| node_chat_terminal
node_chat_terminal -->|"runs agents"| node_agent_runtime
node_user -->|"delegates tasks"| node_orchestration
node_orchestration -->|"starts workers"| node_worktrees
node_orchestration -->|"dispatches work"| node_agent_runtime
node_user -->|"creates workspaces"| node_worktrees
node_user -->|"reviews changes"| node_diff_review
node_diff_review -->|"delegates rail"| node_markdown_rail
node_user -->|"uses remotely"| node_mobile_app
node_mobile_app -->|"reviews diffs"| node_mobile_review
node_mobile_app -->|"receives alerts"| node_push_service
node_user -->|"pairs remotely"| node_remote_server
node_remote_server -.->|"uses relay"| node_relay_edge
node_relay_edge -.->|"coordinates fences"| node_fence_broker
node_user -->|"runs commands"| node_cli
node_cli -->|"starts workers"| node_orchestration
node_user -->|"reviews PRs"| node_git_review
node_user -->|"starts from tasks"| node_task_integrations
node_user -->|"selects elements"| node_browser_design
node_browser_design -->|"sends context"| node_chat_terminal
node_user -->|"installs plugins"| node_plugins
node_user -.->|"searches sessions"| node_session_search
node_markdown_rail -->|"positions notes"| node_diff_review

click node_desktop "https://github.com/sant0x00/orca/tree/main/src/renderer/src"
click node_chat_terminal "https://github.com/sant0x00/orca/tree/main/src/main/native-chat"
click node_diff_review "https://github.com/sant0x00/orca/blob/main/src/renderer/src/components/editor/rich-markdown/review/useRichMarkdownReviewController.ts"
click node_mobile_app "https://github.com/sant0x00/orca/tree/main/mobile"
click node_session_search "https://github.com/sant0x00/orca/blob/main/src/main/ai-vault-search/query/session-search-engine.ts"
click node_orchestration "https://github.com/sant0x00/orca/tree/main/src/cli/handlers"
click node_worktrees "https://github.com/sant0x00/orca/tree/main/src/main/workspaces"
click node_agent_runtime "https://github.com/sant0x00/orca/tree/main/src/main/runtime"
click node_cli "https://github.com/sant0x00/orca/tree/main/src/cli"
click node_remote_server "https://github.com/sant0x00/orca/tree/main/cloud/apps/relay"
click node_relay_edge "https://github.com/sant0x00/orca/tree/main/cloud/apps/relay-edge"
click node_fence_broker "https://github.com/sant0x00/orca/tree/main/cloud/apps/relay-fence-broker"
click node_push_service "https://github.com/sant0x00/orca/tree/main/cloud/apps/push"
click node_git_review "https://github.com/sant0x00/orca/blob/main/src/main/runtime/integrations/github/runtime-github-repository-query-commands.ts"
click node_task_integrations "https://github.com/sant0x00/orca/tree/main/src/main/runtime/integrations"
click node_browser_design "https://github.com/sant0x00/orca/tree/main/src/renderer/src/components/browser-pane"
click node_plugins "https://github.com/sant0x00/orca/tree/main/src/shared/plugins"
click node_markdown_rail "https://github.com/sant0x00/orca/blob/main/src/renderer/src/components/editor/rich-markdown/review/useRichMarkdownReviewRailController.ts"
click node_mobile_review "https://github.com/sant0x00/orca/blob/main/mobile/src/source-control/review/use-mobile-diff-review-controller.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_desktop,node_chat_terminal,node_diff_review,node_mobile_app,node_session_search,node_markdown_rail,node_mobile_review toneBlue
class node_orchestration,node_worktrees,node_agent_runtime,node_cli toneAmber
class node_remote_server,node_relay_edge,node_fence_broker,node_push_service toneMint
class node_git_review,node_task_integrations,node_browser_design,node_plugins toneRose
class node_user toneIndigo
```

## Components

### User experience

- [Desktop app](https://github.com/sant0x00/orca/tree/main/src/renderer/src): `src/renderer/src`
- [Chat and terminal](https://github.com/sant0x00/orca/tree/main/src/main/native-chat): `src/main/native-chat`
- [Diff review](https://github.com/sant0x00/orca/blob/main/src/renderer/src/components/editor/rich-markdown/review/useRichMarkdownReviewController.ts): `src/renderer/src/components/editor/rich-markdown/review/useRichMarkdownReviewController.ts`
- [Mobile companion](https://github.com/sant0x00/orca/tree/main/mobile): `mobile`
- [Session search](https://github.com/sant0x00/orca/blob/main/src/main/ai-vault-search/query/session-search-engine.ts): `src/main/ai-vault-search/query/session-search-engine.ts`
- [Review rail](https://github.com/sant0x00/orca/blob/main/src/renderer/src/components/editor/rich-markdown/review/useRichMarkdownReviewRailController.ts): `src/renderer/src/components/editor/rich-markdown/review/useRichMarkdownReviewRailController.ts`
- [Mobile diff review](https://github.com/sant0x00/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`

### Agent work

- [Agent orchestration](https://github.com/sant0x00/orca/tree/main/src/cli/handlers): `src/cli/handlers`
- [Parallel worktrees](https://github.com/sant0x00/orca/tree/main/src/main/workspaces): `src/main/workspaces`
- [Agent runtime](https://github.com/sant0x00/orca/tree/main/src/main/runtime): `src/main/runtime`
- [Orca CLI](https://github.com/sant0x00/orca/tree/main/src/cli): `src/cli`

### Execution platform

- [Remote Orca Server](https://github.com/sant0x00/orca/tree/main/cloud/apps/relay): `cloud/apps/relay`
- [Relay edge](https://github.com/sant0x00/orca/tree/main/cloud/apps/relay-edge): `cloud/apps/relay-edge`
- [Fence broker](https://github.com/sant0x00/orca/tree/main/cloud/apps/relay-fence-broker): `cloud/apps/relay-fence-broker`
- [Push service](https://github.com/sant0x00/orca/tree/main/cloud/apps/push): `cloud/apps/push`

### Integrations

- [Git and PRs](https://github.com/sant0x00/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`
- [GitHub and Linear tasks](https://github.com/sant0x00/orca/tree/main/src/main/runtime/integrations): `src/main/runtime/integrations`
- [Browser design mode](https://github.com/sant0x00/orca/tree/main/src/renderer/src/components/browser-pane): `src/renderer/src/components/browser-pane`
- [Plugin system](https://github.com/sant0x00/orca/tree/main/src/shared/plugins): `src/shared/plugins`

### Other components

- **Builder**

## Connections

- Builder → Desktop app: uses
- Desktop app → Chat and terminal: starts agents
- Chat and terminal → Agent runtime: runs agents
- Builder → Agent orchestration: delegates tasks
- Agent orchestration → Parallel worktrees: starts workers
- Agent orchestration → Agent runtime: dispatches work
- Builder → Parallel worktrees: creates workspaces
- Builder → Diff review: reviews changes
- Diff review → Review rail: delegates rail (evidence: `src/renderer/src/components/editor/rich-markdown/review/useRichMarkdownReviewController.ts`)
- Builder → Mobile companion: uses remotely
- Mobile companion → Mobile diff review: reviews diffs (evidence: `mobile/src/source-control/review/use-mobile-diff-review-controller.ts`)
- Mobile companion → Push service: receives alerts
- Builder → Remote Orca Server: pairs remotely
- Remote Orca Server → Relay edge: uses relay
- Relay edge → Fence broker: coordinates fences
- Builder → Orca CLI: runs commands
- Orca CLI → Agent orchestration: starts workers (evidence: `src/cli/handlers/orchestration-handler-test-context.ts`)
- Builder → Git and PRs: reviews PRs
- Builder → GitHub and Linear tasks: starts from tasks
- Builder → Browser design mode: selects elements
- Browser design mode → Chat and terminal: sends context
- Builder → Plugin system: installs plugins
- Builder → Session search: searches sessions
- Review rail → Diff review: positions notes (evidence: `src/renderer/src/components/editor/rich-markdown/review/useRichMarkdownReviewRailController.ts`)