Skip to main content

Source: docs/manual/architecture.md

This page is generated by site/scripts/sync-manual-docs.mjs.

Architecture

Cruvero is structured around Temporal workflows and deterministic workflow code. All nondeterministic I/O (LLM calls, tools, storage, events) runs in activities.

System Diagram​

Runtime Components​

  • Temporal cluster: source of truth for workflow state and orchestration.
  • Worker process: executes all workflow activities and integration I/O.
  • Postgres: primary durable store for registry, memory, traces, audit, quotas, and tenancy metadata.
  • Dragonfly: optional fast KV and counter store.
  • Qdrant/pgvector: embedding vector storage for semantic retrieval/search paths.
  • NATS JetStream: event transport for runtime signals, MCP discovery, and buffered async pipelines.

Core Workflows​

  • Agent workflow: internal/agent/workflow.go
  • Graph workflow: internal/graph/workflow.go
  • Supervisor workflow: internal/supervisor/workflow.go

Data Flow​

  1. A client starts a run via API/CLI into Temporal.
  2. Worker loads immutable tool registry and memory context.
  3. LLM decision is produced through configured provider/failover chain.
  4. Tool execution routes through built-in, MCP, or composite tools.
  5. Semantic retrieval/indexing uses Qdrant or pgvector.
  6. Runtime/audit/discovery events are published/consumed via NATS when enabled.
  7. Observations, traces, and audit records persist to Postgres.
  8. Quota and tenant policy checks gate continued execution.

Design Guarantees​

  • Workflow determinism: no side effects in workflow code.
  • Immutable registries: content-hashed tool versions for replay integrity.
  • Tenant isolation: namespace separation + Postgres RLS boundaries.
  • Audit integrity: hash-chained audit records per tenant.
  • Degraded-mode operation: event/vector backends can fall back based on config.