Bezel Workflow architecture-decision
internal prototype · canonical JSON + Dreamborn Forge HTML
internal generated
architecture-decision · supabase_json

Bezel Workflow architecture-decision

architecture-decision artifact · for Bezel Workflow · status draft

Planning Surface

Use this to decide what happens next.

Status

draft

Agent Handoff
Start Here

architecture-decision artifact · for Bezel Workflow · status draft

Completion Evidence

No explicit evidence field yet. Require tests, screenshots, linked PRs, or reviewed outputs before marking complete.

Decision

Keep Bezel Workflow and Bezel API together in the Bezel API repo/build stream, but treat them as separate products/layers: Bezel Workflow is the human-readable workflow product; Bezel API is the agent-readable runtime/API product.

Structured Payload

Machine-readable source fields

kind

architecture-decision

project

Bezel Workflow

decision

Keep Bezel Workflow and Bezel API together in the Bezel API repo/build stream, but treat them as separate products/layers: Bezel Workflow is the human-readable workflow product; Bezel API is the agent-readable runtime/API product.

rationale
  • This matches the Bezel two-world model: humans work in product surfaces; agents consume structured runtime contracts.
  • Bezel API already owns the agent-readable primitives: accounts, workspaces, roles, queues, agents, plans, workflow runs, tasks, dependencies, claims, leases, release/reclaim, terminal outcomes, workflow events, and Lite HCS claim proofs.
  • Bezel Workflow should not duplicate the runtime. It should translate human-authored flows into machine-readable runtime plans and render machine events back into human workflow status.
  • This preserves one execution kernel while allowing the product UI, positioning, and UX to feel like a Zapier/n8n replacement rather than an API dashboard.
  • The Bezel API project is actively being built and already contains the runtime primitives Bezel Workflow needs, so keeping them together avoids duplicate schema/auth/claim/event/runtime work.
  • The product boundary still matters: Bezel Workflow should be designed as the Zapier/n8n-facing human product while Bezel API remains the agent-readable execution substrate.
decided at

2026-05-09T13:05:47.350Z

boundary rule

Humans never author low-level task graphs directly once the Workflow product exists. They author Flows. Bezel Workflow compiles Flows into Bezel API runtime plans. Agents never consume human prose workflow screens; they consume Bezel API contracts.

product split
agent readable product
name

Bezel API

owns
  • Runtime schemas and contracts
  • Plan materialization into workflow runs, tasks, and dependencies
  • Role and queue resolution
  • Agent registration and API-key authentication
  • Claim-next, renew, release, complete, fail, cancel lifecycle
  • Workflow event stream and Lite HCS proof boundary
  • Connector execution contracts and structured completion payloads
outputs to human product
  • workflow run summaries
  • task status rows without sensitive inputs
  • event timeline rows
  • claim/proof references
  • structured remediation objects
human readable product
name

Bezel Workflow

owns
  • Flow builder and workflow templates
  • Connector setup and credential configuration UX
  • Run timeline and operational status views
  • Human-readable error/remediation surfaces
  • Approvals and policy controls
  • Product positioning against Zapier, n8n, Make, and Temporal
outputs to runtime
  • FLOW.json
  • connector credential references
  • policy and approval settings
  • runtime plan submissions
repo decision
rule

Do not create a separate Bezel Workflow repo yet. Build Workflow and API together while preserving explicit product/runtime boundaries.

canonical repo

/Users/justinking/Vaults/Projects/bezel-api

separation model
  • Separate artifacts and product language in Studio.
  • Separate package/module boundaries inside the repo where practical.
  • Separate human UI/Workflow concerns from runtime API contracts.
  • Shared contracts for FLOW.json, claims, events, connector manifests, and credential references.
  • Avoid routing local-first Workflow dogfooding through hosted API calls unless the feature explicitly targets hosted/multi-tenant runtime.
future split condition

Only split repos if Bezel Workflow becomes a separately deployed product with a different release cadence or ownership model from Bezel API.

next artifacts
  • runtime-boundary-spec for same-repo separate-layer architecture
  • repo/module layout spec for Bezel Workflow inside bezel-api
  • FLOW.json schema
  • flow-to-plan compiler spec
  • connector credential UX/data spec
  • workflow run timeline UX spec
schema version

architecture-decision.v1

repo recommendation
now

Keep Bezel Workflow implementation coupled to bezel-api plus the chosen UI/control-surface repo. Do not create a separate runtime repo yet.

later split condition

Split only if the human product surface becomes a separately deployed application with distinct ownership/release cadence while Bezel API remains the shared runtime.