Skip to main content

Bicycle Studio architecture

Synced from bicycle-studio-api

Source: docs/architecture/README.md at origin/platform (c2ce9cf), synced 2026-09-26. Do not edit this page here; change the source and run yarn sync:studio.

For engineers joining the platform team and for coding agents. Everything here was checked against the code on origin/platform (Studio API a78212f, data-app-runtime 0583b0c, studio-snapshot-worker 2241304, ui-bicycle-studio caf434a) and the live preview deployments on 26 Sep 2026. Where a status document and the code disagreed, the code won and the difference is called out in the page.

PageWhat it answers
overview.mdWhich systems exist, what each owns, how they are deployed on preview (namespaces and deployment names), one component diagram
storage.mdEvery kind of state: where it lives (blob-store document paths, Redis keys, Postgres tables, Temporal), who writes and reads it, durability, retention, what a restart loses; the in-flight changes (#48, #39) as "changing" notes
interactions.mdA sequence diagram and a short narrative for each flow: function Try, calls from apps / agents / MCP, workflow runs (manual, cron, app-triggered), snapshot nodes, send steps and approvals, agent runs, data-app chat, Detect/Explain, Schedule Mode, publish with review, disable/enable
security.mdIdentities and grants, visibility rules, the allowlists and caps on preview
decisions.mdThe numbered decisions (#1–#48, X1–X15) as they stand, one line of rationale each
operations.md (in the bicycle-studio-api repository, not published)Flags per environment, deploy order, rollback after #48, where the logs are, the quota and limit knobs
  • API.md (in the bicycle-studio-api repository, not published): the route-by-route API list (REST and MCP). The architecture pages link to it rather than repeat request and response shapes. Its "Storage … there is no Postgres run DB. Runner: asyncio tasks in the API pod" paragraph under the workflows section describes the deprecated in-process path; preview runs the workflow-runner (see operations.md (in the bicycle-studio-api repository, not published)).
  • the digest workflow example: a workflow bundle that validates and runs (it still uses the deprecated destination alias; new documents put recipients on the send step's to).
  • src/bicycle_studio_api/workflows/docs/WORKFLOWS.md: the coding-agent guide for workflows, served filled-in by GET /api/studio/v1/workflows/guide and the MCP workflow_guide tool. Read it from the API, never copy it.
  • tests/fixtures/workflow_runner_contract.json and snapshot_worker_contract.json: the pinned wire contracts between Studio and the runner / the snapshot worker.

Removed​

Two plan documents that described work since built were deleted with this set:

  • docs/PUBLISH_REGISTRY_PLAN.md (publishing apps into a registry.json in blob-store for the UI to read directly): the UI reads and publishes through this API (ui-bicycle-studio/src/platform/studio/studioApi.ts); no registry writer exists in the service.
  • docs/UI_ON_API_PLAN.md (the plan for that change): built; the routes it lists are in API.md (in the bicycle-studio-api repository, not published).

Conventions used in these pages​

  • Paths are given as the code names them: blob-store document keys are relative to the tenant prefix blob-store adds from the credential, Redis keys include their real prefix (bsa-rt:, bsa-claim:, studio:), Postgres tables are named as the migrations create them.
  • Service names are Kubernetes service names (<runtime-server host>), never hostnames beyond the cluster. No token, key or customer model id appears anywhere in these pages.
  • "Preview" means the preview-* deployments in namespace bicycle-studio (Studio, runtime-server, workflow-runner, snapshot worker), bicycle-ai (agent-service, tool-service) and ui; "prod" means the same charts without the prefix.