Skip to main content
MentatLab docs

Architecture

MentatLab separates workflow design, orchestration, and execution into clear service boundaries.

High-Level Components

  • Frontend (services/frontend)
    • React + ReactFlow Mission Control canvas
    • Panels for console, timeline, and issues
    • Interacts with Gateway over HTTP and run-scoped SSE
  • Gateway (services/gateway-go)
    • API proxy to Orchestrator
    • Transparent SSE proxy and middleware (auth, rate limits, headers)
  • Orchestrator (services/orchestrator-go)
    • DAG scheduler and run lifecycle
    • Agent registry, flow store, run store
    • Execution backends (memory/redis/k8s)
  • Redis
    • Shared run state and messaging backend (when configured)
  • Agents (agents/)
    • External processes or workloads following stdin/stdout NDJSON contract

Request/Run Lifecycle

  1. User creates or updates a flow in Mission Control.
  2. Frontend calls Gateway (/api/v1/flows, /api/v1/runs).
  3. Gateway forwards to Orchestrator and streams events back.
  4. Orchestrator schedules nodes according to DAG dependencies.
  5. Node execution emits events; run status is persisted in runstore.
  6. Frontend updates timeline/console with live run events.

Run Event Transport

GET /api/v1/runs/{id}/events is the canonical live event path. The orchestrator persists/replays events through the runstore and exposes them as Server-Sent Events; the gateway proxies that response without a write deadline so long-running runs remain connected.

The legacy /ws/streams/{id} route is intentionally unavailable and returns HTTP 410 with the corresponding SSE URL. Its Redis Pub/Sub implementation did not consume the Redis Streams written by the orchestrator, so a successful WebSocket upgrade falsely reported connectivity without a producer. WebSocket streaming may only return after an end-to-end bridge is implemented and tested.

Orchestrator Internal Packages

  • internal/api - HTTP handlers and routing
  • internal/scheduler - DAG scheduling/execution
  • internal/registry - agent registration and lookup
  • internal/flowstore - flow persistence
  • internal/runstore - run state persistence
  • internal/k8s - Kubernetes job driver

Execution Modes

  • memory - in-memory state for local dev
  • redis - Redis-backed run state for durable dev/prod
  • k8s - Kubernetes Jobs for agent execution in cluster

Key Design Goals

  • Deterministic DAG execution for repeatable runs
  • Observable run lifecycle (events + metrics)
  • Pluggable execution backends and storage
  • Agent-language agnostic integration via NDJSON
Architecture | MentatLab docs