https://github.com/chrisrobison/mindgraph
Framework-free, browser-native visual graph workbench for modeling and running AI workflows with Web Components and a lightweight event architecture.
https://github.com/chrisrobison/mindgraph
ai-workflows browser-native event-driven graph-editor javascript web-components
Last synced: 16 days ago
JSON representation
Framework-free, browser-native visual graph workbench for modeling and running AI workflows with Web Components and a lightweight event architecture.
- Host: GitHub
- URL: https://github.com/chrisrobison/mindgraph
- Owner: chrisrobison
- Created: 2026-04-02T10:55:49.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-22T22:40:50.000Z (21 days ago)
- Last Synced: 2026-05-23T00:25:21.052Z (21 days ago)
- Topics: ai-workflows, browser-native, event-driven, graph-editor, javascript, web-components
- Language: JavaScript
- Size: 472 KB
- Stars: 2
- Watchers: 0
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# MindGraph AI
MindGraph AI is a browser-native, framework-free graph workbench for operational AI workflows.
It intentionally keeps:
- custom elements (Web Components)
- plain ES modules
- PAN event bus
- `graph-store` as the canonical graph document owner
- `ui-store` for UI-only state
- `persistence-store` for autosave/restore
Roadmap: [ROADMAP.md](/Users/cdr/Projects/mindgraph/ROADMAP.md)
## Run Locally
Use any static HTTP server (do not open with `file://`).
```bash
cd /Users/cdr/Projects/mindgraph
python3 -m http.server 4173
```
Open [http://127.0.0.1:4173](http://127.0.0.1:4173).
### Run Provider Proxy (OpenAI / Claude / Gemini)
In a second terminal:
```bash
cd /Users/cdr/Projects/mindgraph
node server/provider-proxy-server.mjs
```
Proxy defaults:
- HTTP health: `http://127.0.0.1:8787/api/mindgraph/health`
- Runtime HTTP endpoint: `http://127.0.0.1:8787/api/mindgraph/runtime`
- Runtime WebSocket endpoint: `ws://127.0.0.1:8787/api/mindgraph/runtime/ws`
- Tenancy mode: `local` (default bootstrap tenant/domain is `localhost`)
- Control DB: `./data/mindgraph-control.sqlite` (default)
Then in the app:
1. Set runtime mode to `HTTP Runtime` in the top toolbar.
2. Set runtime endpoint to `http://127.0.0.1:8787/api/mindgraph/runtime`.
3. Open `Provider Settings` and configure provider, model, API key, and (optionally) proxy token.
## Architecture
### Ownership and mutation discipline
1. Components publish `*.requested` intent events.
2. Stores/services validate + execute canonical mutations.
3. `graph-store` remains the source of truth for graph state.
4. Components render from store snapshots and result events.
No component directly mutates shared graph state.
### Primary modules
- `js/store/graph-store.js`: canonical graph mutations + selection + undo/redo + metadata updates
- `js/store/ui-store.js`: UI-only runtime/feed state (`activity`, `queue`, `history`, `traces`)
- `js/store/persistence-store.js`: autosave/restore
- `js/core/graph-document.js`: normalize + validate graph docs
- `js/core/graph-migrations.js`: schema versioning + ordered graph document migrations
- `js/core/graph-semantics.js`: node/edge contracts and semantic rules
- `js/runtime/execution-planner.js`: readiness, order, cycles, stale detection
- `js/runtime/runtime-service.js`: request-driven runtime orchestration, retries, cancellation, propagation
- `js/runtime/mock-agent-runtime.js`: planner-aware local runtime adapter
- `js/runtime/http-agent-runtime.js`: external runtime adapter (WebSocket first, HTTP fallback)
- `js/runtime/runtime-audit-store.js`: persists planner snapshots/run traces into graph metadata
- `server/provider-proxy-server.mjs`: hosted-capable provider proxy with tenant host/domain resolution (HTTP + WS)
- `server/tenancy/*`: control-plane tenant registry, pluggable DB adapter, and host-based tenant resolver
## Graph Semantics (Implemented)
Full design note: [docs/graph-semantics.md](/Users/cdr/Projects/mindgraph/docs/graph-semantics.md)
Provider proxy note: [docs/provider-proxy.md](/Users/cdr/Projects/mindgraph/docs/provider-proxy.md)
### Node roles
- `note`: reference/context only
- `data`: structured source/sink node (non-runnable)
- `transformer`: runnable deterministic transform
- `agent`: runnable reasoning/orchestration
- `view`: runnable presentation/render
- `action`: runnable side-effect/publish
Node contracts are normalized via `normalizeNodeDataWithContract` and validated via `validateNodeContract`, including:
- required fields by node type
- `inputPorts` / `outputPorts`
- role-aware port presets (with schema defaults) for contract authoring
- runtime policy defaults (`maxAttempts`, `retryBackoffMs`, `retryBackoffFactor`, `failFast`)
### Edge roles
- Execution edges: `depends_on`, `triggers`
- Data/context edges: `feeds_data`, `reads_from`, `writes_to`, `transforms`
- Hierarchy edges: `parent_of`
- Informational edges: `informs`, `critiques`, `reports_to`, `references`
Edge contracts are normalized and validated at create/update time:
- `sourcePort`
- `targetPort`
- `payloadType`
- `required`
- `schema`
- schema presets (`text`, `object`, `array`, `dataset`, `prompt`, `report`, `command_result`) with manual override support
## Planner and Execution Model
Planner answers:
- runnable vs blocked
- upstream dependencies
- missing input payloads
- missing required ports
- cycle detection
- subtree scope by hierarchy
- stale dependency rerun hints
Runtime service behavior:
- handles `runtime.*.requested` events (`run node`, `run subtree`, `run all`, `cancel`)
- applies retry/backoff from node runtime policy
- supports cancellation across adapters
- propagates upstream failures during batch plans
- supports fail-fast per node policy
- injects provider/model/key settings from UI into HTTP runtime requests
### Runtime modes
- `mock`: in-browser execution against planner state
- `http`: delegates to external runtime endpoint over WebSocket (fallback HTTP)
The toolbar controls mode and HTTP endpoint. Mode/endpoint are persisted in local storage.
Provider settings (provider/model/api key/system prompt) are available in bottom panel `Runtime Settings`.
## UI Clarity Improvements
- Connect drag now opens an edge-type chooser with semantic presets and validity hints.
- Edge inspector shows semantic category/effects, schema preset controls, and clearer compatibility errors.
- Node overview includes role-aware input/output port preset editing plus manual schema JSON editing.
- Toolbar includes a demo template picker/import action with scenario descriptions.
- Planner readiness is surfaced in node/inspector views.
- Bottom panel `Timeline` includes all/current/selected-node filters plus optional group-by-node event rendering.
- Bottom panel `Planner Diff` compares any two saved planner snapshots (status, blockers, dependencies, order, stale/rerun hints).
- Bottom panel now includes `Run Traces` alongside activity/history/errors.
- Bottom panel includes a `Runtime Settings` control panel for provider/model/API key configuration.
- Running items are visually highlighted with status animations across task queue/history/timeline and node status badges (with `prefers-reduced-motion` fallbacks).
- Left tool-palette SVG icons now inherit button color via inline `currentColor`, so icons automatically match light/dark themes.
## End-to-End Workflow (Seeded)
Seed graph demonstrates a real path:
`data_market_data` -> `transformer_signal_normalizer` -> `agent_strategy_synthesizer` -> `view_campaign_brief` -> `action_publish_brief`
With additional semantics:
- `reads_from` for config ingestion
- `depends_on` for execution ordering
- `parent_of` for subtree scope
- `references` for non-executable context links
## Demo Templates
Use the top toolbar `Import Template` picker to load these sample graphs:
1. `Research -> Brief -> Publish`
- Flow: market research ingest -> synthesis transform -> brief drafting -> packet render -> CMS publish.
- Demo value: explicit execution + data contracts (`feeds_data`, `reads_from`, `depends_on`) and a clean end-to-end publish path.
2. `Ingest -> Normalize -> Analyze -> Dashboard`
- Flow: telemetry ingest -> schema normalization -> KPI analysis -> dashboard rendering.
- Demo value: showcases semantic `transforms` + `reads_from` edges and planner-visible staging from data prep to presentation.
3. `Human Approval Gate`
- Flow: draft recommendation -> review packet -> approval request -> gated release decision -> publish.
- Demo value: intentionally leaves approval-state data empty so planner clearly shows `blocked` vs `ready` nodes and missing payload diagnostics.
## Audit and Trace Persistence
Runtime audit data is persisted in `document.metadata.executionAudit`:
- `plannerSnapshots` (capped)
- `runTraces` (capped)
This gives replay/debug context directly in the saved graph document.
## Graph Schema Versioning
Graph documents include a top-level integer `schemaVersion` and are migrated before normalization/validation.
- Current value is `CURRENT_GRAPH_SCHEMA_VERSION` in `js/core/graph-migrations.js`.
- Migration entrypoint is `migrateGraphDocument(...)`, called by `graphStore.load(...)`.
- `persistence-store` restore and toolbar JSON load both flow through `graphStore.load(...)`, so migration happens automatically on import/restore.
- Future schema versions fail safely with a readable migration error object (`code`, `message`, `sourceVersion`, `targetVersion`, `details`).
Migration authoring details: [docs/graph-schema-migrations.md](/Users/cdr/Projects/mindgraph/docs/graph-schema-migrations.md)
## Current Limitations
- Port contracts are lightweight and do not enforce full JSON Schema semantics.
- Proxy server currently supports single-node execution requests (`run-node`) and WebSocket structured runtime stream events (plan orchestration remains client-side).
- API keys are session-only by default; persistence requires explicit opt-in (`Remember Keys On This Device`).
- Planner uses in-memory recomputation each render/request (no incremental diff engine yet).
- Batch execution parallelism is intentionally bounded by a configurable concurrency limit (`metadata.runtimePolicy.batchConcurrencyLimit` or `runtimePolicy.concurrencyLimit` override).
## Suggested Next Steps
1. Add stronger contract validation (optional JSON Schema validation mode, linting, and actionable fix hints).
2. Add durable run-session continuity (explicit persisted session objects, resume markers, and replay controls).
3. Add timeline analytics and export (event search/filter presets, branch-level metrics, JSON/CSV export).
4. Add deeper runtime observability (per-stage timing, token/latency/cost summaries where provider data is available).
5. Add automated UI regression coverage for theme-aware icons and runtime-status motion states.