Architecture
A layered control-plane architecture that separates governance, execution, and instrumentation to keep ownership explicit and failures contained.
Bot Velocity is designed around strict responsibility boundaries. The control plane governs lifecycle and retry authority. The execution plane runs isolated workloads under time-bounded leases. The runtime SDK carries trace and cost context inside each execution. This separation prevents systemic coupling and ensures intelligent workflows remain governed, observable, and recoverable.
System Overview
┌─────────────────────────────────────────────────────┐
│ Control Plane — Orchestrator │
│ Lifecycle Governance • Retry Authority • │
│ Evaluation Engine • Tool Registry │
└──────────────────────┬──────────────────────────────┘
│ Pull-based dispatch
▼
┌─────────────────────────────────────────────────────┐
│ Execution Plane — Runner │
│ Package Resolution • Lease Ownership • │
│ Subprocess Isolation │
└──────────────────────┬──────────────────────────────┘
▼
┌─────────────────────────────────────────────────────┐
│ Runtime SDK │
│ Structured Tracing • Logging • call_process │
│ MCP Tool Invocation │
└─────────────────────────────────────────────────────┘
The orchestrator owns state transitions, retry decisions, dead-letter routing, and evaluation enforcement. Runners execute user workloads in isolation under lease protection. The runtime SDK instruments execution with structured trace, cost attribution, and nested orchestration support.
Deterministic Job Lifecycle
┌─────────┐
│ pending │
└────┬────┘
│ claim (lease acquired)
▼
┌─────────────┐
│ in_progress │
└──┬───────┬──┘
│ │
success │ │ system_error
▼ ▼
┌─────────┐ ┌──────────────┐
│ success │ │ system_error │
└─────────┘ └──────┬───────┘
│ retry (policy-controlled)
▼
┌─────────────┐
│ scheduled │
└──────┬──────┘
│
▼
(re-queued)
│
▼
pending
│
▼
┌─────────────┐
│ dead_letter │
└─────────────┘
Execution state transitions are explicit and enforced by the control plane. Retries occur only under policy authorization. Exhausted or non-retryable workloads are captured in a dead-letter queue for operator review. Every transition is recorded and auditable.
Nested Process Invocation
Parent Workflow
│
├── Step 1: Model generation
│
├── Step 2: call_process ──▶ Child Workflow
│ │
│ ├── Tool invocation
│ └── Model generation
│ │
│ ◀── result ──────────────┘
│
└── Step 3: Final decision logic
Workflows can invoke sub-workflows synchronously via call_process(). The child execution is independently governed by the control plane while maintaining trace continuity, cost attribution, and tenant scoping. This enables composable automation without sacrificing isolation or lifecycle integrity.
Evaluation Pipeline
┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
│ Baseline │ ─▶ │ Run New │ ─▶ │ Compare │ ─▶ │ Gate │
│ Dataset │ │ Evaluation │ │ Results │ │ Pass/Fail │
└────────────┘ └────────────┘ └────────────┘ └────────────┘
│
▼
Regression detected? → Block
Flaky behavior? → Flag
Pass threshold? → Promote
Evaluation operates on real execution artifacts. Baseline comparison, regression detection, flaky analysis, and policy thresholds integrate directly into release workflows. Promotion to production is governed, not assumed.
Tenant & Isolation Model
Organization
├── Tenant A
│ ├── Folder: production
│ │ ├── Encrypted credentials (scoped)
│ │ ├── Hash-validated packages
│ │ └── RBAC-governed executions
│ └── Folder: staging
│
└── Tenant B
└── Folder: production
└── (strictly isolated — no cross-tenant access)
Tenant and folder boundaries are enforced at the orchestration layer. Credentials remain encrypted and scoped. Packages are validated prior to execution. Access control is role-based. Cross-tenant access is blocked by design.