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