Miragon 开源 designIQ：Git 原生的业务与架构协同建模工作区

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. 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.

• 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, and a text view for every file. 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 — 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 — one container, 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