repo-module-layout-spec · supabase_json
Bezel Workflow repo-module-layout-spec
repo-module-layout-spec artifact · for Bezel Workflow · status draft
Agent Handoff
Start Here
repo-module-layout-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.
Artifact Shape
- kind: repo-module-layout-spec
- repo: /Users/justinking/Vaults/Projects/bezel-api
- project: Bezel Workflow
- created by: atlas-codex
- guardrails: 4 items
- updated at: 2026-05-09T13:17:30.522Z
- schema version: repo-layout.v1
- proposed layout: 6 items
- source memory id: 99edd8d2-5780-43a2-bbd0-03982353768a
- dependency direction: 7 items
- near term recommendation: Start with packages/workflow-contracts and packages/workflow-compiler. Add packages/connectors once FLOW can reference connector actions. Use apps/dashboard only for the first internal operational surface until a dedicated Workflow UI is justified.
- architecture decision ref: 3a1bb081-67f9-41ae-9600-a91fbb14ecda
Structured Payload
Machine-readable source fields
kind
repo-module-layout-spec
repo
/Users/justinking/Vaults/Projects/bezel-api
project
Bezel Workflow
created by
atlas-codex
guardrails
- Do not put workflow product UX fields directly into existing PlanIntake unless they are runtime-relevant.
- Do not let connector implementations depend on browser UI state.
- Do not add hosted-only credential assumptions to FLOW.json.
- Do not duplicate claim lifecycle logic outside store/runtime adapters.
updated at
2026-05-09T13:17:30.522Z
schema version
repo-layout.v1
proposed layout
| path | purpose |
|---|---|
| packages/workflow-contracts | FLOW.json, connector manifest, credential reference, run event, and compiler input/output contracts. May start inside packages/contracts if we want fewer packages, but the boundary should be explicit. |
| packages/workflow-compiler | Compiles human-authored FLOW.json into Bezel API runtime plans/tasks/dependencies. Pure package, no DB/network. |
| packages/connectors | Connector manifests and local connector action implementations. Keep connector SDK/runtime code separate from the API HTTP layer. |
| packages/local-runtime | Local-first execution adapter for dogfooding: storage, queue, claims, and connector execution behind the same runtime interfaces. Can be deferred if apps/api local HTTP is sufficient. |
| apps/workflow | Human Workflow product UI if/when apps/dashboard becomes too small. Until then, apps/dashboard can host early product screens. |
| apps/api | Hosted/multi-tenant API routes, auth, migrations, runtime wiring, and production smoke. |
source memory id
99edd8d2-5780-43a2-bbd0-03982353768a
dependency direction
- apps/workflow or apps/dashboard -> packages/workflow-contracts
- apps/workflow or apps/dashboard -> packages/workflow-compiler
- apps/api -> packages/workflow-contracts
- apps/api -> packages/store
- packages/workflow-compiler -> packages/workflow-contracts and packages/contracts
- packages/connectors -> packages/workflow-contracts
- packages/contracts must not import UI/app packages
near term recommendation
Start with packages/workflow-contracts and packages/workflow-compiler. Add packages/connectors once FLOW can reference connector actions. Use apps/dashboard only for the first internal operational surface until a dedicated Workflow UI is justified.
architecture decision ref
3a1bb081-67f9-41ae-9600-a91fbb14ecda
current repo observations
- Repo is already an npm workspace monorepo with apps/* and packages/*.
- Existing runtime packages: packages/contracts, packages/store, packages/sdk-js, packages/hcs-writer.
- Existing apps: apps/api and apps/dashboard.
- Current PlanIntake contract is low-level: name plus tasks with role_id/input/depends_on.
- Current API already exposes workflow run/task/event reads suitable for a dashboard-safe timeline.