Integrations and extensions

flowss connects to the rest of your toolchain in five ways that work today: living diagrams that stay bound to a source of truth in a public repository, architecture and quality tests that run in your CI through the REST API, embeds and clipboard exports for docs, wikis and chat, the MCP server for AI assistants, and hand-offs to LaTeX and reference managers. This page explains each one end to end, with the exact buttons, the limits and the errors you may see, plus ready-to-paste workflows for GitHub Actions and GitLab CI. It also says plainly which packaged tools (a GitHub Action, two command-line tools and a VS Code extension) exist but are not yet offered for you to install, and what to use instead.

At a glance

Living diagrams

A living diagram is a figure in one of your cloud projects that is bound to its source of truth: the place where the real system is described. flowss reads that source, extracts its structure (services, tables, endpoints, nodes) and compares it with the diagram. When the source moves and the diagram does not, the binding shows Drift and lists exactly what is missing and what is stale. You can then reconcile the diagram with AI in one click, or fix it by hand.

The comparison itself uses no AI. It runs when you press Check, on a schedule, and in your CI.

Before you start

• You must be signed in.
• The diagram must be a figure in a cloud project. A diagram that lives only in your browser cannot be bound. To put your current Studio workspace in the cloud, open the Collaborate panel in the Studio and click Share this workspace as a live project. (The Live dashboard's hint calls this step "Move to cloud".)
• To bind, reconcile or remove a binding you need the editor role (or owner) on the project. Any member of the project can see its bindings, run Check and read the history.
• The source must be public. flowss reads repositories and files anonymously, the same way a visitor without an account would.

The sources you can bind

For a GitHub repository scan, flowss looks for files named like docker-compose*.yml or compose*.yaml anywhere in the repository, tries the shallowest ones first (up to twelve), and uses the first that describes at least two services. A compose file wins over workspaces when both exist; a workspaces monorepo needs at least two packages. Once a binding has been checked, it remembers which file it was based on and reads only that file afterwards, so a new compose file elsewhere in the repository never silently changes what the diagram is compared with. Without @branch, the repository's default branch is scanned.

Where a file may live

File sources are fetched with strict rules:

For a repository scan, compose and package.json files are read through GitHub's API, up to 128 KB each, with a 10-second limit per request. A repository with more than about 100,000 files is too large for a whole-repo scan; bind its compose file by URL instead. Repository scans are anonymous, so GitHub's limit on anonymous requests applies; when it is used up, the check says when it can run again.

Bind a diagram from the Live dashboard

1. Open /live (you need to be signed in). The page header reads Living Diagrams and Diagrams that stay true.
2. Click Bind a diagram (or Bind your first diagram if you have none yet; that empty page also links to CI architecture tests — API docs, the self-describing GET /api/v1/verify).
3. In the dialog Bind a diagram to a source of truth, under 1 · The diagram, choose a project in the first list (Pick a project…) and a figure in the second (Pick a diagram…). Each figure is listed with its engine in brackets.
4. Under 2 · The source of truth, choose one of GitHub repo (selected when the dialog opens), Raw file URL, docker-compose, OpenAPI spec or SQL schema. A one-line hint below the buttons explains the choice.
5. Type the repository or the URL in the field. The placeholder shows the expected shape, for example owner/repo or owner/repo@branch.
6. Click Bind & run first check (it stays disabled until a diagram is picked and the field is filled). You see Diagram bound — first check recorded, and the binding appears as a card with its first verdict.

Cancel closes the dialog without binding. A figure can have one binding: binding it again replaces the source. The figure's engine is recorded with the binding when you bind it.

Note: The Diagram bound — first check recorded message appears even when that first check could not run (for example the file could not be fetched). In that case the card shows Error; open Runs to read why, fix the source and press Check.

Bind a diagram from the Studio

The Studio's Collaborate panel has a Living source section for the figure that is open, when you are working in a cloud project.

1. Open the figure in the Studio, inside its cloud project.
2. Open Collaborate and find Living source.
3. Paste a file URL into the field (placeholder: Bind this diagram to a source URL (GitHub raw/blob…) and keep it in sync).
4. Press Enter or click Bind & sync.

Note: Bind & sync binds a raw file URL (compared in the figure's current engine) and then immediately runs a sync, which reconciles with AI if the diagram differs from the source (see the costs below). The sync needs AI even when it turns out to cost nothing, so on Free, or without enough points, the binding is created but the sync is refused with a message about AI points. To bind without AI, or to bind a repository, compose file, spec or schema, use the Live dashboard, whose first step is an AI-free check.

Once bound, the section shows the host of the source (or just source for a repository binding made on the Live dashboard), checked … with how long ago (or not checked yet), · error if the last attempt failed, a Sync now button (it reads Syncing… while working) and an × button titled Unbind. After a sync, a line under the binding says what changed, or In sync — source unchanged., and a notice at the bottom of the panel reads Synced — … or Already in sync with the source. When a sync returns a diagram, its source is loaded into the editor. Errors appear in a red notice at the bottom of the panel. Sync now in the Studio, like Reconcile on the Live dashboard, uses an AI key saved to your account but not a key kept only in your browser.

The binding card

Each binding on the Live dashboard is a card showing a status badge, the figure's title, the project (in …), the source (owner/repo@ref for a repository, the host and the last two parts of the path for a file), and checked … (for example checked just now, checked 3h ago, checked 2d ago, or checked never). After a Check or a Reconcile, a line under the card shows that run's one-sentence summary. Its buttons:

The strip at the top of the dashboard counts your bindings by status (for example 2 in sync, 1 drift), and Refresh reloads them.

Status badges

After a Check, a short message confirms the verdict: Verified in sync, Drift detected, Source unchanged since the last reconcile, or Source tracked — this diagram can't be verified against it structurally. After a Reconcile, it reads Diagram reconciled with its source or Already in sync; if a check or reconcile fails, the message is the error itself and the badge turns to Error.

For a figure that cannot be compared structurally, the summary line explains what was recorded, for example Baseline recorded. This diagram can't be compared with its source structurally, so future checks track source changes only. or The source has changed since the last sync — run a sync to reconcile.

What drifted

When a check finds drift, the card opens a What drifted panel with the share of the source's entities found in the diagram (coverage 67%) and up to four lists:

Each list shows its first eight items and a +N more count. Reconcile with AI — apply these edits at the bottom runs a reconcile.

Entities are matched by name: lower-cased, with parenthetical notes removed, with everything that is not a letter or a digit (spaces included) dropped, and with the affixes service, svc, server and the removed from the start or end of longer names. Connections are compared only between entities found on both sides. A node labelled API service matches a compose service named api; a node labelled Postgres does not match a service named db.

Reconcile and what it costs

Reconcile works in three steps and stops at the first that settles the matter:

1. If the binding is In sync and the source is byte-for-byte unchanged since it was last confirmed, nothing happens: Already in sync — the source hasn't changed.
2. If a structural comparison shows the figure already matches, nothing is rewritten: Verified structurally: the diagram matches the source.
3. Otherwise the flowss Studio Agent makes the smallest layout-preserving update to the figure and saves it.

On hosted AI, Reconcile needs at least 8 points available before it starts, even if it turns out to be free. An AI key saved to your account (the Bring-your-own key card on your account page, Starter and up) is used before points. Free includes no AI, so on Free use Check and fix the diagram by hand. On Starter, which has no hosted points, Reconcile works only with a key saved to your account; a key kept only in your browser is not used here. See AI points and limits and Bring your own AI key.

A step 3 run that did change the figure leaves a summary of what changed (for example Added 1 node (worker). followed by the AI's own account); one that did not reads No change — the diagram already matches the source.

If somebody edits the figure while a reconcile runs, flowss does not overwrite their edit: you see The bound diagram was edited while the sync ran, so the reconciled version was not written over it. Run the sync again to reconcile the edited diagram. and the card returns to Drift.

Run history

Runs lists the latest 25 checks and syncs, newest first, each with a coloured dot (green in sync, amber drift, red error), what triggered it, its summary or error, and when it ran. If there are none: No runs yet — hit Check to baseline this binding. Click Runs again to close the list; it is loaded once per visit, so reload the page to see runs added since.

Automatic checks

flowss re-checks bindings automatically. Every hour a sweep checks bindings that have not been checked for at least six hours, oldest first. It keeps going for up to about four and a half minutes and checks at most 240 bindings in one run; whatever it does not reach waits for the next hour. Automatic checks never use AI and never change your diagram: they only update the status, so the dashboard and your Library show drift the next time you look. With many bindings across the platform, an individual binding may wait longer than six hours between automatic checks; press Check whenever you need a fresh verdict.

Drift in your Library

Cloud projects in your Library carry a badge with the worst status of their bindings: Drift, Error, Syncing, Tracking or In sync.

What counts toward your limits

Removing a binding

On the Live dashboard, click the bin icon and confirm Unbind "…" from …? The diagram itself is untouched. You see Binding removed. In the Studio, click × (Unbind) in the Living source section; this removes the binding without asking, and if you lack the editor role it silently leaves the binding in place. Either way the figure stays exactly as it is.

Architecture tests and quality gates in CI

Anything that can make an HTTPS request can use the REST API, so every CI system can run flowss checks. All of them are deterministic: no AI, no cost surprises, and the same input always gives the same verdict. Each request spends one call from your account's daily allowance of 60.

Set up once

1. Create an API key on your account page: API keys, then Create key (full steps on The REST API).
2. In your repository settings, add the key as a secret named GLYPH_API_KEY.
3. Add a variable named GLYPH_URL with the value https://www.flowss.ai.

The workflows on this page use those two names because the Live dashboard's CI button does too, so one secret serves every workflow.

Note: Pull requests opened from forks do not receive your repository's secrets, so these workflows can only run on pull requests from branches of the same repository.

The workflow from the CI button

On the Live dashboard, click CI on a binding. The dialog Architecture test — fail the PR when this diagram lies shows a complete workflow with your project and figure ids filled in, under a reminder to add a GLYPH_API_KEY secret (created in Account, API keys) and a GLYPH_URL variable; Copy workflow copies it and confirms Workflow copied. It looks like this:

# .github/workflows/architecture-test.yml
name: Architecture test
on: [pull_request]
jobs:
  verify-diagram:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Verify "System context" still matches this repo
        run: |
          RES=$(curl -sS -X POST "${{ vars.GLYPH_URL }}/api/v1/verify" \
            -H "Authorization: Bearer ${{ secrets.GLYPH_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"projectId":"<project id>","figureId":"<figure id>"}')
          echo "$RES" | jq .
          [ "$(echo "$RES" | jq -r .pass)" = "true" ] || {
            echo "::error::Architecture drift — the diagram no longer matches the code."; exit 1; }

With no truth in the request, flowss re-fetches the binding's own source on its servers. That means the check compares the diagram with the source as it is published (for example on your default branch), not with the pull request's changes. To test the pull request itself, send the changed file as inline truth, as in the next workflow.

Test a pull request's own changes

This version reads the compose file and the diagram from the checked-out pull request and sends both inline, so it needs no binding and no stored figure:

# .github/workflows/architecture-test.yml
name: Architecture test
on: pull_request
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: The architecture diagram must match docker-compose.yml
        env:
          GLYPH_URL: ${{ vars.GLYPH_URL }}
          GLYPH_API_KEY: ${{ secrets.GLYPH_API_KEY }}
        run: |
          set -euo pipefail
          jq -n --rawfile d docs/architecture.mmd --rawfile c docker-compose.yml \
            '{diagram: {engine: "mermaid", code: $d}, truth: {kind: "compose", content: $c}}' > body.json
          curl -sS --fail-with-body -X POST "$GLYPH_URL/api/v1/verify" \
            -H "Authorization: Bearer $GLYPH_API_KEY" \
            -H "Content-Type: application/json" \
            --data-binary @body.json > result.json
          jq . result.json
          if [ "$(jq -r .pass result.json)" != "true" ]; then
            echo "::error::$(jq -r .summary result.json)"
            exit 1
          fi

truth.kind may be compose, sql, openapi, or a diagram engine (mermaid, d2, graphviz, dbml, structurizr, erd). The diagram must be in one of the structural engines. --fail-with-body makes the job fail with the error message if the request itself is refused (a bad key, a used-up allowance), which keeps "the diagram drifted" and "the check could not run" distinguishable in your logs.

Gate on diagram quality

Every Mermaid file under docs/diagrams/ must at least be sound (nothing mechanically broken). Raise gate to reviewed or publishable for stricter rules; the levels are explained on The REST API.

# .github/workflows/figure-quality.yml
name: Figure quality
on: pull_request
jobs:
  critique:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Every figure in docs/diagrams must be sound
        env:
          GLYPH_URL: ${{ vars.GLYPH_URL }}
          GLYPH_API_KEY: ${{ secrets.GLYPH_API_KEY }}
        run: |
          set -euo pipefail
          for f in docs/diagrams/*.mmd; do
            jq -n --rawfile c "$f" '{engine: "mermaid", code: $c, gate: "sound"}' > body.json
            curl -sS --fail-with-body -X POST "$GLYPH_URL/api/v1/critique" \
              -H "Authorization: Bearer $GLYPH_API_KEY" \
              -H "Content-Type: application/json" \
              --data-binary @body.json > result.json
            echo "$f: $(jq -r '.readiness.level + " — " + .readiness.reason' result.json)"
            if [ "$(jq -r .pass result.json)" != "true" ]; then
              echo "::error file=$f::$(jq -r '.readiness.blocking[0] // .readiness.reason' result.json)"
              exit 1
            fi
          done

Each file is one call, so this suits a handful of diagrams. With more, critique only the files the pull request changed.

Comment a structural diff on every pull request

This workflow sends every diagram file the pull request changed to POST /api/v1/diff in one batch (one call, however many files), writes the Markdown summary to the job summary and posts it as a pull-request comment.

# .github/workflows/diagram-diff.yml
name: Diagram diff
on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  diagram-diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Diff the diagrams this pull request changes
        env:
          GLYPH_URL: ${{ vars.GLYPH_URL }}
          GLYPH_API_KEY: ${{ secrets.GLYPH_API_KEY }}
          GH_TOKEN: ${{ github.token }}
          BASE: ${{ github.event.pull_request.base.sha }}
          HEAD: ${{ github.event.pull_request.head.sha }}
          PR: ${{ github.event.pull_request.number }}
        run: |
          set -euo pipefail
          MB=$(git merge-base "$BASE" "$HEAD")
          PATTERNS=('*.mmd' '*.mermaid' '*.d2' '*.dot' '*.gv' '*.dbml' '*.sql')
          git diff --name-only "$MB" "$HEAD" -- "${PATTERNS[@]}" > changed.txt
          if [ ! -s changed.txt ]; then echo "No diagram files changed."; exit 0; fi
          echo '[]' > batch.json
          while IFS= read -r f; do
            case "$f" in
              *.mmd|*.mermaid) eng=mermaid ;;
              *.d2) eng=d2 ;;
              *.dot|*.gv) eng=graphviz ;;
              *.dbml) eng=dbml ;;
              *.sql) eng=sql ;;
            esac
            git show "$MB:$f" > before.txt 2>/dev/null || : > before.txt
            git show "$HEAD:$f" > after.txt 2>/dev/null || : > after.txt
            jq --arg p "$f" --arg e "$eng" --rawfile b before.txt --rawfile a after.txt \
              '. + [{path: $p, engine: $e, before: $b, after: $a}]' batch.json > batch.tmp
            mv batch.tmp batch.json
          done < changed.txt
          jq '{files: .}' batch.json > body.json
          curl -sS --fail-with-body -X POST "$GLYPH_URL/api/v1/diff?format=markdown" \
            -H "Authorization: Bearer $GLYPH_API_KEY" \
            -H "Content-Type: application/json" \
            --data-binary @body.json > result.json
          jq -r '.markdown' result.json > diff.md
          cat diff.md >> "$GITHUB_STEP_SUMMARY"
          gh pr comment "$PR" --body-file diff.md

Things to know about this workflow:

• It posts a new comment on every push to the pull request. Remove the last line if you prefer only the job summary.
• A batch holds up to 100 files and 4 MB of source; split larger pull requests.
• A file that was added or deleted has an empty side, so the API compares it as text and reports The source changed. rather than a node-by-node breakdown.
• To block merges that remove things, append these lines to the end of the same step's run script (they reuse MB, HEAD and PATTERNS from it), so the job fails when any result lists removed nodes or edges, or when a diagram file was deleted:

removed=$(jq '[.results[] | select(((.diff.removedNodes // []) | length) > 0 or ((.diff.removedEdges // []) | length) > 0)] | length' result.json)
deleted=$(git diff --name-only --diff-filter=D "$MB" "$HEAD" -- "${PATTERNS[@]}" | wc -l)
if [ "$removed" -gt 0 ] || [ "$deleted" -gt 0 ]; then
  echo "::error::This pull request removes parts of the architecture. Review the diagram diff."
  exit 1
fi

Other CI systems

The same requests work anywhere. A GitLab CI job that runs the architecture test on merge requests:

architecture-test:
  image: alpine:3.20
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  before_script:
    - apk add --no-cache curl jq
  script:
    - |
      jq -n --rawfile d docs/architecture.mmd --rawfile c docker-compose.yml \
        '{diagram: {engine: "mermaid", code: $d}, truth: {kind: "compose", content: $c}}' > body.json
      curl -sS --fail-with-body -X POST "$GLYPH_URL/api/v1/verify" \
        -H "Authorization: Bearer $GLYPH_API_KEY" \
        -H "Content-Type: application/json" \
        --data-binary @body.json > result.json
      jq . result.json
      test "$(jq -r .pass result.json)" = "true"

Define GLYPH_API_KEY as a masked CI/CD variable and GLYPH_URL as a plain one. In Jenkins, CircleCI or Buildkite, run the same curl and jq commands in a shell step with the key from your secret store.

Keep generated diagrams up to date

POST /api/v1/generate turns a SQL schema, an OpenAPI spec or a DBML, D2, Graphviz, Structurizr, ERD or Mermaid flowchart source into a Mermaid diagram, byte-for-byte the same every time for the same input. A CI job can regenerate a committed Mermaid file from its source and fail when the committed copy is stale:

jq -n --rawfile c db/schema.sql '{engine: "sql", code: $c}' > body.json
curl -sS --fail-with-body -X POST "$GLYPH_URL/api/v1/generate" \
  -H "Authorization: Bearer $GLYPH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @body.json | jq -j .mermaid > /tmp/db.mmd
diff -u docs/db.mmd /tmp/db.mmd || { echo "docs/db.mmd is stale: regenerate it."; exit 1; }

jq -j writes the mermaid value exactly as returned, with no extra newline, so commit the file produced the same way. A source that cannot be parsed answers HTTP 422, which --fail-with-body turns into a failed job.

Embedding diagrams in docs, wikis and chat

Live embeds

An embed is a link to the /embed page that carries the whole diagram, so it renders anywhere an iframe or a link works, with no account: Notion, Confluence, blogs, READMEs and any HTML page.

How the two embed dialogs differ:

The embed script, live embeds from a repository file, themes, sizes and the headless render API are covered on Embedding and the render API.

Pasting into chat, docs and slides

In the Studio's export menu, under Copy to clipboard:

Every export format is listed on Exporting your work.

Connecting AI assistants (MCP)

flowss runs a Model Context Protocol server at https://www.flowss.ai/api/mcp (JSON-RPC 2.0 over HTTP; a plain GET lists its tools). Point any MCP client that speaks HTTP at it and send your API key as Authorization: Bearer glyp_…. Without a key, the assistant can list engines and templates, detect an engine, verify and critique diagrams, and convert between engines that have a built-in converter. With your key it can also generate, render and diff diagrams, convert with AI and run the science checks; those calls are metered to your account exactly as the REST API is. Setup, the tool list and the limits are on The flowss MCP server.

LaTeX and Overleaf

• The Studio's TikZ panel turns a figure into LaTeX when you press Convert (later Regenerate). The conversion is an AI call, so it needs hosted AI points (Plus and up) or your own AI key (Starter and up); conversions on hosted AI also have a per-plan daily limit of their own. Once there is LaTeX, Copy LaTeX and Download .tex save it, and Open in Overleaf (tooltip Open this LaTeX directly in a new Overleaf project) sends it to Overleaf, which opens it as a new project. You need an Overleaf account. See Data, timeline, TikZ and the diagram tools.
• The Evidence studio exports a bibliography as BibTeX (.bib) for LaTeX and Overleaf.

Reference managers

The Evidence studio reads and writes the formats reference managers use:

There is no live connection to a reference manager's library; you move files between them. More on Screening, extraction and synthesis.

Packaged tools that are not yet available

flowss has built several tools that wrap the REST API for particular places, but none of them is offered for you to install from flowss yet (the diff runner, for example, is not published to npm). Everything they do is available through the API, and the equivalents below work now.

Automatic pull requests depend on a GitHub App that flowss.ai does not offer for installation, so that feature is not available on flowss.ai. There is also no webhook you can add to your own repository to trigger checks on push; use the automatic checks, the Check button and your CI instead.

Tips

• Bind the file that is the real source of truth (the compose file, the DDL, the spec), not a copy of the diagram, so drift means "the system changed".
• Name diagram nodes after the services, tables or endpoints in the source; matching is by name.
• On Free, bind from the Live dashboard rather than with Bind & sync in the Studio, so binding never asks for AI.
• One schema or one spec per binding keeps each file under the 256 KB limit.
• Batch diffs into one request per pull request; each request spends one of your 60 daily calls, however many files it carries.
• Give each CI pipeline its own API key, named after it, so you can see which ones run and revoke one without breaking the others.
• Keep a GLYPH_URL variable rather than hard-coding the address, so every workflow changes in one place.

Limits and known constraints

• Only public repositories and publicly reachable files on the five allowed hosts can be bound. Private repositories, self-hosted Git servers and other hosts are not supported.
• File sources must be 256 KB or smaller; repository manifests 128 KB or smaller.
• A figure can have one binding.
• Automatic checks run once an hour (at most 240 bindings a run) and only for bindings not checked in the last six hours, so they are not instant.
• Reconcile needs AI: hosted points (8, only when the AI rewrites the figure) or an AI key saved to your account. Free cannot reconcile.
• Check and API checks share your account's 60 deterministic calls a day with the rest of the REST API and the render API.
• Reconcile, Sync now and Bind & sync need AI, even when the result turns out to be free, and they use a key saved to your account, never one kept only in your browser.
• Opening a figure in Overleaf requires a TikZ conversion, which is an AI call.
• verify passes a diagram that draws extra connections the source lacks; they are reported as stale connections but do not fail the check.
• The packaged GitHub Action, command-line tools and VS Code extension are not yet published, and automatic pull requests on push are not offered on flowss.ai.
• Studio embed links carry the source in the address, so very large diagrams make links some hosts will not accept.
• There is no two-way sync with Notion, Confluence, Slack or reference managers: you embed, paste or move files.

Troubleshooting

Related pages

• The REST API
• Embedding and the render API
• The flowss MCP server
• Exporting your work
• Your library
• Live collaboration and Sharing and permissions
• AI points and limits and Bring your own AI key
• Data, timeline, TikZ and the diagram tools
• Screening, extraction and synthesis
• Plans and what they include