Bridge Graph

Districts, export/import, pipeline runs, and upstream context.

Bridges page graph: district nodes, bridge edges, and pipeline controls
Bridges graph view (web UI)

Concepts

TermMeaning
DistrictContainer for bees, tasks, and settings. Shown as a node on the Bridges page graph.
BridgeEdge between two districts with label, optional dataFlow, and direction.
one_wayUsed for pipeline traversal: forward edges only. Only active one-way bridges participate.
two_wayNot followed by pipeline BFS. For documentation or bidirectional UI semantics.
Start districtWhere a pipeline run begins. Stored in bridgeGraphMeta.startDistrictId.

Export

  1. Open the web app Bridges page (/bridges).
  2. Select at least one district node on the graph.
  3. Click Export selection. A JSON file downloads (bridge-settings-*.json).

Included: format (beebridge.bridge-settings.v1), exportedAt, startDistrictId (if in selection), full district bundles (bees + tasks), and bridges whose endpoints are both in the selection.

Import

  1. On Bridges, click Import and choose a .json file.
  2. The gateway parses and validates the beebridge.bridge-settings.v1 format.

Districts, bees, and tasks are upserted by id. Bridges are applied only when both endpoints exist. dependsOn references to unknown tasks are dropped. Import merges with existing data.

Pipeline Run

From a chosen start district, run all tasks (not done) in every district reachable along active one_way bridges going forward (BFS).

  • API: POST /api/bridge-graph/run with { "districtId": "<id>" }
  • The request blocks until the pipeline finishes.

History

  • GET /api/bridge-pipeline/history — list of past runs (newest first).
  • GET /api/bridge-pipeline/history/:runId — one run record.

Upstream Context & {{bridgeOut:taskId}}

Tasks in upstream districts (one-way edges into the current district) can be listed via:

  • GET /api/bridge-graph/upstream-tasks?districtId=...
  • GET /api/bridge-graph/upstream-overview?districtId=...

Placeholders like {{bridgeOut:<taskId>}} in prompts are resolved using completed outputs from the same pipeline run.

Minimal JSON Shape

{
  "format": "beebridge.bridge-settings.v1",
  "exportedAt": "2026-04-13T12:00:00.000Z",
  "startDistrictId": "district-abc",
  "districts": [
    {
      "district": { "id": "...", "title": "...", "objective": "..." },
      "bees": [ { "id": "...", "name": "...", "systemPrompt": "..." } ],
      "tasks": [ { "id": "...", "title": "...", "dependsOn": [] } ]
    }
  ],
  "bridges": [
    {
      "id": "...",
      "fromDistrictId": "...",
      "toDistrictId": "...",
      "direction": "one_way",
      "status": "active"
    }
  ]
}