FlowPad package layout

The FlowPad package is at projects/matrix-3/packages/flowpad/. Build outputs go to dist/. The source tree is organised so each concern can be modified without touching unrelated panes.

Directory map

projects/matrix-3/packages/flowpad/
├── matrix.json              # Package manifest (webapp, no headless components)
├── package.json             # @open-matrix/flowpad, devDeps: @open-matrix/core, tsx, vite
├── README.md
├── LICENSE
├── build.mjs                # Vite build wrapper that writes matrix-artifact.json
├── vite.config.ts           # Vite config (browser bundle)
├── dist-path.js             # Exports __dirname so other packages can find the dist
├── tsconfig.json
└── src/
    ├── index.html           # Page entry; bootstraps <flowpad-app>
    ├── index.ts             # Re-exports + customElements.define for every shell
    ├── FlowpadApp.ts        # MatrixActor + re-export of FlowpadAppShell
    ├── components/
    │   ├── FlowpadControl.ts    # Header strip / labelled frame
    │   ├── PipelineEditor.ts    # Code editor (Flow / LISP)
    │   ├── ResultsPanel.ts      # Result manager (children = result viewers)
    │   ├── ExecutionStatus.ts   # Status bar + topology tag
    │   ├── TransportLog.ts      # Bus-message log (dock tab)
    │   ├── ActorInspector.ts    # Inspector pane
    │   ├── addressing.ts        # resolveMountAddress() helper
    │   ├── index.ts             # Component barrel
    │   └── sidebar/
    │       ├── FlowpadSidebar.ts        # Composes the three sidebar children
    │       ├── FlowpadActorTree.ts      # Hierarchical actor tree
    │       ├── FlowpadPackageBrowser.ts # Installed packages
    │       ├── FlowpadExampleList.ts    # Examples for selected actor
    │       ├── types.ts                 # IDiscoverTreeNode / ICatalogPackageEntry
    │       └── index.ts
    ├── shell/
    │   ├── FlowpadAppShell.ts   # The DOM owner that wraps FlowpadApp
    │   ├── projectCatalog.ts    # Loader for src/projects/*/manifest.json roots
    │   ├── transport-indicator.ts
    │   └── index.ts
    ├── dsl/
    │   ├── parser.ts            # parseFlowDSL — string → ParsedFlow
    │   ├── examples.ts          # ~85 named DSL examples
    │   ├── query-catalog.ts     # CLI-addressable query catalog
    │   ├── validateExamples.ts  # Validation harness for DSL_EXAMPLES
    │   └── index.ts
    ├── runtime/
    │   └── queryPipeline.ts     # CanonicalIR + compileSourceToCanonicalIR + executeCanonicalIR
    ├── services/
    │   ├── MockDbService.ts     # In-page mock database
    │   ├── FlowRunnerService.ts # Server-style runner used by onRunFlow
    │   ├── SecurityRealmService.ts
    │   ├── TopicClaimService.ts
    │   ├── NetworkPatterns.ts   # Real-world LISP examples for distributed systems
    │   ├── ControlFactory.ts
    │   ├── RealmController.ts
    │   └── index.ts             # Re-exports + LISP/Scheme/Bootstrap from @open-matrix/core/lisp
    ├── projects/
    │   ├── database/{manifest.json, examples/}
    │   ├── federation/{manifest.json, examples/}
    │   ├── lisp/{manifest.json, examples/}
    │   ├── security/{manifest.json, examples/}
    │   ├── serialization/{manifest.json, examples/}
    │   └── vlm/{manifest.json, examples/}
    ├── template/
    │   └── flowpad.template.ts  # The page HTML
    ├── styles/
    │   └── flowpad.styles.ts    # All FlowPad-specific CSS
    ├── config/
    │   └── defaults.ts          # FLOWPAD_DEFAULTS
    └── vlm/
        ├── VLMVisualization.ts  # Visualisation shell for VLM execution
        └── index.ts

Module-level responsibilities

Top-level

• matrix.json — webapp manifest. Empty components array (browser-only package). webapp.appName=flowpad, displayName=FlowPad, navOrder=40, shells=["platform","edge"].
• build.mjs — runs Vite build, then writeArtifactManifest to emit dist/matrix-artifact.json capturing the gitSha and the source roots used. Source roots include ../core/src, ../director/src/shims, ../federation/src so the artifact is reproducible from a known commit.
• dist-path.js — exposes __dirname/dist so other packages can locate FlowPad's static assets (gateway uses this).

Inside src/

• index.ts — registers every custom element name with customElements.define. The names are stable: flowpad-app, flowpad-control, flowpad-sidebar, pipeline-editor, transport-log, execution-status, results-panel, flowpad-actor-tree, flowpad-example-list, flowpad-package-browser, mx-split, mx-dock, mx-theme, vlm-visualization, data-viewer, tree-viewer, table-viewer, error-viewer.
• FlowpadApp.ts — the headless actor. Owns example list, selected example, target mount, per-stage data map, and the run loop.
• shell/FlowpadAppShell.ts — the DOM owner. Subscribes to FlowpadApp's events, wires the sidebar, manages the page-topic tag and the transport indicator, persists splitter positions.

components/

Each .ts file in components/ exports two classes: a MatrixActor subclass (suffix-less) and a MatrixActorHtmlElement subclass (suffix Shell). Pattern B everywhere.

dsl/ and runtime/

• dsl/parser.ts parses FlowDSL source into a ParsedFlow (a list of stage descriptors).
• runtime/queryPipeline.ts is the canonical compile + execute pipeline. Both onRunFromCode and onRunFlow ultimately go through here for non-FlowBuilder paths.

services/

Each service is a small MatrixActor that becomes a child of the FlowPad mount at bootstrap:

File	Mount id	What it offers
MockDbService.ts	db	Query op against three canned tables (products, users, orders)
FlowRunnerService.ts	flow-runner	RunFlow op for the FlowBuilder execution path
SecurityRealmService.ts	security-realm	Capability-mint/attenuate/revoke/validate ops
TopicClaimService.ts	topic-claims	Claim/release/delegate/revoke topic prefixes

The LISP/Scheme actors come from @open-matrix/core/lisp (services/index.ts:6-25) — LispEval, SchemeEval, BootstrapNode. FlowPad doesn't reimplement them.

projects/

The six bundled "projects" are loaded at runtime by shell/projectCatalog.ts rather than baked into the bundle. Each one is a directory with a manifest.json and an examples/ folder. manifest.json declares services, views, examples, and dependencies on other project ids. loadProjectCatalog builds a topologically sorted list and validates references.

template/ and styles/

flowpad.template.ts exports a single string with the page layout (see What is FlowPad? for the structure). styles/flowpad.styles.ts exports the matching CSS string. Both are pulled into FlowpadApp as static template = flowpadTemplate and concatenated into the rendered host element.

Build outputs

Running pnpm --filter @open-matrix/flowpad build (or node build.mjs directly) produces:

dist/
├── index.html               # Page entry
├── assets/                  # Hashed JS/CSS bundles
├── projects/                # The six bundled projects, copied as-is
└── matrix-artifact.json     # Reproducibility manifest (gitSha, source roots, entrypoints)

The package's files field in package.json ships dist, dist-path.js, matrix.json, README.md, LICENSE.

See also

• FlowPad components and shells
• Actor integration and IR pipeline
• Package manifest (matrix.json)

Source: projects/matrix-3/packages/flowpad/src/index.ts and projects/matrix-3/packages/flowpad/build.mjs.