cambium ▸ docs/architecture/cambium-v1-architecture.md
updated 2026-03-27

Cambium V1 Architecture

Purpose

This document defines the V1 architecture for Cambium.

The goal is not to describe the final organism in full. The goal is to define the first buildable version of the platform in a way that is technically serious, strategically differentiated, and robust enough to grow toward something with the structural integrity of systems like OpenClaw and Paperclip.

So V1 needs to do two things at once: 1. Solve a real orchestration problem now 2. Establish the architectural bones for a much larger platform later

V1 Product Thesis

Cambium V1 is a resilient orchestration platform for agent systems, built around adaptive execution, system health, recovery, and governed action.

This is not a generic workflow builder. It is not a swarm of agents with vibes. It is not a manager dashboard with AI sprinkled on top.

V1 should prove that a nature-based orchestration model produces better operational behavior than brittle, purely linear automation.

V1 Scope

V1 should focus on five core capabilities:

  1. Adaptive orchestration via Hypha
  2. Workflow composition and visibility via Loom
  3. Threshold-based action gating via Quorum
  4. System health and homeostasis via a health layer
  5. Recovery and rollback via a seed/replay layer

This maps closely to the strongest wedge from earlier thinking: - immune detection - seeded recovery - homeostatic routing - quorum gating - non-central coordination

For V1, we should be ruthless about what lands in the core platform and what waits.

Official V1 Components

1. Cambium Core

The overall platform shell.

Responsibilities: - system identity - tenant/workspace boundary model - shared data contracts - auth and permissions model - event and state backbone - package and deployment topology

Cambium Core is the substrate that lets the other parts evolve without becoming a pile of scripts glued together.

2. Hypha Engine

The orchestration runtime.

Responsibilities: - execute workflows and agent tasks - model workflows as graphs, not just linear chains - manage state transitions - route work based on rules, signals, and system conditions - coordinate tool execution - support retries, fallbacks, and alternate paths - emit events for all significant transitions

V1 principle: Hypha should be event-driven and stateful from day one.

If we build it as a thin request-response wrapper over prompts, we will regret it almost immediately.

3. Loom Surface

The human-facing workflow surface.

Responsibilities: - define workflows - inspect runs - visualize execution paths and state - show failures, bottlenecks, and pending approvals - expose system health and recovery controls - let operators understand what the system is doing without reading raw logs all day

V1 principle: Loom should be operational, not decorative.

A pretty canvas with no real inspection depth is bullshit. The surface has to help operators debug, govern, and trust the system.

4. Quorum Layer

The governed action and threshold decision system.

Responsibilities: - define action policies - classify sensitive operations - require threshold approval for risky actions - aggregate votes, confidence, or rule satisfaction - create auditable decision records - support escalations and overrides

V1 principle: Quorum is not a nice-to-have.

If Cambium is going to coordinate meaningful autonomous action, governance cannot be an afterthought.

5. Homeostasis Layer

The system health and stress regulation subsystem.

Responsibilities: - track workload health metrics - monitor latency, cost, token burn, queue pressure, error rates, and context pressure - trigger throttling, rerouting, or degradation policies under stress - expose health state to Hypha and Loom

This is the V1 embodiment of the ThermoGuard / metabolism logic, even if the branding for that sub-layer stays internal for now.

V1 principle: The platform should know when it is overheating and respond automatically.

6. Seed Layer

The rollback, replay, and recovery subsystem.

Responsibilities: - snapshot workflow state - checkpoint important transitions - replay or resume interrupted runs - restore known-good configurations or workflow states - provide recovery hooks for failed orchestration paths

This is the practical V1 version of SeedVault.

V1 principle: Recovery is part of the architecture, not an ops patch.

7. Immune Signals Layer

The anomaly and trust event subsystem.

Responsibilities: - detect suspicious or abnormal behavior patterns - surface risk signals to Quorum and operators - quarantine or pause runs under defined policies - provide the beginning of a stronger trust model

Important nuance: V1 does not need a grand unified security AI fantasy. It needs a serious event model for anomaly signals and response hooks.

That is enough to make the platform safer and much more robust.

Architectural Shape

The V1 architecture should like this:

System model

What this means in practice

Every important system action should be: - represented in state - emitted as an event - inspectable in Loom - governable by Quorum when needed - recoverable through the seed layer

That gives us a platform with real bones instead of a bundle of automation tricks.

This is the technical bias I recommend for V1.

1. Event Backbone

Use an internal event model as a first-class primitive.

Events should cover things like: - workflow created - run started - task assigned - task completed - task failed - threshold requested - threshold met - threshold denied - anomaly detected - recovery checkpoint created - replay triggered - health state changed

Why: - event streams make the system inspectable - they support retries and replay - they make audits and debugging possible - they create a clean boundary between runtime and UI

If Cambium is supposed to mature into something robust, this backbone is non-negotiable.

2. Stateful Run Model

Each workflow run should have durable state.

At minimum, V1 runs should track: - workflow definition version - current status - node/task states - inputs and outputs - decision checkpoints - recovery checkpoints - anomaly flags - timestamps and operator interventions

Why: Without durable run state, recovery and serious observability fall apart.

3. Graph-Based Workflow Model

Do not model workflows as only linear sequences.

V1 should support: - branching - joins - retries - fallback edges - conditional routing - pause/wait states - approval gates

Why: OpenClaw and Paperclip-level robustness comes from handling reality, and reality is branching, interruptible, and messy.

4. Clear Service Boundaries

Even if we ship fast, the conceptual boundaries should be clean:

These can start in a modular monolith if speed matters. I actually think that is the right move early on.

But the boundaries should be explicit so we can split services later without surgery.

5. Modular Monolith First

My strong recommendation for V1:

Build Cambium as a modular monolith, not premature microservices.

Why: - faster iteration - easier debugging - simpler local development - fewer distributed-systems headaches before the product is real - cleaner path to changing core abstractions quickly

But inside that monolith, enforce: - module boundaries - typed contracts - event interfaces - domain separation

That is how you get speed now without painting yourself into a corner later.

6. Auditability by Default

Every sensitive action and major workflow transition should leave an audit trail.

Audit records should include: - who or what initiated the action - what policy applied - what inputs mattered - whether quorum was required - what decision was made - what happened next

Why: If autonomous systems touch real work, this becomes mandatory fast.

7. Recovery-First Execution

Hypha should not just run tasks. It should run tasks in a way that assumes: - interruptions happen - models fail - tools timeout - humans intervene - policies change midstream

That means every meaningful execution path needs: - checkpoint opportunities - resumable state - replay or rollback support - explicit terminal failure handling

This is one of the biggest differences between a toy orchestrator and a platform.

Proposed V1 Capability Map

In scope for V1

A. Workflow runtime

B. Operator surface

C. Governance

D. Health and resilience

E. Trust and anomaly response

Explicitly Out of Scope for V1

Do not try to fully build these yet: - internal credit routing - universal energy accounting economy - full symbiosis marketplace - swarm opportunity discovery market - embedded financial organ layer - elaborate multi-tenant ecosystems with external agent marketplaces

Those may be real later. They are not required to prove the platform now.

If we try to stuff V1 with all of that, we will create a mythology project instead of a product.

Suggested Repository / Package Shape

If we want this to grow well, the codebase should reflect the architecture.

Example structure:

cambium/
 apps/
 loom/ # operator UI / workflow surface
 packages/
 core/ # shared contracts, types, identity model
 hypha/ # orchestration engine
 quorum/ # threshold policies and governed actions
 health/ # metrics, stress logic, homeostasis
 seed/ # checkpoints, replay, rollback
 immune/ # anomaly signals and trust events
 workflows/ # workflow graph definitions and compiler/loader
 events/ # event schemas and bus abstractions
 audit/ # audit records and query helpers
 integrations/ # tools, model providers, external connectors
 infrastructure/
 migrations/
 dev/
 deployment/
 docs/
 architecture/
 prd/

This is not sacred, but the principle is: separate the engine, governance, resilience, and UI from day one.

Data Model Bias

V1 should preserve a few central records cleanly:

WorkflowDefinition

WorkflowRun

TaskExecution

DecisionRecord

CheckpointRecord

AnomalyEvent

We do not need the perfect ontology on day one. We do need durable objects that match the platform’s responsibilities.

UX Principles for Loom

If Loom is going to matter, it should help people answer these questions fast: - What is running right now? - What failed? - What is blocked on approval? - What path did the system take? - Why did it choose that path? - What changed after the anomaly? - Can I replay, resume, or roll back this run?

That means Loom V1 should prioritize: - clarity over visual theater - run inspection over pretty diagrams - decision visibility over generic dashboards - intervention controls where they matter most

Paperclip-grade seriousness requires an interface that helps operators think, not just admire gradients.

Robustness Standard

You specifically said you want this organized to become something as robust as OpenClaw and Paperclip.

That means V1 should be judged against these standards:

1. Durable state

No important run exists only in memory.

2. Replayability

Failures can be diagnosed and meaningful parts can be resumed or replayed.

3. Auditability

Sensitive actions and decisions are inspectable later.

4. Policy boundaries

The system knows when it is allowed to act and when it must escalate.

5. Operational visibility

An operator can tell what happened without reverse-engineering chaos from logs.

6. Modularity

Core subsystems can evolve without rewriting the entire platform.

7. Controlled autonomy

The system can act without becoming an opaque gremlin factory.

If V1 does not satisfy those, it may still demo well, but it will not age well.

Strategic Build Recommendation

This is the sequence I recommend.

Phase 1: Core platform skeleton

Phase 2: Governed execution

Phase 3: Resilience

Phase 4: Immune signals

That path gets us to a serious V1 without pretending we have to solve the entire ecology on day one.

Final V1 Statement

Cambium V1 should be built as a modular, event-driven orchestration platform with a graph-based runtime, operator-grade workflow visibility, threshold-governed actions, recovery-native execution, and first-class system health.

In simpler terms:

That is a credible V1. It is differentiated enough to matter. And it is structurally sound enough to grow into something real instead of collapsing under its own metaphor.