api_repo_architecture · supabase_json
Bezel API api_repo_architecture
api_repo_architecture artifact · for Bezel API · status draft
Agent Handoff
Start Here
api_repo_architecture artifact · for Bezel API · status draft
Completion Evidence
No explicit evidence field yet. Require tests, screenshots, linked PRs, or reviewed outputs before marking complete.
Artifact Shape
- version: 0.1
- repo name: bezel-api
- repo path: /Users/justinking/Vaults/Projects/bezel-api
- guardrails: 5 items
- initial stack: docs: string, tests: string, language: string, validation: string, api_runtime_decision: string
- package layout: 10 items
- recommendation: Start as a focused TypeScript product repo with API service, onboarding dashboard, shared contracts, and SDK snippets. Keep HCS writer behind a replaceable boundary.
- first build order: 11 items
- service boundaries: 7 items
Structured Payload
Machine-readable source fields
version
0.1
repo name
bezel-api
repo path
/Users/justinking/Vaults/Projects/bezel-api
guardrails
- Do not build a visual workflow builder in v1.
- Do not make OpenClaw the core product boundary.
- Do not expose raw HCS topic management to normal users.
- Do not allow unapproved natural-language software-build prompts to dispatch directly to agents.
- Do not store large model outputs or secrets in HCS events.
initial stack
docs
OpenAPI generated from route contracts once endpoint contract stabilizes
tests
Vitest for contract/unit tests; integration smoke for first task claim loop
language
TypeScript
validation
Zod or JSON Schema at every public boundary
api runtime decision
Open question: Cloudflare Workers edge with separate HCS writer boundary vs single Node service for first claim-loop stability.
package layout
| path | purpose |
|---|---|
| apps/dashboard | Onboarding and admin UI: account, workspace, API key, roles, agents, queues, receipts, usage |
| apps/api | Hosted public API routes and auth/session handling |
| packages/contracts | Shared request/response schemas, event types, plan.json schema, receipt types |
| packages/sdk-js | TypeScript SDK used by onboarding snippets and OpenClaw adapter |
| packages/openclaw-adapter | First public adapter; depends on SDK, not internal API code |
| packages/hcs-writer | Replaceable HCS write/proof boundary; can later move to VPS/service without changing public routes |
| packages/store | DB access layer with workspace-scoped query helpers and transaction helpers |
| docs | API docs, onboarding docs, adapter examples, receipt examples |
| examples/curl-first-claim | Minimal curl flow for account/workspace/role/agent/queue/task/claim/receipt |
| examples/openclaw-five-agents | First public demo: five agents, one queue, parallel claims, missed claim handling, receipt replay |
recommendation
Start as a focused TypeScript product repo with API service, onboarding dashboard, shared contracts, and SDK snippets. Keep HCS writer behind a replaceable boundary.
first build order
- Repo scaffold with contracts package and test runner
- Auth/session shell with no billing complexity
- Workspace and API key model with workspace-scoped query enforcement
- Role creation with stubbed HCS writer interface
- Agent registration and role assignment
- Queue and simple task publish
- Claim endpoint with claimed/missed/rejected semantics in local deterministic mode
- Receipt/read-model projection with fake proof in local mode
- Swap HCS writer stub for real RedKey/Hedera-backed writer
- Dashboard onboarding screens wired to the same endpoints
- OpenClaw adapter demo after the curl/SDK loop is mechanically passing
service boundaries
| name | owns | must not own | must not expose |
|---|---|---|---|
| Auth | - human account/session lifecycle - password/OAuth hooks | - agent task claiming | |
| Workspace | - tenant boundary - members - API keys - usage credits | ||
| Agent Registry | - Agent Card ingestion - endpoint verification - role assignment | ||
| Coordination | - queues - tasks - claims - leases - missed/rejected semantics | ||
| Workflow | - plan intake - plan validation - workflow runs - dependency release | ||
| Ledger | - event projection - receipt projection - ledger replay | ||
| HCS Writer | - topic creation - event submission - proof capture | - operator keys - raw Hedera SDK operations to normal API callers |