Architecture

B3OS gives teams one place to design, test, run, and observe workflows that connect apps, chains, wallets, APIs, and Caddie-assisted automation. The important contract is simple: workflows define intent, B3OS validates and runs each step, and external systems only receive the calls you configure.

Platform Layers

Layer	What it does
Authoring surface	Visual editing, testing, publishing, versions, templates, and workflow review
REST API	Programmatic access for workflow creation, runs, connectors, API keys, templates, and execution hooks
Execution engine	Starts runs, resolves expressions, applies branches and waits, and records step results
Action runtime	Runs typed actions with declared inputs, outputs, connector requirements, and wallet requirements
State and audit layer	Keeps workflow versions, run history, activity streams, policy checks, and usage records
External systems	Apps, protocols, chain RPCs, webhooks, wallets, and customer backends connected by workflows

Request and Execution Flow

Control Plane

Capability	What it manages
Workflow definitions	Drafts, live versions, validation, rollback, visibility, public views, and workflow details
Organizations	Members, roles, usage, managed data, connectors, wallets, billing settings, and knowledge
Access	User sessions, API keys, role permissions, scopes, org context, and public route boundaries
Observability	Runs, node executions, activity streams, error summaries, logs, search, tags, templates, and usage stats
Integration surfaces	Incoming webhooks, execution hooks, connector flows, wait-node resumes, public runs, and x402 endpoints

Execution Plane

1. A trigger creates a run with input.
2. B3OS loads the live workflow definition and organization context.
3. Node payloads are resolved with expression templates.
4. Built-in nodes run in the workflow engine; catalog actions run through the managed action runtime.
5. Results are recorded per node and made available to downstream steps.
6. Branch, loop, delay, wait, and child-workflow behavior decides what runs next.
7. Run status resolves to success, failure, waiting, or cancelled.
8. Execution hooks and activity streams deliver downstream notifications.

Action Runtime

B3OS provides a typed action catalog with names, descriptions, input schemas, output schemas, connector requirements, tags, and supported execution behavior.

Use the action, trigger, and API references for exact IDs, inputs, outputs, and connector requirements. Use the narrative guides for design choices and implementation patterns.

Data Boundaries

Data type	Handling
Connector credentials	Stored and used through connector records; clients receive masked views
API keys	Shown once, scoped, revocable, and designed for server-side use
Secrets in executions	Masked before logs and responses are shown
Webhook secrets	Managed separately from workflow definitions and used for signing
Wallet signing material	Managed by wallet controls and not exposed to workflow authors

Developer Surfaces