Follow the path. Inspect the evidence. Share one offline file.
💡 Inspired by Cocoon-AI/architecture-diagram-generator — thanks to the original author for the idea.
English · 中文 · Русский · Português · 日本語 · Deutsch · Español
Live demo · Getting started · Client installation · Report an issue · MIT
Eleven diagram types: platform capability architecture, engineering layer architecture, component relationship architecture, flowchart, sequence, ER, deployment, class, state, use case and data flow.
QGraphFlow turns source code, schemas, configuration and requirements into interactive software diagrams, with evidence you can inspect and an offline HTML file you can share.
What sets it apart: eleven diagram types from one skill, an evidence kind on every relationship and the source line behind each code-backed one, automatic layout, editing in the page, and no network requests from the plugin scripts or the Viewer itself.
Using real Jeepay source code, switch between component relationship architecture, sequence and ER diagrams to explore components and call relationships. View full-size GIF
Complex sequence diagram showcase
A fictional e-commerce scenario contains 9 participants, 29 messages and 6 combined fragments, covering stock retries, nested branches, parallel processing, failure compensation and asynchronous callbacks. The animation progressively reveals the generated diagram to show its structure and details. View full-size GIF
npx skills add supermax92/qgraphflowOne command installs the skill for Claude Code, Codex, Cursor and Qoder; the installation guide covers the plugin installations and the other clients.
-
Explore: search, zoom and pan; inspect responsibilities and upstream/downstream relationships.
-
Verify: inspect nodes and edges for source files, lines, symbols and explicitly marked uncertainty.
-
Edit: unlock the layout, change text and move elements; reset when needed.
-
Share: open offline HTML or export the complete diagram as SVG / PNG.
The real-source Jeepay corpus contains all eleven views used by CI and the live demo.
After installation, open your application project in the client and select the q-flow skill. These examples use Claude Code's /q-flow; in Codex, use the $q-flow or $qgraphflow:q-flow entry actually provided by your client. Not installed yet? Read the installation guide first.
Invoke the skill without adding a request:
/q-flow
The skill guides you to choose the part to analyze and the question the diagram should answer. Drawing starts once the necessary information is clear.
/q-flow What types of diagrams can you draw? What questions does each type answer? I have just taken over a project; introduce your capabilities and suggest a starting point.
Learn what the eleven diagram types are for, then decide whether to explore project structure, call order, data relationships or something else.
/q-flow Help me draw this project. I want to understand it as quickly as possible.
You do not need to specify a diagram type first. The skill selects a suitable view based on the project and your goal, and asks follow-up questions when necessary information is missing.
Replace the business names and steps below with flows that actually exist in your project:
/q-flow Analyze the order creation flow in the current project and generate a sequence diagram in Chinese.
Cover the request entry point, pricing, stock reservation, payment authorization and order persistence.
Retain the synchronous calls, asynchronous messages, paired returns, activation bars, conditional branches, retries and failure compensation that actually exist in the source. Do not omit details for brevity.
Mark the source files and line numbers for components and calls, and save the result to docs/qgraphflow/order-sequence/.
State the subject, question, level of detail and output location clearly to start directly. The diagram retains only facts supported by evidence.
After the result is generated, continue in the same conversation:
/q-flow Expand the stock reservation step in the previous sequence diagram into a separate flowchart in Chinese.
Show all branches for stock validation, successful reservation, retryable failures, the retry limit and stock release. Follow the source code and add no steps absent from it.
Start with the overall picture, then explore one step in depth. You can also request more detail in an existing diagram or verify its relationships.
You need Node.js 22 or later and a plugin-capable client with model access configured.
npx skills add supermax92/qgraphflowTested with skills 1.7.0 for Claude Code, Codex, Cursor and Qoder. It asks which clients to install to; -a claude-code names one, and -g installs for your user instead of the current project. The skill installs as q-flow, without the qgraphflow: prefix of the plugin installations below.
To install it as a plugin instead, follow the steps below. Qoder Desktop users can install from the marketplace and skip step 1.
Get the plugin from npmjs.com; no account, login or token is needed. Create a separate directory outside your application project:
mkdir qgraphflow-install
cd qgraphflow-install
npm install qgraphflow --ignore-scripts
cd node_modules/qgraphflowYou are now in the plugin root. Downloading through npm does not automatically install the plugin in your client; continue with step 2. The package also provides the qgraphflow command used in Keep diagrams in sync with code.
Run the following terminal commands from the plugin root containing skills/.
Codex CLI must be installed and available in your terminal:
codex plugin marketplace add .
codex plugin add qgraphflow@supermax92Start a new session, type $, and select qgraphflow:q-flow.
claude plugin marketplace add ./
claude plugin install qgraphflow@supermax92 --scope userStart a new session and enter /q-flow (or the fully qualified /qgraphflow:q-flow).
qodercli plugins install .Start a new session and select q-flow.
Recommended: Open Settings → Plugins → Marketplace, search for QGraphFlow or 代码图谱可视化, and install the plugin. Start a new session and select q-flow.
For local installation, complete step 1, then open Settings → Plugins → Custom → Import and import the complete plugin root directory. Start a new session and select q-flow.
Copy everything in the plugin root, including hidden files, into:
~/.cursor/plugins/local/qgraphflow/
Confirm that .cursor-plugin/plugin.json exists there, reload the window, and find q-flow in Customize. Back up any previous version first; do not mix old and new files.
Open your application project in the client, start a new session and select the skill. Describe your request using the Getting started examples. Open the generated HTML in your browser.
Building it yourself? See the source build instructions.
These examples use $qgraphflow:q-flow in Codex. If your client shows $q-flow, select that entry instead. For other clients, use the skill entry described above.
Not sure where to begin? Invoke the skill and choose the subject and question when prompted.
$qgraphflow:q-flow
Already have a goal? Say which part to draw and what you want to understand. You do not need to choose a diagram type first.
$qgraphflow:q-flow Analyze the current project and generate an architecture diagram in Chinese, showing the responsibilities of the main modules, dependencies and system boundaries.
Useful when joining a project and learning its overall structure.
$qgraphflow:q-flow Analyze order creation and generate a sequence diagram in Chinese, showing the call order for pricing, stock reservation, payment and order persistence, and mark failure branches.
Replace order creation and its steps with your project's actual flow. Continue in the same conversation:
$qgraphflow:q-flow Expand the stock reservation step in the previous diagram into a separate flowchart in Chinese, showing success and failure handling.
Results go under docs/qgraphflow/ by default. Open index.html to explore, edit and export; graph.json retains the graph data. Each view is also written as an SVG (diagram.svg, or diagram-<n>-<type>.svg for several views) that you can embed as an image in a README, pull request or wiki.
After editing in the page, More → Save changes in Chrome or Edge rewrites the page, graph.json and the SVGs in place once you pick the diagram's folder. Other browsers save graph.json only: put it in the folder and regenerate the page and SVGs with npx -y qgraphflow generate docs/qgraphflow/<name>/graph.json docs/qgraphflow/<name> --layout preserve --force.
Run the eleven-view Jeepay source example
Select your Jeepay source checkout to verify the evidence:
export JEEPAY_REPO_ROOT="<local Jeepay repository root>"
node skills/q-flow/scripts/validate-graph.mjs examples/jeepay/collection.graph.json --input-only --repo-root "$JEEPAY_REPO_ROOT"
node skills/q-flow/scripts/generate-viewer.mjs examples/jeepay/collection.graph.json output/jeepay --repo-root "$JEEPAY_REPO_ROOT"Open output/jeepay/index.html; its eleven SVGs are in the same directory. See the corpus README for the source revision and refresh procedure.
A diagram generated with a repository root records where each component is defined and the line behind each code-backed relationship (a call, a foreign key). Validating it with --repo-root fails when a recorded file is gone, a line range no longer fits, or a recorded symbol has left its lines, and the error names the lines where the symbol is now. Add this job to your CI; it needs no build, login or token:
name: Diagrams
on: [push, pull_request]
jobs:
diagrams:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: '22'
- run: |
for graph in docs/qgraphflow/*/graph.json; do
npx -y qgraphflow validate "$graph" --input-only --repo-root . || { echo "::error file=$graph::$graph failed validation"; failed=1; }
done
exit ${failed:-0}When it fails, ask the skill to refresh that diagram:
$qgraphflow:q-flow CI says docs/qgraphflow/order-sequence is out of date. Refresh it.
The skill moves anchors whose symbol it finds once, corrects only the anchors still reported, and regenerates the page and SVGs with your edited positions and text kept. It does not redraw the diagram.
| View · PNG | Main question | Example scope |
|---|---|---|
| Platform capability architecture | What capabilities does the platform provide? | Capability zones and matrices |
| Engineering layer architecture | How is the engineering code organized? | Engineering layers and shared support |
| Component relationship architecture | Which responsibility boundaries collaborate in the system? | Channels, transaction orchestration, pricing, risk, stock, payment, orders, events and fulfillment |
| Flowchart | How does each decision point branch and converge? | Stock shortage, risk rejection, compensation for payment failure and successful commit |
| Sequence | In what order does a request make calls and receive returns? | Successful checkout main flow and asynchronous OrderPaid |
| ER | How does core data relate? | Cart, orders, items, payments, stock reservations and parcels |
| Deployment | Where are runtime units placed and how are they connected? | Edge, Kubernetes, data services, payment and warehouse/logistics networks |
| Class | How do domain objects and code contracts depend on each other? | Checkout application service, Order and four ports |
| State | Which events and guards advance an order? | Payment, fulfillment, cancellation, refund and closure |
| Use case | What capabilities does each actor have? | Buyer, merchant, warehouse and customer support |
| Data flow | What transformations and stores do data assets pass through? | Cart, transaction decisions, order events, warehouse/logistics and delivery receipts |
This is a concept model demonstrating QGraphFlow, not a particular e-commerce repository. The example graph.json invents no source paths and marks relationship evidence as inference. Real project diagrams need traceable source, DDL, configuration, tests and accepted requirements.
npm ci --prefix skills/q-flow/assets/viewer
npm run build --prefix skills/q-flow/assets/viewer
node --test tests/*.test.mjs skills/q-flow/scripts/*.test.mjsDevelopment needs Node.js 22 or later, npm, tar, zip and unzip. Include a minimal redacted graph, client/browser versions and reproduction steps in issue reports.
Reference documentation (English): Evidence sources · Graph data format · Guided intake · Viewer development and acceptance · Visual conventions
QGraphFlow is an independent MIT-licensed project. The scenarios in this document are conceptual examples and do not represent any real company's production architecture.
Architecture now includes component relations, platform capabilities and engineering layers. Describe the subject and question; the skill chooses the template. Requested collections can contain multiple architecture views with independent edits.
$qgraphflow:q-flow Analyze this project's platform capabilities and business integration methods, and generate a platform capability overview in Chinese.
$qgraphflow:q-flow Analyze the organization and component layers of the current project, and generate Chinese overviews of the whole project and a cross-section of one component.
$qgraphflow:q-flow Generate an English platform capability overview of this project and show how application modules integrate.
See examples/jeepay for real-source platform, engineering and component relationship architecture views. Unlock an overview to reorder cards within a layer or edit text. Save keeps all views; reset restores only the current one.