architecture-spec · supabase_json
Bezel Workflow architecture-spec
architecture-spec artifact · for Bezel Workflow · status draft
components
| name | purpose |
|---|---|
| Flow Definition | Customer-authored route describing triggers, sequential steps, parallel fan-out groups, integration roles, guardrails, and completion criteria. |
| Router Agent / Flow Engine | Persistent orchestrator that reads a Flow, dispatches jobs to topics, watches completion topics, decides next steps, handles retries/fallbacks, and records routing decisions. |
| Topic-Based Pull Queues | Jobs land on integration or capability topics. Compatible agents claim work atomically when they have capacity. |
| Role per Integration | Each connector/integration has a role/topic and assigned agent pool, allowing independent scaling by integration load. |
| Connector Agents | Agents execute connector work, interpret API responses, adapt to unexpected response shapes, and produce structured completion payloads. |
| Credential Vault | Stores OAuth/API secrets externally with secret IDs in Bezel DB; credentials are scoped per workflow and every access is logged. |
| Completion Event Stream | Structured completion/failure/blocked/claim-expired events consumed by the Router Agent and rendered in Studio for humans. |
| Observability and Audit | Visible trace of every job, claim, dispatch, completion, retry, credential access, and routing decision. |
open questions
- Whether MVP vault is GCP Secret Manager, Cloudflare Secrets, or a thin abstraction over both.
- How much self-healing is allowed to happen autonomously before requiring human approval.
- Whether HCS claim proofs are exposed in V1 product UI or kept as internal audit infrastructure.
Agent Handoff
Start Here
architecture-spec artifact · for Bezel Workflow · status draft
Completion Evidence
No explicit evidence field yet. Require tests, screenshots, linked PRs, or reviewed outputs before marking complete.
Components
- Flow Definition: name: string, purpose: string
- Router Agent / Flow Engine: name: string, purpose: string
- Topic-Based Pull Queues: name: string, purpose: string
- Role per Integration: name: string, purpose: string
- Connector Agents: name: string, purpose: string
- Credential Vault: name: string, purpose: string
- Completion Event Stream: name: string, purpose: string
- Observability and Audit: name: string, purpose: string
Execution Model
- bezel flow: 5 items
- temporal contrast: Temporal uses worker pull queues but trigger/state-change orchestration. Bezel uses pull semantics in both execution and control planes.
Open Questions
- Whether MVP vault is GCP Secret Manager, Cloudflare Secrets, or a thin abstraction over both.
- How much self-healing is allowed to happen autonomously before requiring human approval.
- Whether HCS claim proofs are exposed in V1 product UI or kept as internal audit infrastructure.
Structured Payload
Machine-readable source fields
kind
architecture-spec
project
Bezel Workflow
components
| name | purpose |
|---|---|
| Flow Definition | Customer-authored route describing triggers, sequential steps, parallel fan-out groups, integration roles, guardrails, and completion criteria. |
| Router Agent / Flow Engine | Persistent orchestrator that reads a Flow, dispatches jobs to topics, watches completion topics, decides next steps, handles retries/fallbacks, and records routing decisions. |
| Topic-Based Pull Queues | Jobs land on integration or capability topics. Compatible agents claim work atomically when they have capacity. |
| Role per Integration | Each connector/integration has a role/topic and assigned agent pool, allowing independent scaling by integration load. |
| Connector Agents | Agents execute connector work, interpret API responses, adapt to unexpected response shapes, and produce structured completion payloads. |
| Credential Vault | Stores OAuth/API secrets externally with secret IDs in Bezel DB; credentials are scoped per workflow and every access is logged. |
| Completion Event Stream | Structured completion/failure/blocked/claim-expired events consumed by the Router Agent and rendered in Studio for humans. |
| Observability and Audit | Visible trace of every job, claim, dispatch, completion, retry, credential access, and routing decision. |
agent tiers
| use | tier | models |
|---|---|---|
| Simple API calls, formatting, low-risk connector execution | lightweight | - Flash - Haiku |
| Router decisions, interpretation, medium-complexity recovery | routing | - Sonnet - Pro |
| Self-healing edge cases, ambiguous failures, complex reasoning | advanced | - Opus - Ultra |
| Developer tasks and connector repair/code generation where allowed | code | - Codex - Claude Code |
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.
open questions
- Whether MVP vault is GCP Secret Manager, Cloudflare Secrets, or a thin abstraction over both.
- How much self-healing is allowed to happen autonomously before requiring human approval.
- Whether HCS claim proofs are exposed in V1 product UI or kept as internal audit infrastructure.
schema version
architecture.workflow.v1
execution model
bezel flow
- Jobs land on topics
- Agents pull and claim when ready
- Connector agents emit completion events
- Router Agent pulls completions
- Router Agent decides next dispatch or terminal status
temporal contrast
Temporal uses worker pull queues but trigger/state-change orchestration. Bezel uses pull semantics in both execution and control planes.
credential rules
- OAuth connectors use a shared OAuth foundation where possible.
- AI providers and databases may use API keys stored only in the vault.
- Database rows store vault references, never raw secrets.
- Credentials are scoped per workflow rather than globally per account by default.
- Credential reads are logged with actor, workflow, connector, timestamp, and reason.
source memory id
99edd8d2-5780-43a2-bbd0-03982353768a
two world product model
rule
Workflow compiles human-authored Flows into runtime contracts; API/runtime executes agent-readable contracts and emits structured events back to Workflow.
repo model
same repo/build stream, separate product and runtime layers
agent readable product
Bezel API
human readable product
Bezel Workflow
architecture decision ref
3a1bb081-67f9-41ae-9600-a91fbb14ecda