Hermes Switch UI — Workflows Architecture

Frontend surfaces, backend engine, and storage — how data flows from library to live run

Legend Frontend (browser) Backend (server) Storage Frontend — src/screens/workflows/ Library panel workflow-library.tsx bundled + user workflows Grid view workflow-grid.tsx card tiles · tag filters Editor workflow-editor.tsx Overview · DAG · YAML Launch wizard launch-wizard.tsx Plan → Route → Schedule → Confirm Run detail panel run-detail-panel.tsx node badges · output · approval use-workflow-events.ts (SSE consumer hook) EventSource → /api/workflow-events • updates run state in Zustand api-client.ts (REST client) listDefinitions · submitRun · getNodeRuns · postApproval Backend — src/server/workflow-engine/ Discovery loader discovery/loader.ts parse YAML · validate nodes Schema validator schemas/dag-node.ts Zod · node type guards DAG executor core/dag-executor.ts topo order · node runners Event emitter emitter/event-emitter.ts node_started/completed/failed Node-runs projector projector/node-runs-projector.ts writes node_runs rows SSE relay /api/workflow-events broadcasts to EventSource API routes (TanStack Start) GET/POST /api/workflow-definitions POST /api/workflow-runs • GET /api/workflow-runs/:id GET /api/workflow-events (SSE) POST /api/workflow-runs/:id/approve GET /api/workflow-runs/:id/node-runs ~/.hermes/ (persistent storage) • workflows/ (YAML files) • workflows-manifest.json • workflow-runs.db • node_runs table • bundled definitions (read-only) • user / project scoped defs GET /api/workflow-definitions POST /api/workflow-runs emit events writes node_runs SSE stream reads YAML defs

Frontend surfaces

  • • Library panel: browse bundled + user workflows
  • • Grid view: card tiles with tag filters
  • • Editor: Overview / DAG / YAML tabs
  • • Launch wizard: 4-step run submission
  • • Run detail panel: live node status + output

Backend engine

  • • Discovery loader: parses YAML, validates nodes
  • • DAG executor: topological execution
  • • Event emitter: node lifecycle events
  • • Node-runs projector: writes DB snapshot
  • • SSE relay: streams events to browser

Storage (~/.hermes/)

  • • workflows/ — user YAML definitions
  • • workflow-runs.db — run + node_runs tables
  • • Bundled definitions shipped with the app
  • • Manifest JSON for fast listing

Hermes Switch UI • workflows architecture