AllenNeuralDynamics · dbirman · Jul 1, 2026
diff --git a/.claude/launch.json b/.claude/launch.json
@@ -0,0 +1,17 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "diagram-app",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["--prefix", "diagram-app", "run", "dev", "--", "--port", "5178", "--strictPort"],
+      "port": 5178
+    },
+    {
+      "name": "docs-built",
+      "runtimeExecutable": "python3",
+      "runtimeArgs": ["-m", "http.server", "8012", "--directory", "docs/build/html"],
+      "port": 8012
+    }
+  ]
+}
diff --git a/.gitignore b/.gitignore
@@ -137,3 +137,9 @@ dmypy.json
 
 # MacOs
 **/.DS_Store
+
+# diagram-app (React Flow viewer/editor)
+diagram-app/node_modules/
+diagram-app/dist/
+# Built viewer bundle — regenerated by `npm run build` locally and by the RTD build job.
+docs/source/_static/diagrams-app/
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -11,6 +11,13 @@ build:
   os: ubuntu-24.04
   tools:
     python: "3.13"
+    nodejs: "20"
+  jobs:
+    # Build the interactive React Flow diagram bundle into docs/source/_static/
+    # before Sphinx runs (the bundle is git-ignored and regenerated here).
+    pre_build:
+      - npm --prefix diagram-app ci
+      - npm --prefix diagram-app run build
 
 python:
   install:

diff --git a/diagram-app/README.md b/diagram-app/README.md
@@ -0,0 +1,53 @@
+# diagram-app
+
+Interactive [React Flow](https://reactflow.dev/) diagrams for the AIND software docs,
+plus a **local-only editor**. Diagrams are stored as JSON (the canonical source of
+truth) under `../docs/source/diagrams/`, organised by level
+(`high_level/`, `mid_level/`, `low_level/`, `dynamic_foraging/`).
+
+## Concepts
+
+- **Canonical format** — each diagram is a JSON file (`<level>/<name>.json`) of
+  React Flow `nodes` + `edges`. See [`src/types.ts`](src/types.ts). This replaces the
+  old draw.io `.drawio` / `.drawio.svg` files.
+- **Click-to-expand hierarchy** — a node may declare `data.childDiagram` (another
+  diagram id). In the viewer, clicking that node reveals the child diagram nested
+  *inside* it; a **✕ collapse** button closes it again.
+- **Viewer vs editor** — the read-only viewer ships in the published docs; the editor
+  runs only on your machine and writes changes back to the JSON files.
+
+## Commands
+
+```bash
+npm install            # once
+
+npm run dev            # read-only viewer at http://localhost:5173
+npm run edit           # local EDITOR (edit + save to disk) at /editor.html
+npm run build          # bundle the viewer into ../docs/source/_static/diagrams-app/
+npm run convert        # one-time: import any remaining .drawio files -> JSON
+```
+
+### Editing diagrams
+
+`npm run edit` opens the editor. Load a diagram by id (e.g. `high_level/general_data_flow`),
+then drag nodes, draw edges (drag between nodes), edit the selected node in the
+Inspector (type/label/colour/**child-diagram link**), add nodes, or Delete to remove.
+Click **Save** to write back to `docs/source/diagrams/<id>.json`.
+
+> The save endpoint (`POST /api/diagram/:id`) exists **only** on the dev server, via a
+> plugin in [`vite.config.ts`](vite.config.ts). The production bundle has no write path,
+> so the published docs are strictly read-only.
+
+## How it ships in the docs
+
+1. `npm run build` bundles the viewer to `docs/source/_static/diagrams-app/diagrams.{js,css}`
+   (git-ignored; rebuilt by the Read the Docs `pre_build` job — see `.readthedocs.yaml`).
+2. A `build-finished` hook in `docs/source/conf.py` copies the diagram JSON into
+   `_static/diagrams/` so the viewer can fetch it at runtime.
+3. A page embeds a diagram with a raw-HTML block:
+   ```html
+   <div class="rf-diagram" data-diagram="high_level/general_data_flow" style="height:620px"></div>
+   <script type="module" src="../_static/diagrams-app/diagrams.js"></script>
+   ```
+
+To preview the full docs locally: `npm run build`, then `cd ../docs && make html`.
diff --git a/diagram-app/editor.html b/diagram-app/editor.html
@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AIND Diagram Editor (local)</title>
+    <style>
+      html, body, #editor-root { margin: 0; height: 100%; font-family: system-ui, sans-serif; }
+    </style>
+  </head>
+  <body>
+    <div id="editor-root"></div>
+    <script type="module" src="/src/main-editor.tsx"></script>
+  </body>
+</html>
diff --git a/diagram-app/index.html b/diagram-app/index.html
@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AIND Diagram Viewer (dev)</title>
+    <style>
+      html, body { margin: 0; height: 100%; font-family: system-ui, sans-serif; }
+    </style>
+  </head>
+  <body>
+    <!-- In the docs this div is injected by a raw-HTML block; here it drives the dev server. -->
+    <div
+      class="rf-diagram"
+      data-diagram="high_level/general_data_flow"
+      style="height: 100vh"
+    ></div>
+    <script type="module" src="/src/main-viewer.tsx"></script>
+  </body>
+</html>