Orchestration crate layout

crates/orchestration/src is grouped by app concern. Entity folders hold application logic and port traits. Centralized adapters/ folders hold concrete storage, tool, MCP, git, and LSP implementations.

Rust import paths match the folder layout. For example, workflow/catalog.rs is orchestration::workflow::catalog, and run/execution/ is orchestration::run::execution.

Module paths

File or folder	Rust module
backend/mod.rs	orchestration::backend
workflow/catalog.rs	orchestration::workflow::catalog
run/coordinator/mod.rs	orchestration::run::coordinator
run/execution/	orchestration::run::execution
run/handoff.rs	orchestration::run::handoff
tool/registry.rs	orchestration::tool::registry
adapters/tool_impl/	orchestration::tools internal alias
adapters/infrastructure/git	orchestration::git public alias
adapters/infrastructure/lsp	orchestration::lsp public alias

Roles

desktop / ui
    │
    ▼
backend/                  AppBackend facade and composition root
    │
    ├── workflow/          workflow catalog and authoring services
    ├── chat.rs            saved direct-chat metadata
    ├── agent.rs           saved agent library
    ├── project/           project registry and file references
    ├── settings/          settings facade, provider readiness, skills
    ├── schedule/          schedule evaluation and status
    ├── run/               run registry, per-run coordinators, checkpoints, state projection
    ├── terminal.rs        embedded terminal sessions
    └── tool/              tool registry, dispatch, retry, output

adapters/
    ├── storage/           JSON and checkpoint persistence
    ├── tool_impl/         concrete read/search/write/bash/edit tools
    ├── mcp/               MCP discovery and run clients
    └── infrastructure/    git and LSP integrations

Role	Folder	Job
Composition	backend/	Construct services, expose the stable facade that desktop calls.
Application services	workflow/, agent.rs, project/, settings/, schedule/, run/, terminal.rs, tool/	Apply app rules, coordinate ports, and return API DTOs.
Port traits	{entity}/ports.rs or agent.rs	Define store/catalog seams consumed by entity services.
Run state	run/state.rs	Project RunTelemetry into WorkflowRunState for UI and IPC.
Concrete storage	adapters/storage/	Read and write JSON files under {data_local}/openflow/, project workflow files, and run checkpoints.
Runtime I/O	adapters/tool_impl/, adapters/mcp/, adapters/infrastructure/	Perform filesystem, subprocess, MCP, git, and LSP work.
Shared DTOs	api.rs, error.rs	Define transport shapes and BackendError used across the crate.

Engine semantics stay in crates/engine. Orchestration wires the engine to providers, stores, tools, projects, and desktop-facing state.

Directory map

orchestration/src/
├── lib.rs
├── api.rs
├── error.rs
├── backend/
│   ├── mod.rs
│   └── tests.rs
├── adapters/
│   ├── storage/
│   │   ├── agent_store.rs
│   │   ├── app_workflow_store.rs
│   │   ├── project_store.rs
│   │   ├── project_workflow_store.rs
│   │   ├── run_checkpoint_store.rs
│   │   ├── settings_store.rs
│   │   └── skill_store.rs
│   ├── tool_impl/
│   ├── mcp/
│   └── infrastructure/
├── agent.rs
├── chat.rs
├── diagnostics.rs
├── project/
├── run/
│   ├── coordinator/
│   ├── execution/
│   ├── handoff.rs
│   ├── persistence.rs
│   └── state.rs
├── schedule/
├── settings/
├── terminal.rs
├── tool/
└── workflow/
    ├── authoring/
    └── catalog.rs

Entity reference

Workflow

File	Module path	Responsibility
workflow/catalog.rs	workflow::catalog	Merge app and project workflows; assign, unassign, rename, and split saves.
workflow/authoring/	workflow::authoring	AI-assisted workflow draft and validation turns.
workflow/ports.rs	workflow::ports	Workflow store traits consumed by the catalog.
adapters/storage/app_workflow_store.rs	adapters::storage::app_workflow_store	Persist app-level workflows.json.
adapters/storage/project_workflow_store.rs	adapters::storage::project_workflow_store	Discover and save per-project workflow files.

The catalog owns merge policy; the stores only read and write bytes.

Agent

File	Module path	Responsibility
agent.rs	agent	Callable agent CRUD, create_agent_node, and agent store trait.
adapters/storage/agent_store.rs	adapters::storage::agent_store	Persist openflow/agents.json.

Chat

File	Module path	Responsibility
chat.rs	chat	Persisted Chat identity, project/runtime config, title, timestamps, and durable run reference.
backend/chat.rs	backend::chat	Direct-chat commands and private workflow execution adapter.
adapters/storage/chat_store.rs	adapters::storage::chat_store	Persist openflow/chats.json separately from the workflow catalog.

Project

File	Module path	Responsibility
project/registry.rs	project::registry	Register and load project folders.
project/file_refs.rs	project::file_refs	Read project file-reference content.
project/ports.rs	project::ports	Project store trait and project DTO.
adapters/storage/project_store.rs	adapters::storage::project_store	Persist openflow/projects.json.

Run

File	Module path	Responsibility
run/registry.rs	run::registry	Addressable top-level sessions keyed by run_id; shared execution resources.
run/coordinator/mod.rs	run::coordinator	One session mutex; start_run, submit_*, stop_run, resume, replay, interrupts.
run/execution/	run::execution	Host loop, AI adapter, ToolPortImpl, headless execution, telemetry event projection.
run/handoff.rs	run::handoff	Validate, atomically persist, hash, and resolve canonical Markdown/JSON node handoffs.
run/persistence.rs	run::persistence	Durable run roots, records, and checkpoint metadata.
run/ports.rs	run::ports	Run checkpoint store trait.
run/skill_invocation.rs	run::skill_invocation	Resolve installed task-prompt skill tokens into frozen runtime prompt guidance.
run/state.rs	run::state	WorkflowRunState projected for UI and IPC.
adapters/storage/run_checkpoint_store.rs	adapters::storage::run_checkpoint_store	Persist run records and engine checkpoints.

Only run/execution/ constructs or drives InteractiveEngine, as required by the architecture contract.

Settings

File	Module path	Responsibility
settings/facade.rs	settings::facade	Settings UX backend: redaction, skill list, provider readiness, validation summary.
settings/provider.rs	settings::provider	Key precedence: transient input, stored key, then environment.
settings/model.rs	settings::model	Persisted settings DTOs.
settings/ports.rs	settings::ports	Settings and skill catalog traits.
adapters/storage/settings_store.rs	adapters::storage::settings_store	Persist settings.json.
adapters/storage/skill_store.rs	adapters::storage::skill_store	Scan configured roots for SKILL.md files.

Tool and infrastructure

File or folder	Module path	Responsibility
tool/registry.rs	tool::registry	Register builtin tools and their ToolTier and ToolConcurrency.
tool/runner.rs	tool::runner	Execute registered tools and persist large artifacts.
tool/dispatch.rs	tool::dispatch	Route calls to concrete tool implementations.
tool/retry.rs	tool::retry	Retry transient tool failures according to workflow policy.
adapters/tool_impl/	tools internal alias	Concrete read, ls, search, find, write, edit, bash, grep, and patch implementations.
adapters/mcp/	adapters::mcp	MCP server discovery and per-run clients.
adapters/infrastructure/git	git public alias	Execution-cwd-scoped diff and revert operations.
adapters/infrastructure/lsp	lsp public alias	LSP settings and format/diagnostic integration.

Diagnostics, schedule, and terminal

File or folder	Module path	Responsibility
diagnostics.rs	diagnostics	Append optional local debug output to a process-specific JSONL file in the system temporary directory.
schedule/	schedule	Evaluate workflow schedules and status.
terminal.rs	terminal	Manage embedded terminal sessions.

Request flow: start a run

sequenceDiagram
    participant UI
    participant Desktop
    participant Backend as backend/mod.rs
    participant Registry as run/registry
    participant Coordinator as run/coordinator
    participant Execution as run/execution
    participant Engine as engine::InteractiveEngine
    participant ToolPort as ToolPortImpl

    UI->>Desktop: invoke start_run
    Desktop->>Backend: AppBackend::start_run
    Backend->>Registry: RunRegistry::start_run
    Registry->>Coordinator: create one RunCoordinator
    Coordinator->>Execution: spawn_interactive_workflow_run
    Execution->>Engine: engine.run(ai, tool_port, cancel_token)
    Engine->>ToolPort: ToolPort::run_tools
    ToolPort-->>Engine: ToolResult batch
    Execution-->>Coordinator: RunTelemetry stream
    Coordinator-->>Backend: WorkflowRunState
    Backend-->>Desktop: IPC payload

AppBackend delegates run lifecycle operations to RunRegistry, which owns one RunCoordinator per live or retained in-process run. Different workflows may run concurrently, but the registry rejects a second active run for the same workflow. It targets 64 retained sessions by evicting inactive sessions first and never evicts an active session.

Registry operations accept an optional run ID internally: an explicit ID selects that session; omitting it selects the latest session for legacy backend calls. Missing explicit IDs return an error. AppBackend retains separate addressed and legacy methods for existing consumers.

The coordinator completes fallible launch setup, including durable resume status writes, before spawning execution. It then installs handles without an intervening await. The headless runner cancels and joins execution on return; dropping its future cancels and aborts the owned task.

Hashline editing uses one concrete snapshot store, with a single mutex over versions and path recency so concurrent writes cannot bypass eviction. Bash and MCP package installation share the process-group cleanup helper in adapters/infrastructure/process.rs.

Where to add code

Change	Put it here
New workflow merge rule	workflow/catalog.rs.
New workflow file layout	adapters/storage/app_workflow_store.rs or adapters/storage/project_workflow_store.rs.
New project registry behavior	project/registry.rs plus project/ports.rs if the store seam changes.
New run lifecycle step	run/coordinator/mod.rs or run/execution/.
New UI run field	run/state.rs plus engine::RunTelemetry if the engine emits new state.
New builtin tool	adapters/tool_impl/, tool/registry.rs, tool/dispatch.rs, and crates/engine/src/tools/config.rs; also update NODE_RUNTIME_PREAMBLE in crates/engine/src/execution/node_invocation.rs.
New settings field	settings/model.rs, adapters/storage/settings_store.rs, and settings/facade.rs if UI-facing.
New desktop command	Delegate in backend/mod.rs; implement in the owning service module.

Import rules

Folder	May import
backend/	Entity services, storage adapters, api, and error.
workflow/, agent/, project/, settings/, tool/	Engine types, local ports, sibling modules, and shared DTOs. They must not import crate::adapters::.
run/	Engine types, providers through AiPort, tool infrastructure, run ports, and run state.
adapters/storage/	Engine types, entity port traits, filesystem/JSON support.
adapters/tool_impl/, adapters/mcp/, adapters/infrastructure/	Engine tool types and concrete I/O crates.

Cross-entity work goes through services or backend/. Entity services should depend on port traits when a concrete store would otherwise leak persistence details.

Persistence locations

Data	Location	Owning module
App workflows	{data_local}/openflow/workflows.json	orchestration/src/adapters/storage/app_workflow_store.rs
Projects	{data_local}/openflow/projects.json (migrates from legacy slug)	orchestration/src/adapters/storage/project_store.rs
Saved agents	{data_local}/openflow/agents.json (migrates from legacy slug)	orchestration/src/adapters/storage/agent_store.rs
Settings	{data_local}/openflow/settings.json	orchestration/src/adapters/storage/settings_store.rs
Project workflows	{project}/.flow/workflows/{workflowId}.workflow.json	orchestration/src/adapters/storage/project_workflow_store.rs
Provider API keys	Plaintext in settings.json (ProviderProfile.api_key)	orchestration/src/adapters/storage/settings_store.rs
Skills	Discovered at runtime from Cursor/Claude/Agents skill dirs (not persisted)	orchestration/src/adapters/storage/skill_store.rs

AppBackend::load_all_workflows merges app-store workflows with project-discovered workflows (project files win on ID collision).

run_checkpoint_store writes to {data_local}/openflow/runs/ or the project-scoped run root selected by orchestration. Data locations lists run attachments, handoffs, and credential storage.