Vectorbea Engineering

Architecture

A high-level map of how Vectorbea is put together. This is intentionally a simple system The early goal was to ship something durable and correct before reaching for anything more elaborate. We go deeper on each piece in the articles.

Frontend (Next.js)

The visual workflow builder and run inspector. Talks to the API over REST/JSON, renders run timelines and event history.

API (Kotlin)

Owns workflow definitions, run lifecycle, auth (Supabase), budgets and rate limits. Validates and persists to Postgres.

Worker (Kotlin)

Pulls work from Redis Streams consumer groups, executes steps, writes checkpoints and event history, handles retries.

Postgres / Neon

System of record for workflow definitions, runs, checkpoints, and the append-only event history.

Redis Streams

Durable work queue between API and workers. Consumer groups, pending entry lists, and DLQ-style retry handling.

Deploy (Vercel + Railway)

Frontend on Vercel, backend services on Railway. Kept deliberately simple for a small team.

Request flow, in short

  1. 1. A user designs a workflow visually in the frontend and starts a run.
  2. 2. The API validates the definition, creates a run record, and enqueues the first step onto a Redis Stream.
  3. 3. A worker claims the step via a consumer group, executes it, appends events to the run's event history, and writes a checkpoint.
  4. 4. On failure, the step is retried with backoff; on success, the next step is enqueued. Approval gates pause the run until a human acts.
  5. 5. The frontend polls (or subscribes to) the event history to render a live timeline of the run.