Architecture

System Architecture

Cascade's shared orchestration engine sits inside a TypeScript/Node.js monorepo. The CLI, desktop application, cloud server and SDK use the same underlying core, with different host capabilities and security boundaries.

flowchart TD
  U[User / client] --> CLI[CLI / Ink]
  U --> Desk[Desktop / Electron]
  U --> Web[Cloud Web / React]
  U --> API[OpenAI compatible API]
  CLI --> Core[Cascade orchestrator]
  Desk --> Core
  Web --> Server[Cloud server / Express and Socket.IO]
  API --> Server
  Server --> Core
  Core --> Router[Classifier + model router]
  Core --> Graph[Task graph + scheduler]
  Core --> Tiers[T1 / T2 / T3]
  Router --> Providers[LLM provider adapters]
  Tiers --> Tools[Tools / MCP / workspace]
  Server --> DB[(SQLite / per-user storage)]

Loading

Code map

Path	Responsibility
src/core/cascade.ts	Run lifecycle, orchestration facade and events
src/core/tiers/	T1 administrator, T2 managers, T3 workers, planning and escalation
src/core/orchestration/	Typed task graph, dependency scheduler, checkpoints/resume
src/core/router/	Complexity analysis, benchmarks, routing, budgets and failover
src/providers/	Anthropic, OpenAI, Gemini, Azure, Ollama and OpenAI-compatible adapters
src/tools/	Shell, file, git, web, media, documents, browser and MCP tools
src/browser/	Browser lease and remote CDP/Steel integration
src/config/	Config schema, keystore, credential discovery and linking
src/cli/	Commander interface, Ink REPL, slash commands and themes
src/retrieval/	Code indexing and retrieval
src/core/documents/	Shared document renderers
app/	Electron host, React UI, Cockpit/editor and browser
cloud/server/	Sessions, auth, runs, storage, /v1 and remote browser
cloud/web/	Hosted landing/chat/settings/connector UI
web/	Local dashboard SPA

Trust boundaries

The desktop can interact with local files and an authenticated browser page. Hosted cloud runs operate within tenant/auth boundaries and have different available tools; remote browser endpoints are operator-provided, not user-selectable network targets. The HTTP API invokes noninteractive orchestration, so it cannot wait for user approval in the same way as an interactive UI.

Cloud uses SQLite for persistent user/conversation state. Deployment without a persistent DATA_DIR risks losing data at redeploy. Model credentials for hosted web runs are client controlled; opt-in settings synchronization uses encrypted envelopes.

Read next: Agent-Orchestration, Tools-and-MCP, Security-and-Privacy. Source: src/core/.