{"id":50294739,"url":"https://github.com/chrisrobison/mindgraph","last_synced_at":"2026-05-28T08:04:01.341Z","repository":{"id":348787769,"uuid":"1199441232","full_name":"chrisrobison/mindgraph","owner":"chrisrobison","description":"Framework-free, browser-native visual graph workbench for modeling and running AI workflows with Web Components and a lightweight event architecture.","archived":false,"fork":false,"pushed_at":"2026-05-22T22:40:50.000Z","size":483,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T00:25:21.052Z","etag":null,"topics":["ai-workflows","browser-native","event-driven","graph-editor","javascript","web-components"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chrisrobison.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-02T10:55:49.000Z","updated_at":"2026-04-10T09:05:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/chrisrobison/mindgraph","commit_stats":null,"previous_names":["chrisrobison/mindgraph"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/chrisrobison/mindgraph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrisrobison%2Fmindgraph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrisrobison%2Fmindgraph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrisrobison%2Fmindgraph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrisrobison%2Fmindgraph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chrisrobison","download_url":"https://codeload.github.com/chrisrobison/mindgraph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrisrobison%2Fmindgraph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33599494,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-workflows","browser-native","event-driven","graph-editor","javascript","web-components"],"created_at":"2026-05-28T08:03:59.295Z","updated_at":"2026-05-28T08:04:01.330Z","avatar_url":"https://github.com/chrisrobison.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MindGraph AI\n\nMindGraph AI is a browser-native, framework-free graph workbench for operational AI workflows.\n\nIt intentionally keeps:\n- custom elements (Web Components)\n- plain ES modules\n- PAN event bus\n- `graph-store` as the canonical graph document owner\n- `ui-store` for UI-only state\n- `persistence-store` for autosave/restore\n\nRoadmap: [ROADMAP.md](/Users/cdr/Projects/mindgraph/ROADMAP.md)\n\n## Run Locally\n\nUse any static HTTP server (do not open with `file://`).\n\n```bash\ncd /Users/cdr/Projects/mindgraph\npython3 -m http.server 4173\n```\n\nOpen [http://127.0.0.1:4173](http://127.0.0.1:4173).\n\n### Run Provider Proxy (OpenAI / Claude / Gemini)\n\nIn a second terminal:\n\n```bash\ncd /Users/cdr/Projects/mindgraph\nnode server/provider-proxy-server.mjs\n```\n\nProxy defaults:\n- HTTP health: `http://127.0.0.1:8787/api/mindgraph/health`\n- Runtime HTTP endpoint: `http://127.0.0.1:8787/api/mindgraph/runtime`\n- Runtime WebSocket endpoint: `ws://127.0.0.1:8787/api/mindgraph/runtime/ws`\n- Tenancy mode: `local` (default bootstrap tenant/domain is `localhost`)\n- Control DB: `./data/mindgraph-control.sqlite` (default)\n\nThen in the app:\n1. Set runtime mode to `HTTP Runtime` in the top toolbar.\n2. Set runtime endpoint to `http://127.0.0.1:8787/api/mindgraph/runtime`.\n3. Open `Provider Settings` and configure provider, model, API key, and (optionally) proxy token.\n\n## Architecture\n\n### Ownership and mutation discipline\n\n1. Components publish `*.requested` intent events.\n2. Stores/services validate + execute canonical mutations.\n3. `graph-store` remains the source of truth for graph state.\n4. Components render from store snapshots and result events.\n\nNo component directly mutates shared graph state.\n\n### Primary modules\n\n- `js/store/graph-store.js`: canonical graph mutations + selection + undo/redo + metadata updates\n- `js/store/ui-store.js`: UI-only runtime/feed state (`activity`, `queue`, `history`, `traces`)\n- `js/store/persistence-store.js`: autosave/restore\n- `js/core/graph-document.js`: normalize + validate graph docs\n- `js/core/graph-migrations.js`: schema versioning + ordered graph document migrations\n- `js/core/graph-semantics.js`: node/edge contracts and semantic rules\n- `js/runtime/execution-planner.js`: readiness, order, cycles, stale detection\n- `js/runtime/runtime-service.js`: request-driven runtime orchestration, retries, cancellation, propagation\n- `js/runtime/mock-agent-runtime.js`: planner-aware local runtime adapter\n- `js/runtime/http-agent-runtime.js`: external runtime adapter (WebSocket first, HTTP fallback)\n- `js/runtime/runtime-audit-store.js`: persists planner snapshots/run traces into graph metadata\n- `server/provider-proxy-server.mjs`: hosted-capable provider proxy with tenant host/domain resolution (HTTP + WS)\n- `server/tenancy/*`: control-plane tenant registry, pluggable DB adapter, and host-based tenant resolver\n\n## Graph Semantics (Implemented)\n\nFull design note: [docs/graph-semantics.md](/Users/cdr/Projects/mindgraph/docs/graph-semantics.md)\nProvider proxy note: [docs/provider-proxy.md](/Users/cdr/Projects/mindgraph/docs/provider-proxy.md)\n\n### Node roles\n\n- `note`: reference/context only\n- `data`: structured source/sink node (non-runnable)\n- `transformer`: runnable deterministic transform\n- `agent`: runnable reasoning/orchestration\n- `view`: runnable presentation/render\n- `action`: runnable side-effect/publish\n\nNode contracts are normalized via `normalizeNodeDataWithContract` and validated via `validateNodeContract`, including:\n- required fields by node type\n- `inputPorts` / `outputPorts`\n- role-aware port presets (with schema defaults) for contract authoring\n- runtime policy defaults (`maxAttempts`, `retryBackoffMs`, `retryBackoffFactor`, `failFast`)\n\n### Edge roles\n\n- Execution edges: `depends_on`, `triggers`\n- Data/context edges: `feeds_data`, `reads_from`, `writes_to`, `transforms`\n- Hierarchy edges: `parent_of`\n- Informational edges: `informs`, `critiques`, `reports_to`, `references`\n\nEdge contracts are normalized and validated at create/update time:\n- `sourcePort`\n- `targetPort`\n- `payloadType`\n- `required`\n- `schema`\n- schema presets (`text`, `object`, `array`, `dataset`, `prompt`, `report`, `command_result`) with manual override support\n\n## Planner and Execution Model\n\nPlanner answers:\n- runnable vs blocked\n- upstream dependencies\n- missing input payloads\n- missing required ports\n- cycle detection\n- subtree scope by hierarchy\n- stale dependency rerun hints\n\nRuntime service behavior:\n- handles `runtime.*.requested` events (`run node`, `run subtree`, `run all`, `cancel`)\n- applies retry/backoff from node runtime policy\n- supports cancellation across adapters\n- propagates upstream failures during batch plans\n- supports fail-fast per node policy\n- injects provider/model/key settings from UI into HTTP runtime requests\n\n### Runtime modes\n\n- `mock`: in-browser execution against planner state\n- `http`: delegates to external runtime endpoint over WebSocket (fallback HTTP)\n\nThe toolbar controls mode and HTTP endpoint. Mode/endpoint are persisted in local storage.\nProvider settings (provider/model/api key/system prompt) are available in bottom panel `Runtime Settings`.\n\n## UI Clarity Improvements\n\n- Connect drag now opens an edge-type chooser with semantic presets and validity hints.\n- Edge inspector shows semantic category/effects, schema preset controls, and clearer compatibility errors.\n- Node overview includes role-aware input/output port preset editing plus manual schema JSON editing.\n- Toolbar includes a demo template picker/import action with scenario descriptions.\n- Planner readiness is surfaced in node/inspector views.\n- Bottom panel `Timeline` includes all/current/selected-node filters plus optional group-by-node event rendering.\n- Bottom panel `Planner Diff` compares any two saved planner snapshots (status, blockers, dependencies, order, stale/rerun hints).\n- Bottom panel now includes `Run Traces` alongside activity/history/errors.\n- Bottom panel includes a `Runtime Settings` control panel for provider/model/API key configuration.\n- Running items are visually highlighted with status animations across task queue/history/timeline and node status badges (with `prefers-reduced-motion` fallbacks).\n- Left tool-palette SVG icons now inherit button color via inline `currentColor`, so icons automatically match light/dark themes.\n\n## End-to-End Workflow (Seeded)\n\nSeed graph demonstrates a real path:\n\n`data_market_data` -\u003e `transformer_signal_normalizer` -\u003e `agent_strategy_synthesizer` -\u003e `view_campaign_brief` -\u003e `action_publish_brief`\n\nWith additional semantics:\n- `reads_from` for config ingestion\n- `depends_on` for execution ordering\n- `parent_of` for subtree scope\n- `references` for non-executable context links\n\n## Demo Templates\n\nUse the top toolbar `Import Template` picker to load these sample graphs:\n\n1. `Research -\u003e Brief -\u003e Publish`\n   - Flow: market research ingest -\u003e synthesis transform -\u003e brief drafting -\u003e packet render -\u003e CMS publish.\n   - Demo value: explicit execution + data contracts (`feeds_data`, `reads_from`, `depends_on`) and a clean end-to-end publish path.\n2. `Ingest -\u003e Normalize -\u003e Analyze -\u003e Dashboard`\n   - Flow: telemetry ingest -\u003e schema normalization -\u003e KPI analysis -\u003e dashboard rendering.\n   - Demo value: showcases semantic `transforms` + `reads_from` edges and planner-visible staging from data prep to presentation.\n3. `Human Approval Gate`\n   - Flow: draft recommendation -\u003e review packet -\u003e approval request -\u003e gated release decision -\u003e publish.\n   - Demo value: intentionally leaves approval-state data empty so planner clearly shows `blocked` vs `ready` nodes and missing payload diagnostics.\n\n## Audit and Trace Persistence\n\nRuntime audit data is persisted in `document.metadata.executionAudit`:\n- `plannerSnapshots` (capped)\n- `runTraces` (capped)\n\nThis gives replay/debug context directly in the saved graph document.\n\n## Graph Schema Versioning\n\nGraph documents include a top-level integer `schemaVersion` and are migrated before normalization/validation.\n\n- Current value is `CURRENT_GRAPH_SCHEMA_VERSION` in `js/core/graph-migrations.js`.\n- Migration entrypoint is `migrateGraphDocument(...)`, called by `graphStore.load(...)`.\n- `persistence-store` restore and toolbar JSON load both flow through `graphStore.load(...)`, so migration happens automatically on import/restore.\n- Future schema versions fail safely with a readable migration error object (`code`, `message`, `sourceVersion`, `targetVersion`, `details`).\n\nMigration authoring details: [docs/graph-schema-migrations.md](/Users/cdr/Projects/mindgraph/docs/graph-schema-migrations.md)\n\n## Current Limitations\n\n- Port contracts are lightweight and do not enforce full JSON Schema semantics.\n- Proxy server currently supports single-node execution requests (`run-node`) and WebSocket structured runtime stream events (plan orchestration remains client-side).\n- API keys are session-only by default; persistence requires explicit opt-in (`Remember Keys On This Device`).\n- Planner uses in-memory recomputation each render/request (no incremental diff engine yet).\n- Batch execution parallelism is intentionally bounded by a configurable concurrency limit (`metadata.runtimePolicy.batchConcurrencyLimit` or `runtimePolicy.concurrencyLimit` override).\n\n## Suggested Next Steps\n\n1. Add stronger contract validation (optional JSON Schema validation mode, linting, and actionable fix hints).\n2. Add durable run-session continuity (explicit persisted session objects, resume markers, and replay controls).\n3. Add timeline analytics and export (event search/filter presets, branch-level metrics, JSON/CSV export).\n4. Add deeper runtime observability (per-stage timing, token/latency/cost summaries where provider data is available).\n5. Add automated UI regression coverage for theme-aware icons and runtime-status motion states.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrisrobison%2Fmindgraph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchrisrobison%2Fmindgraph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrisrobison%2Fmindgraph/lists"}