Every Vellum system is built on the same six-layer architecture. Each layer has a defined contract with its neighbours. Failures stay local. State is recoverable. Behaviour is auditable. This is what makes the difference between a script and a system.
Source-specific collectors handle the messy reality of acquiring data. Each collector is responsible for one source — its authentication, rate limiting, parsing, pagination, and checkpointing.
Collectors return partial-success envelopes, not exceptions. A failed source does not bring down the workflow. The orchestration layer can replay, resume, or skip individual sources without affecting the rest of the system.
Raw content from heterogeneous sources is normalised to a canonical schema. Dates, identifiers, jurisdictions, and entity references are resolved to their normalised forms before any downstream processing.
Normalisation is deterministic. Two runs over the same input produce the same output. This is what makes deduplication, change tracking, and replay possible.
The orchestration layer is the spine of the system. It defines the workflow as a state machine: which stages run, in what order, with what inputs, producing what outputs. State is persisted between stages. Failed stages can be retried, skipped, or replayed.
Orchestration is the boundary between deterministic system behaviour and probabilistic agent behaviour. The orchestration layer never calls a language model. It coordinates the agents that do.
Agents are where judgement happens. Each agent has a single responsibility — classify, extract, draft, score, summarise — and operates against a schema-defined contract. Inputs are typed. Outputs are validated. Behaviour is testable.
The agent layer is the only place where probabilistic behaviour is permitted. Every other layer treats agents as components with defined contracts, not as the system itself.
Human review and approval gates are first-class components of the architecture, not afterthoughts. Workflow stages can be configured to require human sign-off before downstream processing continues. Reviewers see the system context, not raw model output.
For sensitive workflows, multiple gates can be inserted. The audit trail captures every approval, decision, and override.
The delivery layer handles outputs: written briefs, dashboard updates, API responses, notifications, file generation. Delivery is decoupled from processing — the same workflow output can be delivered through multiple channels without changing the upstream architecture.
This separation is what makes the system extensible. New delivery channels can be added without modifying the rest of the architecture.
Three operating principles distinguish Vellum systems from typical AI deployments.
Orchestration, state, routing, and validation are deterministic. Models are used for judgement, not coordination. This is what makes the system reliable.
Every interface between layers is a schema. Inputs and outputs are validated. Behaviour can be tested. Failures stay local.
Every action — collection, processing, decision, approval, delivery — is logged. The audit trail is the record of what the system did and why.