JSON2Map Userflow Diagram

Build editable system design diagrams from JSON inside VS Code.

Commands

• JSON2Map: Open Userflow Diagram
• JSON2Map: Generate Userflow Diagram from Selection
• JSON2Map: Generate Userflow Diagram from Current File
• JSON2Map: Generate Userflow Diagram from Clipboard

Use the selection/current-file/clipboard commands with JSON that describes systems, nodes, edges, groups, and custom icon references. The extension opens a webview with the same userflow diagram UI used by the JSON2Map web app.

Copilot Tool

This extension contributes a Copilot/agent-mode tool:

#json2mapUserflow

After the extension is installed, VS Code registers the tool automatically. In Copilot Chat agent mode, ask Copilot to generate a JSON2Map userflow diagram for your code and use #json2mapUserflow when you want to force the tool call.

Recommended prompt:

Use #json2mapUserflow.

Analyze this workspace and create a JSON2Map userflow system design diagram.

You must generate valid JSON and call #json2mapUserflow with that JSON.

Required top-level fields:
- version: "1"
- title
- description
- groups
- nodes
- edges
- icons

Node rules:
- Every node must have id, label, type, icon, description, position, size, tags, and metadata.
- Node ids must be short, stable, lowercase kebab-case strings.
- Use only these built-in icons unless a custom icon is explicitly available:
  api, browser, cache, cdn, cloud, database, event, function, gateway,
  lock, monitor, queue, server, storage, user.
- Use parents arrays to assign nodes to one or more groups.
- Position nodes left-to-right by request/data flow.

Group rules:
- Every group must have id, label, description, position, size, color, and zIndex.
- Use groups for app shell, domain layers, feature areas, extension/package system,
  external services, storage, observability, and deployment boundaries.

Edge rules:
- Do not omit edges.
- Every meaningful dependency, request, event, write, read, render, package,
  build, or extension-host interaction must be represented as an edge.
- Every edge must have id, source, target, label, protocol, and direction.
- source and target must exactly match existing node ids.
- direction must be one of: forward, reverse, both, none.
- Use direction "both" for request/response calls.
- Use direction "forward" for events, telemetry, package/build flow, file loading,
  persistence, and one-way data movement.
- Add at least one edge between every connected component so the diagram has visible lines.

Before calling the tool, validate:
- JSON parses successfully.
- nodes.length is greater than 0.
- edges.length is greater than 0.
- Every edge source and target exists in nodes.
- No duplicate node ids.

Then call #json2mapUserflow with the final JSON.

VS Code may still ask you to approve the tool invocation. That confirmation is controlled by VS Code/Copilot, not by this extension.

The tool preserves explicit edges and well-spaced positions from better models. It automatically enlarges nodes for readable text, assigns nodes listed inside groups, fixes crowded group layouts, and adds conservative fallback connections when Copilot supplies no usable edges.

JSON Shape

{
  "title": "Checkout Platform",
  "groups": [
    {
      "id": "commerce",
      "label": "Commerce System",
      "color": "#60a5fa",
      "nodes": ["web", "api", "db"]
    }
  ],
  "nodes": [
    {
      "id": "web",
      "label": "Web App",
      "type": "browser",
      "icon": "browser",
      "parents": ["commerce"]
    },
    {
      "id": "api",
      "label": "Checkout API",
      "type": "api",
      "icon": "api",
      "parents": ["commerce"]
    },
    {
      "id": "db",
      "label": "Orders DB",
      "type": "database",
      "icon": "database",
      "parents": ["commerce"]
    }
  ],
  "edges": [
    {
      "source": "web",
      "target": "api",
      "label": "checkout",
      "protocol": "HTTPS",
      "direction": "forward"
    },
    {
      "source": "api",
      "target": "db",
      "label": "writes",
      "protocol": "SQL",
      "direction": "both"
    }
  ]
}

Copilot Repair Prompt

If the rendered diagram has no lines, use this repair prompt:

The JSON2Map diagram has no visible lines. Fix the same JSON by adding
complete edges between the existing node ids. Do not rename nodes.
Every edge must have id, source, target, label, protocol, and direction.
Validate that every source and target exactly matches a node id, then call
#json2mapUserflow again.

Copilot Prompt Examples

Ask Copilot to generate JSON, then run one of the JSON2Map commands:

Read this repository module and create a JSON2Map system design JSON
with trust boundaries, data stores, async queues, external systems, and
bidirectional connections where appropriate.

Diagram Features

• Paste or load JSON into the left editor.
• Edit, drag, resize, and group nodes on the canvas.
• Use groups for systems, trust boundaries, data zones, environments, and ownership areas.
• Use parents for nodes that belong to multiple groups.
• Right-click nodes, groups, lines, and the canvas for editing actions.
• Download the diagram as PNG or SVG from Design tools.
• Copy Mermaid, node CSV, connection CSV, diagram summary, or share JSON.