Architecture

This page is the map: what VectorStep does, how the codebase is laid out, and — in prose and a diagram — the path a single webhook takes from arrival to a finished, confidence-scored pipeline run.

Project overview

A webhook-triggered, YAML-configured AI pipeline orchestration service built in Python with FastAPI. It receives webhooks from any source (Alertmanager, Grafana, Atlassian, etc.), normalises the payload, resolves a named pipeline config, and executes a multi-step AI pipeline using pluggable agent executor backends.

The service is designed to be:

• Source agnostic — any webhook source is supported via pluggable parsers
• Executor agnostic — AI backends are adapters behind a common interface; steps in the same pipeline can mix executors freely
• Config driven — all pipeline logic lives in YAML files, not code
• Modular — adding a new source parser or executor adapter requires no changes to core logic

Primary use case is observability automation (alert triage, Grafana investigation, bounded remediation) but the design is intentionally general purpose.

Project structure

The engine is organised into a normaliser (source-specific webhook parsers), a resolver (matches a normalised payload to a pipeline), a pipeline runner (executes steps, manages flow control, emits the run log), a set of pluggable executors (OpenClaw, the VectorStep Gateway, sub-pipeline, webhook, human), and the FastAPI app and UI routes that sit on top. The source itself is private — for the directory layout you actually interact with as an operator, see the ~/.vectorstep/ layout the installer creates.

The request flow

A single webhook’s trip through the system touches every major subsystem in order. In plain terms:

1. Webhook — a source (Alertmanager, Grafana, a generic JSON producer, anything) POSTs to /webhook?source=<name>. This is the single entry point regardless of source.
2. Normalise — a source-specific parser (or the generic fallback) converts the raw payload into a NormalisedContext: a standard shape the rest of the system can reason about without caring where the alert came from.
3. Resolve — the resolver matches the normalised context against configured pipelines’ trigger conditions and picks exactly one pipeline to run (subject to dedup/idempotency checks so the same incident doesn’t fire the same pipeline twice).
4. Run steps — the pipeline runner walks the pipeline’s step list in order (or in parallel groups), building up Jinja2 template context as each step completes so later steps can reference earlier outputs.
5. Executors — each step delegates the actual work to a pluggable executor adapter. Some executors call out to an agent backend; others (webhook, notify, human, pipeline) do something else entirely (an HTTP call, a notification, a human approval, a sub-pipeline).
6. Gateway — for steps using the gateway executor, the request goes over WebSocket to the VectorStep Gateway, which owns the full agentic loop.
7. Providers / MCP — the Gateway drives an LLM provider (Anthropic, OpenRouter, Google, Azure OpenAI, Ollama) through as many tool-calling turns as the agent needs, using MCP servers for tool access, and returns one clean, finished result back to VectorStep — no intermediate tool calls or thinking content cross that boundary.

Each step’s result then feeds VectorStep’s confidence machinery (self-report, optional verifier, optional grounding, optional deterministic checks, optional calibration — see Confidence) before the runner decides whether to proceed, escalate, or abort.

 source (Alertmanager, Grafana, generic JSON, ...)
        │
        │  POST /webhook?source=<name>
        ▼
 ┌───────────────┐
 │   Webhook      │  single entry point, all sources
 │   intake       │
 └───────┬───────┘
         ▼
 ┌───────────────┐
 │  Normalise     │  source parser → NormalisedContext
 └───────┬───────┘
         ▼
 ┌───────────────┐
 │  Resolve       │  match context → one pipeline (dedup/idempotency applied)
 └───────┬───────┘
         ▼
 ┌───────────────┐
 │  Run steps     │  pipeline runner walks steps / parallel groups
 └───────┬───────┘
         ▼
 ┌───────────────┐
 │  Executors     │  gateway | openclaw | webhook | notify | human | pipeline
 └───────┬───────┘
         │  (executor: gateway)
         ▼
 ┌───────────────┐
 │   Gateway      │  owns the full agentic loop over WebSocket
 └───────┬───────┘
         ▼
 ┌───────────────┐
 │ Providers/MCP  │  LLM calls + MCP tool execution, multi-turn
 └───────┬───────┘
         │
         ▼
   one clean result back to VectorStep
   (confidence scoring → proceed / escalate / abort)