UCD.js Docs

Pipeline Server

Architecture notes for @ucdjs/pipeline-server

@ucdjs/pipeline-server is the local pipeline UI and API server for discovering, visualizing, and running pipelines.

Role

  • Hosts the interactive pipeline UI and the server API behind it.
  • Resolves pipeline sources, manages workspace state, and persists execution history.
  • Connects loader, executor, graph, tracing, and UI concerns in one package.

Pipeline Loader

The server discovers and loads pipeline definitions through the loader package.

Pipeline Executor

Executions triggered from the UI run through the executor package.

Pipeline Graph

Graph APIs and UI views depend on pipeline graph data.

Pipeline Playground

Development mode defaults to the example pipelines in pipeline-playground.

Mental Model

This package has two halves:

  • server-side H3 app, database, workspace, and live updates
  • client-side UI bundled into the same package

It is effectively the control plane for the pipeline toolchain.

Method Flows

startServer()

setupLiveUpdates()createApp()resolveWorkspace()createDatabase()/runMigrations()startServer()setupLiveUpdates()createApp()resolveWorkspace()createDatabase()/runMigrations()startServer()OperatorstartServer({ sources, workspaceId, workspaceRoot })ensure config dir, create DB, run migrationsresolve workspace ID and root pathensure workspace row + recover stale executionscreate H3 app with sources/db/workspacesetup live update channelsserve API + SPA clientOperator

Server API request

database / pipeline services/api/sources/* routersrequest context injectorcreateApp()database / pipeline services/api/sources/* routersrequest context injectorcreateApp()BrowserGET /api/sources/...attach sources, db, workspaceId to event contextdispatch to overview/pipeline/executions/logs/graph/traces routerresolve requested data or run operationresultJSON responseBrowser

SPA fallback and static asset serving

index.html fallbackserveStatic()H3 appindex.html fallbackserveStatic()H3 appalt[asset exists][SPA route]BrowserGET non-/api routetry serve built client assetJS/CSS/image assetread client/index.htmlHTML shell for frontend routerBrowser

Design Notes

  • Workspace identity is stable and can come from either config or hashed root path.
  • The package treats failed migrations as fatal, which is correct for a control-plane app.
  • Server and client live together because the UI is tightly coupled to the API shape.
  • Development defaults to the pipeline playground so the app is useful immediately.

Testing Use

  • workspace resolution and stale-execution recovery
  • route behavior for sources, graph, executions, logs, and traces
  • migration/bootstrap failures
  • live update lifecycle
  • SPA fallback and static serving

Pipeline Presets

Architecture notes for @ucdjs/pipeline-presets

Overview

Architecture notes for each application in the monorepo

On this page

RoleRelated DocsMental ModelMethod FlowsstartServer()Server API requestSPA fallback and static asset servingDesign NotesTesting Use