# kesteva/cyboflow architecture

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

- Interactive diagram: https://gitdiagram.com/kesteva/cyboflow
- Repository: https://github.com/kesteva/cyboflow

## Overview

#### Purpose and entry points
Cyboflow is a self-contained macOS Electron desktop application for orchestrating multi-agent software workflows over local Git repositories. It supports built-in Planner, Sprint, Compound, Ship, verification setup, custom workflows, and ad-hoc sessions. Electron starts in `main/src/index.ts`; the privileged bridge is `main/src/preload.ts`; the React renderer starts at `frontend/src/main.tsx` and renders from `frontend/src/App.tsx`.

#### Desktop boundary and API surface
The renderer does not directly own filesystem, processes, Git, or persistence. It calls typed APIs through Electron IPC and tRPC: IPC registration/handlers live in `main/src/ipc/index.ts` and `main/src/ipc/cyboflow.ts`; the orchestrator-facing RPC router is `main/src/orchestrator/trpc/router.ts`, with renderer client wiring in `frontend/src/trpc/client.ts`. This is the primary trust boundary between UI and local-machine capabilities.

#### Workflow orchestration
`main/src/orchestrator/Orchestrator.ts` is the central application coordinator. It launches, resumes, pauses, retries, rewinds, cancels, and recovers runs; `main/src/orchestrator/runLauncher.ts` and `main/src/orchestrator/runExecutor.ts` drive execution. Workflow definitions, built-in bundles, agents, and prompt rendering are represented by `main/src/orchestrator/workflowRegistry.ts`, `main/src/orchestrator/workflows/workflowBundle.ts`, and `main/src/orchestrator/workflowPromptRenderer.ts`. Runs can use programmatic DAG-like control and human/visual gates via `main/src/orchestrator/programmatic/workflowController.ts`.

#### Agent execution substrates and event ingestion
Each isolated session can run Claude Code through SDK/chat or interactive PTY paths. Substrate selection/dispatch is handled by `main/src/services/substrateDispatchFacade.ts`; Claude process management is in `main/src/services/panels/claude/claudeCodeManager.ts`; Codex SDK/PTY support exists in `main/src/services/panels/codex/codexSdkManager.ts` and `main/src/services/panels/codex/codexPtyManager.ts`. Provider stream events are normalized, persisted/projected, and routed to orchestration/UI through `main/src/services/streamParser/eventRouter.ts`, `main/src/services/streamParser/messageProjection.ts`, and `main/src/orchestrator/runEventBridge.ts`.

#### State, isolation, and local infrastructure
SQLite is the durable system of record, with schema/migration evolution in `main/src/database/database.ts`, `main/src/database/schema.sql`, and `main/src/database/migrations/`. It stores projects, sessions, runs, workflow steps, tasks, review items, artifacts, usage, experiments, and integrations. Git worktrees isolate parallel work through `main/src/services/worktreeManager.ts`; Git status/diffs are managed by `main/src/services/gitStatusManager.ts` and `main/src/services/gitDiffManager.ts`. Terminal/PTY lifecycle is managed in `main/src/services/terminalSessionManager.ts`.

#### Human control, review, and verification
Agent permissions, questions, approvals, and review items are first-class workflow gates. Core routing/bridges reside in `main/src/orchestrator/approvalRouter.ts`, `main/src/orchestrator/questionRouter.ts`, and `main/src/orchestrator/reviewItemRouter.ts`. The renderer’s central operational surfaces include `frontend/src/components/ReviewQueueView.tsx` and `frontend/src/components/cyboflow/RunView.tsx`. Verification is a separate scheduling pipeline with runbook, snapshot, dependency, agent, and verdict stages in `main/src/orchestrator/verify/verificationScheduler.ts`, `main/src/orchestrator/verify/runbookStore.ts`, and `main/src/orchestrator/verify/verdictDelivery.ts`.

#### Renderer composition and integrations
The React UI is state-store driven; workflow/run/session state centers on `frontend/src/stores/cyboflowStore.ts`, `frontend/src/stores/sessionStore.ts`, and `frontend/src/stores/workflowsStore.ts`. The Cyboflow workspace root and workflow editor are `frontend/src/components/cyboflow/CyboflowRoot.tsx` and `frontend/src/components/cyboflow/WorkflowEditorModal.tsx`; task planning is surfaced through `frontend/src/components/BacklogPane.tsx`. External/local integrations include Claude Code, Codex runtimes, MCP via `main/src/orchestrator/mcpServer/cyboflowMcpServer.ts`, Linear and Plane tracker sync via `main/src/services/trackerSync/trackerSyncService.ts`, visual verification using Playwright/Peekaboo adapters, and Electron auto-updates via `main/src/services/appUpdater.ts`.

Main entry points: [`main/src/orchestrator/Orchestrator.ts`](https://github.com/kesteva/cyboflow/blob/main/main/src/orchestrator/Orchestrator.ts) (Orchestrator), [`main/src/orchestrator/runExecutor.ts`](https://github.com/kesteva/cyboflow/blob/main/main/src/orchestrator/runExecutor.ts) (Run launcher & executor), [`main/src/services/streamParser/eventRouter.ts`](https://github.com/kesteva/cyboflow/blob/main/main/src/services/streamParser/eventRouter.ts) (Event ingestion & bridge), [`frontend/src/App.tsx`](https://github.com/kesteva/cyboflow/blob/main/frontend/src/App.tsx) (React application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_renderer["React renderer"]
  node_renderer_app["React application<br/>renderer entry<br/>[App.tsx]"]
  node_trpc_client["tRPC client<br/>[client.ts]"]
  node_ui_stores["Workflow/run stores<br/>renderer state<br/>[cyboflowStore.ts]"]
  node_workspace["Cyboflow workspace<br/>operational UI<br/>[CyboflowRoot.tsx]"]
  node_review_ui["Review queue &amp; run view<br/>human control UI"]
end

subgraph group_boundary["Electron boundary"]
  node_electron_main["Electron main<br/>desktop entry<br/>[index.ts]"]
  node_preload["Preload bridge<br/>privileged bridge<br/>[preload.ts]"]
  node_ipc["IPC handlers<br/>local capability API<br/>[index.ts]"]
  node_trpc_router["Orchestrator RPC router<br/>typed RPC API<br/>[router.ts]"]
end

subgraph group_orchestration["Workflow orchestration"]
  node_orchestrator{{"Orchestrator<br/>run coordinator<br/>[Orchestrator.ts]"}}
  node_run_execution["Run launcher &amp; executor<br/>execution engine<br/>[runExecutor.ts]"]
  node_workflow_registry["Workflow registry<br/>definitions &amp; prompts"]
  node_workflow_controller["Workflow controller<br/>DAG &amp; visual gates"]
  node_human_gates["Approval, question &amp; review routers<br/>human gate routing<br/>[approvalRouter.ts]"]
  node_verification["Verification pipeline<br/>verification scheduler"]
end

subgraph group_execution["Local execution"]
  node_substrate_dispatch["Substrate dispatch<br/>agent runtime selector"]
  node_agent_runtimes["Claude &amp; Codex runtimes<br/>SDK and PTY execution"]
  node_event_pipeline["Event ingestion &amp; bridge<br/>stream normalization<br/>[eventRouter.ts]"]
  node_git_isolation["Git worktree isolation<br/>local Git workspace<br/>[worktreeManager.ts]"]
end

subgraph group_state["Durable state &amp; integrations"]
  node_database[("SQLite system of record<br/>durable persistence<br/>[database.ts]")]
  node_integrations["MCP, trackers &amp; updates<br/>external integrations"]
end

node_electron_main -->|"loads"| node_preload
node_electron_main -->|"registers"| node_ipc
node_preload -->|"exposes APIs to"| node_renderer_app
node_renderer_app -->|"renders"| node_workspace
node_workspace -->|"reads and updates"| node_ui_stores
node_review_ui -->|"resolves gates via"| node_human_gates
node_renderer_app -->|"uses"| node_trpc_client
node_trpc_client -->|"typed RPC"| node_trpc_router
node_ipc -->|"local commands"| node_orchestrator
node_trpc_router -->|"orchestration calls"| node_orchestrator
node_orchestrator -->|"drives"| node_run_execution
node_orchestrator -->|"loads workflows"| node_workflow_registry
node_run_execution -->|"executes control flow"| node_workflow_controller
node_workflow_controller -->|"creates gates"| node_human_gates
node_run_execution -->|"dispatches agents"| node_substrate_dispatch
node_run_execution -->|"uses isolated worktrees"| node_git_isolation
node_substrate_dispatch -->|"selects runtime"| node_agent_runtimes
node_agent_runtimes -->|"streams events"| node_event_pipeline
node_event_pipeline -->|"run events"| node_orchestrator
node_event_pipeline -->|"projects updates"| node_ui_stores
node_orchestrator -->|"schedules verification"| node_verification
node_orchestrator -->|"persists runs"| node_database
node_event_pipeline -->|"persists events"| node_database
node_verification -->|"stores verdicts"| node_database
node_orchestrator -->|"uses"| node_integrations

click node_electron_main "https://github.com/kesteva/cyboflow/blob/main/main/src/index.ts"
click node_preload "https://github.com/kesteva/cyboflow/blob/main/main/src/preload.ts"
click node_ipc "https://github.com/kesteva/cyboflow/blob/main/main/src/ipc/index.ts"
click node_renderer_app "https://github.com/kesteva/cyboflow/blob/main/frontend/src/App.tsx"
click node_trpc_client "https://github.com/kesteva/cyboflow/blob/main/frontend/src/trpc/client.ts"
click node_ui_stores "https://github.com/kesteva/cyboflow/blob/main/frontend/src/stores/cyboflowStore.ts"
click node_workspace "https://github.com/kesteva/cyboflow/blob/main/frontend/src/components/cyboflow/CyboflowRoot.tsx"
click node_review_ui "https://github.com/kesteva/cyboflow/blob/main/frontend/src/components/ReviewQueueView.tsx"
click node_trpc_router "https://github.com/kesteva/cyboflow/blob/main/main/src/orchestrator/trpc/router.ts"
click node_orchestrator "https://github.com/kesteva/cyboflow/blob/main/main/src/orchestrator/Orchestrator.ts"
click node_run_execution "https://github.com/kesteva/cyboflow/blob/main/main/src/orchestrator/runExecutor.ts"
click node_workflow_registry "https://github.com/kesteva/cyboflow/blob/main/main/src/orchestrator/workflowRegistry.ts"
click node_workflow_controller "https://github.com/kesteva/cyboflow/blob/main/main/src/orchestrator/programmatic/workflowController.ts"
click node_human_gates "https://github.com/kesteva/cyboflow/blob/main/main/src/orchestrator/approvalRouter.ts"
click node_verification "https://github.com/kesteva/cyboflow/blob/main/main/src/orchestrator/verify/verificationScheduler.ts"
click node_substrate_dispatch "https://github.com/kesteva/cyboflow/blob/main/main/src/services/substrateDispatchFacade.ts"
click node_agent_runtimes "https://github.com/kesteva/cyboflow/blob/main/main/src/services/panels/claude/claudeCodeManager.ts"
click node_event_pipeline "https://github.com/kesteva/cyboflow/blob/main/main/src/services/streamParser/eventRouter.ts"
click node_git_isolation "https://github.com/kesteva/cyboflow/blob/main/main/src/services/worktreeManager.ts"
click node_database "https://github.com/kesteva/cyboflow/blob/main/main/src/database/database.ts"
click node_integrations "https://github.com/kesteva/cyboflow/blob/main/main/src/orchestrator/mcpServer/cyboflowMcpServer.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_renderer_app,node_trpc_client,node_ui_stores,node_workspace,node_review_ui toneBlue
class node_electron_main,node_preload,node_ipc,node_trpc_router toneAmber
class node_orchestrator,node_run_execution,node_workflow_registry,node_workflow_controller,node_human_gates,node_verification toneMint
class node_substrate_dispatch,node_agent_runtimes,node_event_pipeline,node_git_isolation toneRose
class node_database,node_integrations toneIndigo
```

## Components

### React renderer

Operational UI and state stores.

- [React application](https://github.com/kesteva/cyboflow/blob/main/frontend/src/App.tsx): renderer entry · `frontend/src/App.tsx`
- [tRPC client](https://github.com/kesteva/cyboflow/blob/main/frontend/src/trpc/client.ts): RPC client · `frontend/src/trpc/client.ts`
- [Workflow/run stores](https://github.com/kesteva/cyboflow/blob/main/frontend/src/stores/cyboflowStore.ts): renderer state · `frontend/src/stores/cyboflowStore.ts`
- [Cyboflow workspace](https://github.com/kesteva/cyboflow/blob/main/frontend/src/components/cyboflow/CyboflowRoot.tsx): operational UI · `frontend/src/components/cyboflow/CyboflowRoot.tsx`
- [Review queue & run view](https://github.com/kesteva/cyboflow/blob/main/frontend/src/components/ReviewQueueView.tsx): human control UI · `frontend/src/components/ReviewQueueView.tsx`

### Electron boundary

Typed privileged API boundary.

- [Electron main](https://github.com/kesteva/cyboflow/blob/main/main/src/index.ts): desktop entry · `main/src/index.ts`
- [Preload bridge](https://github.com/kesteva/cyboflow/blob/main/main/src/preload.ts): privileged bridge · `main/src/preload.ts`
- [IPC handlers](https://github.com/kesteva/cyboflow/blob/main/main/src/ipc/index.ts): local capability API · `main/src/ipc/index.ts`
- [Orchestrator RPC router](https://github.com/kesteva/cyboflow/blob/main/main/src/orchestrator/trpc/router.ts): typed RPC API · `main/src/orchestrator/trpc/router.ts`

### Workflow orchestration

Run coordination, definitions, and human gates.

- [Orchestrator](https://github.com/kesteva/cyboflow/blob/main/main/src/orchestrator/Orchestrator.ts): run coordinator · Launches, resumes, controls, and recovers workflow runs. · `main/src/orchestrator/Orchestrator.ts`
- [Run launcher & executor](https://github.com/kesteva/cyboflow/blob/main/main/src/orchestrator/runExecutor.ts): execution engine · `main/src/orchestrator/runExecutor.ts`
- [Workflow registry](https://github.com/kesteva/cyboflow/blob/main/main/src/orchestrator/workflowRegistry.ts): definitions & prompts · `main/src/orchestrator/workflowRegistry.ts`
- [Workflow controller](https://github.com/kesteva/cyboflow/blob/main/main/src/orchestrator/programmatic/workflowController.ts): DAG & visual gates · `main/src/orchestrator/programmatic/workflowController.ts`
- [Approval, question & review routers](https://github.com/kesteva/cyboflow/blob/main/main/src/orchestrator/approvalRouter.ts): human gate routing · `main/src/orchestrator/approvalRouter.ts`
- [Verification pipeline](https://github.com/kesteva/cyboflow/blob/main/main/src/orchestrator/verify/verificationScheduler.ts): verification scheduler · Schedules runbook, snapshot, dependency, agent, and verdict stages. · `main/src/orchestrator/verify/verificationScheduler.ts`

### Local execution

Agent runtimes, Git isolation, and event processing.

- [Substrate dispatch](https://github.com/kesteva/cyboflow/blob/main/main/src/services/substrateDispatchFacade.ts): agent runtime selector · `main/src/services/substrateDispatchFacade.ts`
- [Claude & Codex runtimes](https://github.com/kesteva/cyboflow/blob/main/main/src/services/panels/claude/claudeCodeManager.ts): SDK and PTY execution · `main/src/services/panels/claude/claudeCodeManager.ts`
- [Event ingestion & bridge](https://github.com/kesteva/cyboflow/blob/main/main/src/services/streamParser/eventRouter.ts): stream normalization · Projects provider events to durable state, orchestration, and UI. · `main/src/services/streamParser/eventRouter.ts`
- [Git worktree isolation](https://github.com/kesteva/cyboflow/blob/main/main/src/services/worktreeManager.ts): local Git workspace · `main/src/services/worktreeManager.ts`

### Durable state & integrations

SQLite record and external/local integrations.

- [SQLite system of record](https://github.com/kesteva/cyboflow/blob/main/main/src/database/database.ts): durable persistence · Stores projects, sessions, runs, steps, tasks, artifacts, and integrations. · `main/src/database/database.ts`
- [MCP, trackers & updates](https://github.com/kesteva/cyboflow/blob/main/main/src/orchestrator/mcpServer/cyboflowMcpServer.ts): external integrations · `main/src/orchestrator/mcpServer/cyboflowMcpServer.ts`

## Connections

- Electron main → Preload bridge: loads
- Electron main → IPC handlers: registers
- Preload bridge → React application: exposes APIs to
- React application → Cyboflow workspace: renders
- Cyboflow workspace → Workflow/run stores: reads and updates
- Review queue & run view → Approval, question & review routers: resolves gates via
- React application → tRPC client: uses
- tRPC client → Orchestrator RPC router: typed RPC
- IPC handlers → Orchestrator: local commands
- Orchestrator RPC router → Orchestrator: orchestration calls
- Orchestrator → Run launcher & executor: drives
- Orchestrator → Workflow registry: loads workflows
- Run launcher & executor → Workflow controller: executes control flow
- Workflow controller → Approval, question & review routers: creates gates
- Run launcher & executor → Substrate dispatch: dispatches agents
- Run launcher & executor → Git worktree isolation: uses isolated worktrees
- Substrate dispatch → Claude & Codex runtimes: selects runtime
- Claude & Codex runtimes → Event ingestion & bridge: streams events
- Event ingestion & bridge → Orchestrator: run events
- Event ingestion & bridge → Workflow/run stores: projects updates
- Orchestrator → Verification pipeline: schedules verification
- Orchestrator → SQLite system of record: persists runs
- Event ingestion & bridge → SQLite system of record: persists events
- Verification pipeline → SQLite system of record: stores verdicts
- Orchestrator → MCP, trackers & updates: uses