Overview
System architecture
Canyon is assembled from six distinct layers, each responsible for a single concern. A chat-driven console. An authenticated API. A multi-agent orchestrator. A tool layer that speaks MCP. Isolated sandbox runtimes. A governed data layer. Each layer is independently scalable, replaceable, and auditable.
BetaUpdated April 2026•Reference•Canyon v1.0
BetaThese docs are in beta
Expect gaps and drift from the live product. Something unclear or missing? Grab 30 minutes with the team and we will walk you through it.
Layered view
Every layer is independently deployable. The API gateway is stateless; every orchestrator node is a pod; each sandbox is a short-lived, isolated container. The tool layer is the one piece that spans both Canyon-native and customer-owned systems — this is how Canyon reaches private data and internal tooling without those things ever leaving your perimeter.
1Canyon Console
Modern, typed web UI
Chat-driven workspace for building, previewing and shipping apps.
ChatCode explorerLive previewCheckpointsKPI builder
2API Gateway
REST + streaming
Single entry point for every workspace action, with authenticated, audited routing.
Auth / SSOChatSandboxProjectsMetricsMCPAdminAudit
3Agent Orchestrator
Model-agnostic
Five specialised agents: Intent, Planner, Builder, Validator, Conversation.
IntentPlannerBuilderValidatorConversation
4Tool layer (MCP)
MCP · stdio · SSE · HTTP
Aggregates Canyon-native tools and your existing MCP-speaking systems behind one router.
Design systemData sourcesCode reposNotificationsCustom tools
5Sandbox Manager
Containerised · bidi streaming
Ephemeral, isolated runtimes where agents generate, validate and preview code.
Local runtimeCloud runtimeRepo syncCheckpoints
6Data Layer
Governed · multi-tenant
Operational data, session cache, the Canyon semantic layer, and per-project code repos.
Operational DBSession cacheCanyon semantic layerCode repos
Request path
Users interact through the Canyon Console. The API gateway routes authenticated requests to the orchestrator, which classifies intent, plans changes, generates code in an isolated sandbox, and validates the output. Every change is persisted as a Git commit and a checkpoint snapshot so time travel is a click away.
- Console sends an authenticated chat request.
- Intent Agent classifies the message in sub-second time, using a fast classification model.
- On a build or modify intent, the request is forwarded to the code-generation pipeline.
- Planner Agent produces a file-by-file spec using the design system and tool layer.
- Builder Agent executes inside a sandbox, calling read/write/edit and your MCP tools.
- Validator Agent runs deterministic checks (type-checker, linter, constraint rules).
- On success, code is committed and checkpointed. On failure, the retry loop kicks in.
Reference diagram
The canonical picture — the one every Canyon engineer keeps on their desk.
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ CANYON CONSOLE │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Chat │ │Code Explorer│ │Live Preview │ │ Checkpoints │ │ KPI Builder │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ API GATEWAY │
│ auth · chat · sandbox · projects · metrics · MCP · admin · audit │
└─────────────────────────────────────────────────────────────────────────────────────────┘
│
┌────────────────────────────┼────────────────────────────┐
▼ ▼ ▼
┌─────────────────────────┐ ┌─────────────────────────┐ ┌─────────────────────────┐
│ AGENT ORCHESTRATOR │ │ TOOL LAYER (MCP) │ │ SANDBOX MANAGER │
│ ┌───────────────────┐ │ │ ┌─────────────────┐ │ │ ┌─────────────────┐ │
│ │ Intent Agent │ │ │ │ Design System │ │ │ │ Local sandbox │ │
│ │ Planner Agent │ │ │ │ Data sources │ │ │ │ Cloud sandbox │ │
│ │ Builder Agent │ │ │ │ Code repo │ │ │ │ Repo sync │ │
│ │ Validator Agent │ │ │ │ Custom tools │ │ │ │ Checkpoint Mgr │ │
│ │ Conversation │ │ │ └─────────────────┘ │ │ └─────────────────┘ │
│ └───────────────────┘ │ └─────────────────────────┘ └─────────────────────────┘
└─────────────────────────┘ │ │
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ DATA LAYER │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Operational │ │ Session cache │ │Canyon Semantic │ │ Code repos │ │
│ │ multi-tenant │ │ & pub/sub │ │ layer │ │ (per project) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────────────┘Architectural guarantees
Isolation by default
Every user session runs in its own container. No shared filesystem, no shared process space, no shared namespaces.
Deterministic validation
The Validator Agent is not a language model. It runs real type checkers and linters against the generated sources and returns structured error objects.
Governed data reads
All database access flows through the Canyon semantic layer — never raw SQL. Metrics are defined once and enforced everywhere.
Reproducible deploys
Every generated project is a Git repository with every change committed and a corresponding checkpoint. Time travel is a git checkout away.
Your perimeter
Data stays where it already lives. Sandboxes, runners and the data layer can be deployed entirely inside your cloud or on-prem.
Next up
Continue to Agent orchestration for the inside of the pipeline, or jump to Deployment for the production topology.