@miragon/design Iq

designIQ: Model together. AI at the table.

designIQ is a Git-native workspace where teams model their business and their architecture together, live: processes (BPMN), decisions (DMN), Wardley Maps, Team Topologies, Event Storming boards, Context Maps, Value Chains and plain Markdown, with Mermaid diagrams inside the documents. Every model is a file in your repository; edits sync in real time in the browser and in VS Code, and a release is a pull request, so review and governance stay where engineering already works. AI assistants join through MCP: they read the same live models, explain them, check them and propose changes.

BPMN and DMN are the notations with the deepest tooling: derived process and decision views, decision simulation and test suites, and todos anchored to BPMN elements.

Docs: miragon.github.io/design-iq, with getting started, self-hosting, the MCP integration and the decision records. The site is built from docs/.

• Model live: every model file (.bpmn, .dmn, .owm, .tt, .storm, .cm.json, .vc.json, .yaml, .md) syncs as a shared Y.Text document; the web client and VS Code bind their editors to it. The browser has a visual modeler for BPMN, DMN, Wardley Maps, Team Topologies, Event Storming boards and Context Maps, a rendered view for Markdown documents (links between models open inside designIQ, mermaid fences drawn as diagrams), and a text view for every file. A Mermaid diagram lives as a mermaid fence in a document, next to the prose that explains it, and the validator checks its type. Login authenticates, repos authorize: what you see and edit follows your git write permission.
• Release as PR: one click cuts a branch from origin/<default>, pushes and opens the PR. The PR is bot-authored, with you as the commit author, so you can approve your own release. Merge = approval: governance stays at the git provider (CODEOWNERS / branch protection), not in the tool.
• AI joins in: agents read, check and edit the live models of every notation through the Live Host's own /mcp endpoint, and people who have the model open see them as co-editors; apps-capable chats (claude.ai, Claude Desktop, ChatGPT) open the modelers inline. The read-only MCP server answers from any checkout without a running host, the AI skill layer (capture, import, review, feedback, export …) travels with the content repo, and export-process-skill packages a process with its resolved dependencies as a portable skill for any agent.

Run it in 5 minutes

Evaluation mode is one container with no login (LIVE_AUTH=none: everyone is the local user):

docker run --rm -p 8301:8080 -e LIVE_AUTH=none \
  -e LIVE_PUBLIC_URL=http://localhost:8301 ghcr.io/miragon/designiq-live-host:latest

LIVE_PUBLIC_URL is the URL you actually open: deep links, the MCP resource audience and the same-site check on browser requests derive from it, so a published port other than the container's 8080 has to say so, or the editors never sync.

The server is up at http://localhost:8301 (/healthz answers): the web app, the VS Code extension (designiq.serverUrl = ws://localhost:8301, no sign-in needed) and pnpm --filter @designiq/live-host test:sync all work right away. What it serves is this repo's example content, cloned into the container on the first request and thrown away again with --rm.

Your own models. A content repo is any checkout with a root designiq.yml naming its models folder (the legacy name bpmiq.yml is still read); process-documentation-starter is the template. Name it, and mount a volume so the clone, the live edits and their lineages survive a restart:

docker run -p 8301:8080 -e LIVE_AUTH=none -e LIVE_PUBLIC_URL=http://localhost:8301 \
  -e GITHUB_REPO=<owner>/<repo> -v designiq-data:/data \
  ghcr.io/miragon/designiq-live-host:latest

That clone happens without credentials, so the repo must be public; private repos (and release-as-PR) need the GitHub App. Already have a checkout? Bind-mount it and the host serves it in place, no clone: edits write through to your working tree, git diff shows them, you commit as usual. Nothing is fetched then, so GITHUB_REPO is a pure label (any <owner>/<name>, no GitHub repository behind it):

git clone https://github.com/<owner>/<repo> my-processes   # or your own; needs a root designiq.yml
docker run -p 8301:8080 -e LIVE_AUTH=none -e LIVE_PUBLIC_URL=http://localhost:8301 \
  -e GITHUB_REPO=acme/my-processes -e LIVE_HOST_CONTENT_DIR=/content \
  -v "$PWD/my-processes:/content" -v designiq-data:/data \
  ghcr.io/miragon/designiq-live-host:latest

(A /content without a usable root designiq.yml (or legacy bpmiq.yml) is not a content repo: the host says so at boot and clones GITHUB_REPO instead, which is where a made-up label then fails.)

A real login is your OIDC identity provider plus a GitHub App for authorization. The 15-minute path ships a Keycloak: docs/on-prem/idp-quickstart.md.

From source (Node >= 23.6; TypeScript runs directly via type stripping, no build step):

pnpm install                     # pnpm, never npm/yarn (workspace: protocol)
pnpm --filter @designiq/web build  # the Live Host serves apps/web/dist
LIVE_AUTH=none pnpm live-host    # sync + API + web app on http://localhost:8301, no login
#   with a login: the IdP quickstart (docs/on-prem/idp-quickstart.md) + your GitHub App
#   (one-time vendor step): GITHUB_REPO=<owner>/<repo> pnpm --filter @designiq/live-host create-app

More entry points: pnpm web:dev (web client with hot reload, proxies to the Live Host), pnpm validate (content validation of the example repo, runs in CI on every PR).

Ask the models: open Claude Code in the repo (.mcp.json auto-connects the read-only MCP server, packages/mcp) and ask "Walk me through order-to-cash" or "What should we automate first?".

To reach the live, write-capable endpoint of the running host instead, point a client at /mcp. On a LIVE_AUTH=none host no credential is needed:

claude mcp add --transport http designiq http://localhost:8301/mcp

Claude Desktop's custom-connector dialog expects OAuth, so bridge a no-auth host in claude_desktop_config.json:

{
  "mcpServers": {
    "designiq": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8301/mcp"]
    }
  }
}

Restart Desktop fully (Cmd+Q) afterwards. Against a real deployment the client fetches an OIDC access token itself (Claude Code: claude mcp add --transport http designiq https://<host>/mcp --client-id designiq-mcp --callback-port 8765 with the quickstart realm); see docs/mcp-integration.md.

What's in this repo

This repository is the full self-hostable platform. Miragon also operates a hosted multi-tenant SaaS; its tenant provisioning and billing control plane is not in this repo, but the cell mode it drives is. The code you read here is the code the SaaS runs (ADR 0004).

Self-hosting

Everything the hosted SaaS runs, on your infrastructure: the GHCR image (or your own build), the Compose reference under deploy/, GitHub App setup, reverse-proxy/WebSocket notes, and persistence. Start at docs/on-prem/. Coming from 4.x (before the rename to designIQ)? Read docs/upgrading-to-5.md first.

Extending

The provider layer is a pair of ports (apps/live-host/src/ports/git-provider.ts and apps/live-host/src/ports/connection-source.ts), so a GitLab connector is a new adapters/gitlab/ folder against existing contracts, not a fork. Session issuance has the same seam for SSO. Boundaries are CI-enforced (ADR 0003); guides live in docs/extending/.

Contributing · Security · MIT © Miragon GmbH