What this example shows
A KYC / customer-onboarding pipeline rendered as a data-flow architecture diagram, with sensitive-data edges visually distinct from regular flows. The diagram captures where personally identifiable information enters the system, every system that stores or processes it, and where it crosses a trust boundary into a third-party service. Every revision is kept with its date and message, so you can open the diagram as it stood on any date.
When to use it
Reach for this when a vendor is reviewing your data flows, when a security team is assessing PII exposure, when a customer’s procurement team asks for a diagram of where their data lives, or when you need to show how those flows looked on an earlier date. The diagram shows what your inventory says; it doesn’t check the live systems. The diagram is generated from a classified inventory rather than hand-drawn - agents are good at this kind of comprehensive sweep, humans are good at reviewing the result.
What the agent does
The agent ingests a data classification source (compliance inventory, data catalog, or codebase scan tagged with PII annotations), then applies typed operations to the persisted scene: createNode for each system that touches PII, createEdge with sensitive-data styling for each flow, and a dashed frame around the external KYC vendor, so the trust boundary PII crosses is explicit. Every change creates an immutable revision, and diagram_history lists them with their dates and messages.
When the architecture changes - a vendor swap, a new processor, a deprecated cache - the agent applies the delta and the visual diff highlights exactly what’s different from an earlier revision. The revision history records each change with its date and message.
What the output includes
- A dashed “External trust boundary” frame around the third-party KYC vendor, the one place PII leaves your systems.
- Sensitive-data edges visually styled distinctly from regular flows.
- A complete revision history accessible via
diagram_historywith timestamps and per-revision messages - each revision documents what changed and why. - Visual diff between any two revisions for “what changed since the last review?” questions.
- Persistent stable IDs so a system that’s been in the architecture for years has the same
elementIdin every revision, simplifying comparisons across dates.
Rendered diagram
Drawn by Zindex from the scene below with POST /v1/diagrams/preview.
Open it in the Playground to swap themes (clean / dark / blueprint / sketch),
or add format: "png" to the same request for a PNG.
Scene JSON
Raw
The DSP scene the diagram above is drawn from. Open it in the
Playground, or send it as scene to
POST /v1/diagrams/preview to draw it yourself.
{
"schemaVersion": "0.1",
"scene": {
"id": "compliance-pii-flow",
"title": "KYC onboarding - PII data flow with trust boundary",
"brief": "Where personal data goes in KYC onboarding: from the customer to the KYC vendor, document store, vault and audit log.\nAn edge's style is its data's class: unsafe where full PII or ID photos go to a vendor or a store, safe for tokenized or hashed data, plainEdge for traffic into and inside the platform. The External trust boundary frame holds every third party under a DPA. Each store's label says what it keeps. Only systems the data inventory classifies belong here.",
"units": "px",
"canvas": {
"width": 1200,
"height": 820,
"background": "#1a1a22"
}
},
"diagramFamily": "architecture",
"layoutStrategy": {
"direction": "LR",
"nodeSpacing": 40,
"rankSpacing": 120
},
"palette": {
"background": "#1a1a22",
"foreground": "#ece8dc",
"nodeFill": "#222230",
"nodeStroke": "#d4a843",
"edgeStroke": "#96918a",
"mutedForeground": "#96918a",
"containerFill": "#1f1f28",
"containerStroke": "#c0544e",
"accentPrimary": "#c0544e",
"accentSecondary": "#4db89a"
},
"styles": {
"safe": {
"fill": "#222230",
"stroke": "#4db89a",
"strokeWidth": 2
},
"unsafe": {
"fill": "#222230",
"stroke": "#c0544e",
"strokeWidth": 2,
"textColor": "#c0544e",
"dash": [
6,
4
]
},
"internal": {
"fill": "#222230",
"stroke": "#d4a843",
"strokeWidth": 1.5
},
"vendorNode": {
"fill": "#222230",
"stroke": "#c0544e",
"strokeWidth": 2,
"textColor": "#ece8dc"
},
"safeStorage": {
"fill": "#222230",
"stroke": "#4db89a",
"strokeWidth": 2,
"textColor": "#ece8dc"
},
"boundary": {
"fill": "#1f1f28",
"stroke": "#c0544e",
"strokeWidth": 1,
"dash": [
4,
4
],
"textColor": "#ece8dc"
},
"plainEdge": {
"stroke": "#96918a",
"strokeWidth": 1.5,
"textColor": "#ece8dc"
}
},
"elements": [
{
"id": "customer",
"kind": "node",
"nodeType": "actor",
"shape": "roundedRect",
"label": "Customer",
"icon": "lucide:user",
"style": "internal"
},
{
"id": "webapp",
"kind": "node",
"nodeType": "service",
"shape": "roundedRect",
"label": "Onboarding\nWeb App",
"icon": "lucide:globe",
"style": "internal"
},
{
"id": "orch",
"kind": "node",
"nodeType": "service",
"shape": "roundedRect",
"label": "KYC\nOrchestrator",
"icon": "lucide:shield",
"style": "internal"
},
{
"id": "vendor",
"kind": "node",
"nodeType": "service",
"shape": "cloud",
"label": "KYC Vendor\n3rd party (DPA)",
"icon": "lucide:cloud",
"style": "vendorNode"
},
{
"id": "trust-frame",
"kind": "frame",
"children": [
"vendor"
],
"title": "External trust boundary",
"containerType": "boundary",
"style": "boundary"
},
{
"id": "iddocs",
"kind": "node",
"nodeType": "database",
"shape": "cylinder",
"label": "ID Document Store\nS3 + KMS",
"icon": "lucide:lock",
"style": "internal"
},
{
"id": "vault",
"kind": "node",
"nodeType": "database",
"shape": "cylinder",
"label": "Customer Vault\ntokenized PII",
"icon": "lucide:key",
"style": "safeStorage"
},
{
"id": "audit",
"kind": "node",
"nodeType": "database",
"shape": "cylinder",
"label": "Audit Log\nhashed events (immutable)",
"icon": "lucide:file-code",
"style": "safeStorage"
},
{
"id": "e1",
"kind": "edge",
"from": {
"elementId": "customer"
},
"to": {
"elementId": "webapp"
},
"router": "orthogonal",
"label": "submit KYC",
"style": "plainEdge"
},
{
"id": "e2",
"kind": "edge",
"from": {
"elementId": "webapp"
},
"to": {
"elementId": "orch"
},
"router": "orthogonal",
"label": "full PII",
"style": "plainEdge"
},
{
"id": "e3",
"kind": "edge",
"from": {
"elementId": "orch"
},
"to": {
"elementId": "vendor"
},
"router": "orthogonal",
"label": "full PII (DPA)",
"style": "unsafe"
},
{
"id": "e4",
"kind": "edge",
"from": {
"elementId": "orch"
},
"to": {
"elementId": "iddocs"
},
"router": "orthogonal",
"label": "ID photo",
"style": "unsafe"
},
{
"id": "e5",
"kind": "edge",
"from": {
"elementId": "orch"
},
"to": {
"elementId": "vault"
},
"router": "orthogonal",
"label": "tokenized",
"style": "safe"
},
{
"id": "e6",
"kind": "edge",
"from": {
"elementId": "orch"
},
"to": {
"elementId": "audit"
},
"router": "orthogonal",
"label": "hashed events",
"style": "safe"
}
],
"constraints": [
{
"type": "order",
"source": "vendor",
"target": "iddocs",
"relation": "above"
},
{
"type": "order",
"source": "iddocs",
"target": "vault",
"relation": "above"
},
{
"type": "order",
"source": "vault",
"target": "audit",
"relation": "above"
}
]
} Agent workflow
Maintain a data-flow diagram showing where PII / KYC / financial data moves between systems, what each system stores, and how the topology has changed over time, by combining a structured data-classification inventory with a Zindex diagram whose every revision is kept with its date and message.
Inputs
- Data-classification inventory (typically a YAML/JSON file in compliance/ describing which fields each system stores and their classification)
- Trust-boundary configuration (which systems sit inside vs outside the company perimeter)
- The diagram's Zindex ID or key (one per documented workflow - e.g. one for KYC, one for billing)
- A Zindex API key, or an MCP client signed in to Zindex
Outputs
- A new revision of the diagram with one node per system, edges labeled by what data crosses (e.g. 'full PII (DPA)'), and a frame around any external trust boundary
- Rendered SVG of the current revision
- A compare showing what changed between the start of a review period and now, with the period's revisions and their messages
- An address on each image, `zindex.ai/d/<id>@<revision>`, naming the diagram and revision it shows, with its date
- 01
Read the data-flow diagram
Data-flow diagrams are long-lived - one per documented workflow, with many revisions over time. Read the current revision with
view: "dsp"before changing anything: the scene JSON carries the edge labels and stroke styles the diff needs, which the default outline leaves out. - 02
Read the data-classification inventory
Parse compliance/data-classification.yaml. Each entry maps a system to the data it stores and its classification (
public,internal,pii,kyc,financial). Edges between systems are derived from which classification crosses each boundary. - 03
Compute the diff against the diagram
For each system in the classification, ensure a node exists with the expected nodeType (
actor,service,database,externalSystem). For each data flow, ensure an edge exists with the expected label (e.g. 'full PII (DPA)' or 'tokenized'). Style PII-bearing edges with a red stroke; tokenized/hashed edges with green; internal-only edges in default. Frame any external-vendor systems inside a dashed trust-boundary frame so readers can see what data crosses the company perimeter. - 04
Save the changes as one edit
Send the diff as one
diagram_editwithbaseRevisionset to the revision you read. Use amessagethat says what changed and why - 'add tokenization layer between webapp and customer vault'. The edit is all or nothing: if an operation has errors, it returnsVALIDATION_FAILEDand saves nothing. Zindex records each revision's date, and the message appears indiagram_history. - 05
Fix what the warnings report
The edit's
warningslist what checking and drawing the new revision noticed, each with acode, theelementwhen there is one, and a one-linefix. Resolve them with a follow-up edit before publishing.LABEL_DUPLICATION_DETECTEDmeans edges at one system share a label, which confuses a reader: name what each one carries. - 06
Render the data-flow diagram
Get SVG and PNG links to the new revision; they work without a key for 7 days. The image prints its address,
zindex.ai/d/<id>@<revision>, and date, so readers always know which version of the diagram they are looking at, with no separate metadata sidecar. - 07
Compare a review period
When the team reviews a period (typically quarterly), call
diagram_historywithcompare: { from }, wherefromis the revision current at the start of the period or the date it started, such as2026-07-01;todefaults to the latest revision. The output lists the elements added, removed and changed over the period. - 08
List the period's revisions
diagram_historywithoutcomparelists the revisions newest first, each with its date, the client that made it, its message, and how many elements it added, changed and removed. Together with the compare, that is the record of what changed in the period and why. - 09
Save the SVG, the compare and the revision list
Save the rendered SVG, the compare JSON and the revision list wherever the team keeps its review material. All of them name the diagram and revision, so anyone can open that exact revision later. The diagram shows what the inventory said; it does not check the live systems.
MCP recipe
For agents using Model Context Protocol. The tool sequence below matches the workflow steps; copy the prompt as a system message.
Tool sequence
- 01
diagram_getRead the data-flow diagram - 02
diagram_editSave the changes as one edit - 03
diagram_renderRender the data-flow diagram - 04
diagram_historyCompare a review period - 05
diagram_historyList the period's revisions
Unique tools used: diagram_get, diagram_edit, diagram_render, diagram_history.
Copyable agent prompt
Drop this verbatim into a system prompt for an MCP-connected agent.
The Zindex MCP server at https://api.zindex.ai/mcp exposes
the tools the prompt references (connect a client),
and so does the npm package @zindexai/mcp, which forwards
to it.
You maintain the data-flow diagram that the security team keeps in Zindex: where personal, KYC and financial data moves between systems, what each system stores, and where data crosses into a third-party vendor. When asked to update it, you read the data-classification inventory and change the diagram with typed edits, each with a message saying what changed and why. Every revision is kept with its date and message, so the team can open the diagram as it stood on any date and see what changed between two dates.
The diagram's Zindex ID is `${SCENE_ID}`; it already exists. Each workflow you document has its own diagram - one for KYC, one for billing, one for any vendor-share boundary. The diagram shows what the inventory said at each revision; it does not check the live systems, so the inventory has to be accurate.
Steps for each update (for example when `compliance/data-classification.yaml` changes):
1. Read `compliance/data-classification.yaml` (or the equivalent inventory). Each entry maps a system to (a) the data it stores, (b) the data classification (`public`, `internal`, `pii`, `kyc`, `financial`), and (c) whether the system is internal or an external vendor.
2. Call `diagram_get({ id: "${SCENE_ID}", view: "dsp" })` to read the current revision and the scene JSON, which carries the edge labels and stroke styles the default outline leaves out. Do not modify anything yet - this update might change nothing if classifications haven't changed.
3. Diff the parsed classification against the diagram. For each system, ensure a node exists with the right nodeType (`actor`, `service`, `database`, `externalSystem`) and label. For each data-flow edge, ensure the edge exists with a label that names what data crosses (e.g. 'full PII (DPA)', 'tokenized', 'hashed events'). Apply edge styles consistently: red stroke for unprotected PII, green for tokenized/hashed, default for internal traffic - readers should be able to see the protection posture at a glance. If any external vendors are touched, wrap them in a dashed trust-boundary frame so the perimeter is explicit.
4. Call `diagram_edit({ id: "${SCENE_ID}", baseRevision, message, ops })` with one batch, `baseRevision` set to the revision you read. The edit is all or nothing. The `message` should say in one line what changed and why: 'add tokenization layer between webapp and customer vault' or 'add SendGrid as PII recipient under DPA'. Zindex records the date of every revision, so the message doesn't need one. Messages appear in `diagram_history`.
5. An edit with errors returns `VALIDATION_FAILED` and saves nothing. A saved edit returns `warnings`: what checking and drawing the new revision noticed, each with a `code`, the `element` when there is one, and a one-line `fix`. Resolve them with a follow-up edit before publishing. `LABEL_DUPLICATION_DETECTED` means edges at one system share a label, which confuses a reader: rename one so each says what it carries.
6. Call `diagram_render({ id: "${SCENE_ID}" })`. It returns SVG and PNG links to the new revision, valid for 7 days. Each revision's image prints its address, `zindex.ai/d/<id>@<revision>`, and date, so readers can tell which revision they are looking at.
7. When the team reviews a period (quarterly is typical), call `diagram_history({ id: "${SCENE_ID}", compare: { from: ${AUDIT_START_REVISION} } })`, where `${AUDIT_START_REVISION}` is the revision current at the start of the period; `from` also takes the date the period started, such as `"2026-07-01"`. The output lists the elements added, removed and changed over the period, and `diagram_history({ id: "${SCENE_ID}" })` lists the period's revisions with their dates and messages. Save the SVG, the compare JSON and the revision list wherever the team keeps its review material.
Hard rules: never hand-edit the rendered SVG; the address printed on each image ties it to its diagram and revision. Zindex never rewrites a revision: to undo a change, make a new edit (or call `diagram_edit` with `restoreRevision`) with a message saying why. Never publish a revision whose warnings you haven't resolved. Treat the data-classification inventory as the source of truth; if a system is not classified, it does not belong in the diagram until it is.
HTTP API recipe
For agents/devs not using MCP. Send
Authorization: Bearer $ZINDEX_API_KEY on every call
except POST /v1/diagrams/validate and
POST /v1/diagrams/preview, which need no key. In the
paths, ${SCENE_ID} is the diagram's ID, or the
key you gave it in diagram_create. Full
reference: REST API, OpenAPI spec.
- 01
GET/v1/diagrams/${SCENE_ID}?view=dspData-flow diagrams are long-lived - one per documented workflow, with many revisions over time. Read the current revision with
view: "dsp"before changing anything: the scene JSON carries the edge labels and stroke styles the diff needs, which the default outline leaves out. - 02
POST/v1/diagrams/${SCENE_ID}/revisionsSend the diff as one
diagram_editwithbaseRevisionset to the revision you read. Use amessagethat says what changed and why - 'add tokenization layer between webapp and customer vault'. The edit is all or nothing: if an operation has errors, it returnsVALIDATION_FAILEDand saves nothing. Zindex records each revision's date, and the message appears indiagram_history. - 03
GET/v1/diagrams/${SCENE_ID}/renderGet SVG and PNG links to the new revision; they work without a key for 7 days. The image prints its address,
zindex.ai/d/<id>@<revision>, and date, so readers always know which version of the diagram they are looking at, with no separate metadata sidecar. - 04
GET/v1/diagrams/${SCENE_ID}/compare?from=${AUDIT_START_REVISION}When the team reviews a period (typically quarterly), call
diagram_historywithcompare: { from }, wherefromis the revision current at the start of the period or the date it started, such as2026-07-01;todefaults to the latest revision. The output lists the elements added, removed and changed over the period. - 05
GET/v1/diagrams/${SCENE_ID}/revisionsdiagram_historywithoutcomparelists the revisions newest first, each with its date, the client that made it, its message, and how many elements it added, changed and removed. Together with the compare, that is the record of what changed in the period and why.
Operations
Raw The typed operations that build this diagram from empty. Save an
empty diagram with diagram_create, then send the
envelope's baseRevision, message and
ops to diagram_edit, or
POST /v1/diagrams/{id}/revisions. Each op
carries a stable id so subsequent runs can update the
same elements instead of regenerating.
{
"schemaVersion": "0.1",
"sceneId": "compliance-pii-flow",
"baseRevision": 1,
"message": "Initial PII data-flow diagram with vendor trust boundary",
"ops": [
{
"op": "createFrame",
"id": "trust-frame",
"title": "External trust boundary",
"containerType": "boundary",
"children": [
"vendor"
],
"style": "boundary"
},
{
"op": "createNode",
"id": "customer",
"nodeType": "actor",
"shape": "roundedRect",
"label": "Customer",
"icon": "lucide:user",
"style": "internal"
},
{
"op": "createNode",
"id": "webapp",
"nodeType": "service",
"shape": "roundedRect",
"label": "Onboarding\nWeb App",
"icon": "lucide:globe",
"style": "internal"
},
{
"op": "createNode",
"id": "orch",
"nodeType": "service",
"shape": "roundedRect",
"label": "KYC\nOrchestrator",
"icon": "lucide:shield",
"style": "internal"
},
{
"op": "createNode",
"id": "vendor",
"nodeType": "service",
"shape": "cloud",
"label": "KYC Vendor\n3rd party (DPA)",
"icon": "lucide:cloud",
"style": "vendorNode"
},
{
"op": "createNode",
"id": "iddocs",
"nodeType": "database",
"shape": "cylinder",
"label": "ID Document Store\nS3 + KMS",
"icon": "lucide:lock",
"style": "internal"
},
{
"op": "createNode",
"id": "vault",
"nodeType": "database",
"shape": "cylinder",
"label": "Customer Vault\ntokenized PII",
"icon": "lucide:key",
"style": "safeStorage"
},
{
"op": "createNode",
"id": "audit",
"nodeType": "database",
"shape": "cylinder",
"label": "Audit Log\nhashed events (immutable)",
"icon": "lucide:file-code",
"style": "safeStorage"
},
{
"op": "createEdge",
"id": "e1",
"from": {
"elementId": "customer"
},
"to": {
"elementId": "webapp"
},
"label": "submit KYC",
"router": "orthogonal",
"style": "plainEdge"
},
{
"op": "createEdge",
"id": "e2",
"from": {
"elementId": "webapp"
},
"to": {
"elementId": "orch"
},
"label": "full PII",
"router": "orthogonal",
"style": "plainEdge"
},
{
"op": "createEdge",
"id": "e3",
"from": {
"elementId": "orch"
},
"to": {
"elementId": "vendor"
},
"label": "full PII (DPA)",
"router": "orthogonal",
"style": "unsafe"
},
{
"op": "createEdge",
"id": "e4",
"from": {
"elementId": "orch"
},
"to": {
"elementId": "iddocs"
},
"label": "ID photo",
"router": "orthogonal",
"style": "unsafe"
},
{
"op": "createEdge",
"id": "e5",
"from": {
"elementId": "orch"
},
"to": {
"elementId": "vault"
},
"label": "tokenized",
"router": "orthogonal",
"style": "safe"
},
{
"op": "createEdge",
"id": "e6",
"from": {
"elementId": "orch"
},
"to": {
"elementId": "audit"
},
"label": "hashed events",
"router": "orthogonal",
"style": "safe"
}
]
} Validation
Valid
Captured response from POST /v1/diagrams/validate, the
check diagram_validate runs. It checks the scene and
draws it. Every code it can return is in the validation rules.
- 0 errors
- 0 warnings
The scene validates with no errors or warnings.
Each entry has a code, the element it
concerns when there is one, and a one-line fix.
diagram_create and diagram_edit save
nothing when there are errors and return
VALIDATION_FAILED; warnings don't block a save. Both
return the same warnings for the revision they save, so an agent
reads them from the write itself.
Revision diff
Raw
What changed between two revisions of the diagram, as
diagram_history returns it with compare.
Every revision is kept, so any two can be compared, by revision
number or by date.
Scenario
The data-flow diagram's first save. Revision 1 is the empty diagram and revision 2 applies the operations in ops.json, so every system, data flow and the vendor trust boundary is added. A review compares the same way, from the revision or the date the period started, and names only the systems and flows that changed since then.
- Revision 1 → 2
- +14 added
- -0 removed
- ~0 changed
- scene fields changed: canvas
+ Added
trust-framecustomerwebapporchvendoriddocsvaultaudite1e2e3e4e5e6
Raw compare response
{
"id": "dgm_syVqrpFgJJJj",
"from": 1,
"to": 2,
"added": [
"trust-frame",
"customer",
"webapp",
"orch",
"vendor",
"iddocs",
"vault",
"audit",
"e1",
"e2",
"e3",
"e4",
"e5",
"e6"
],
"changed": [],
"removed": [],
"scene": [
"canvas"
],
"scenario": "The data-flow diagram's first save. Revision 1 is the empty diagram and revision 2 applies the operations in ops.json, so every system, data flow and the vendor trust boundary is added. A review compares the same way, from the revision or the date the period started, and names only the systems and flows that changed since then."
}
To compare two versions of your own diagram, call
diagram_history with compare: { from, to },
or GET /v1/diagrams/{id}/compare with
from and to, giving revision numbers or
dates. With an API key,
GET /v1/images/{id}@{to}.svg?from={from}
draws the later version with what changed colored.
Agent resources
Machine-readable versions of this example. Agents should fetch these rather than scrape the rendered HTML.
-
compliance-pii-flow.scene.jsonCanonical DSP scene Open -
compliance-pii-flow.ops.jsonTyped-operation envelope that builds the scene Open -
compliance-pii-flow.workflow.jsonStructured agent workflow (goal, inputs, outputs, steps) Open -
compliance-pii-flow.diff.jsonSamplediagram_historycompare response Open -
compliance-pii-flow.svgRendered diagram Open -
compliance-pii-flow.mdAgent-readable markdown summary Open -
/examples/index.jsonManifest of all examples (cross-linked) Open