FlowZap - Not another Diagramming tool - FlowZap Unveils .fz: True Diagrams as Code for Sequence Diagrams and AI-Native Workflows

FlowZap is introducing three tightly connected capabilities: a new .fz file format, Save as .fz and Load .fz actions in the diagram editor, and an LLM-ready flowzap-code-guidelines.md file for your /docs/ folder. Together, they turn FlowZap into a practical “diagrams as code” platform for sequence diagrams—especially for developers using AI coding tools like Cursor, Windsurf, Warp, or Google AI Studio.

All rendering still happens in the FlowZap web app: .fz files contain only FlowZap Code text and are visualized when you load them on flowzap.xyz.

What “Diagrams as Code” Really Means

At its core, diagrams as code means you describe a diagram in text, store that text in version control (usually Git), and use tools to render the visual diagram on demand. Instead of manually drawing boxes and arrows in a GUI, you:

Write diagram definitions as simple text files in your repo.
Commit and review them like any other source file.
Regenerate the visual diagram any time from that text.

This approach keeps diagrams in sync with the codebase, makes changes reviewable via pull requests, and integrates naturally with docs-as-code practices. FlowZap’s .fz format and FlowZap Code language are designed specifically to bring these benefits to workflows and sequence diagrams.

The `.fz` File Format: Text-First Sequence Diagrams

The new .fz format is a plain-text, UTF‑8 file that contains only FlowZap Code—no embedded images or binary data. An .fz file is the single source of truth for a diagram; FlowZap reads it and renders both workflow and sequence views from the same text.

Key characteristics:

Plain text: Easy to edit in any editor (VS Code, Cursor, Windsurf, etc.), easy to diff in Git.
Single diagram per file: Each .fz describes one diagram, typically stored under /docs/.
Globally unique node IDs: n1, n2, … are unique across all lanes so the diagram engine can map steps unambiguously.
Strict but simple syntax: Lanes, nodes, edges, and loops are written in a small, consistent DSL that’s easy for LLMs to follow.

A tiny example:

User { # User
n1: circle label:"Start"
n2: rectangle label:"Submit"
n1.handle(right) -> n2.handle(left)
}
App { # App
n3: rectangle label:"Process"
n4: circle label:"Done"
n2.handle(bottom) -> App.n3.handle(top) [label="Send"]
n3.handle(right) -> n4.handle(left)
}

To render this, you load the .fz file into FlowZap; the app does the layout and visualization.

Save as `.fz` and Load `.fz` in FlowZap

To make this practical, FlowZap’s diagramming UI now exposes two core actions:

Save this FlowZap Code as .fz file: From any diagram, you can export the underlying FlowZap Code as an .fz text file. The typical pattern is to save it into a /docs/ or /architecture/ folder in your project so it can be version-controlled.
Load a .fz file: In the editor, you can load a .fz file from your machine into FlowZap, and it will render the corresponding diagram. The only requirement is that the file contains valid FlowZap Code.

A few important clarifications:

FlowZap does not scan your GitHub or GitLab repos directly.
You, the developer, control the .fz files via your editor and Git; FlowZap reads whatever .fz you choose to upload.
Any .fz file you generate with an LLM, commit, and later download can be loaded into FlowZap for visualization and further editing.

This keeps the architecture simple: Git remains your source of truth; FlowZap remains your visual engine.

`flowzap-code-guidelines.md`: An LLM-Ready Syntax Guide

To make .fz practical in AI-first coding environments, FlowZap provides an official, LLM-optimized guide at:

https://github.com/flowzap-xyz/code/blob/main/flowzap-code-guidelines.md

The idea is simple:

You copy this file into your project’s /docs/ folder.
In tools like Cursor, Windsurf, Warp, or Google AI Studio, you prompt your LLM with something like: “Refer to docs/flowzap-code-guidelines.md and output ONLY FlowZap Code for the authentication flow.”
The LLM uses the guide as its style and syntax authority and generates valid FlowZap Code, which you save as auth.fz.

The guidelines file includes:

A precise description of FlowZap Code syntax (lanes, nodes, edges, loops).
Clear Do / Don’t examples (e.g., label:"Text" for nodes vs. [label="Text"] for edges).
Minimal templates for single-lane flows, multi-lane interactions, decisions, loops, and taskboxes.
Prompting tips so humans can steer LLMs toward correct outputs.

Because the syntax is small and consistent, LLMs can hit high accuracy with just that one file as context.

How FlowZap’s Workflow Matches “Diagrams as Code” Best Practices

FlowZap’s .fz workflow lines up with generally accepted diagrams-as-code patterns:

Text in the repo, visuals in the tool: .fz files live under /docs/ or similar in your Git repo; they are just text. You edit them as part of your codebase and use FlowZap as the specialized renderer.
Version-controlled diagrams: Because .fz is plain text, every change to your diagrams is a Git change:
- You can review diffs on pull requests.
- You can branch, merge, and revert diagram changes alongside code.
- You can see exactly how your authentication or checkout flows evolved over time.
Docs-as-code alignment: Teams already using docs-as-code (MkDocs, Docusaurus, Sphinx, etc.) can treat .fz like any other source artifact in /docs/. Over time, you can script exports or screenshots if you want static images in your HTML docs.
AI-assisted authoring: Instead of hand-writing every FlowZap Code line, you prompt your LLM, which reads flowzap-code-guidelines.md and generates the .fz files for you. This is the “vibe coding” loop:
- Describe the flow in natural language.
- Get FlowZap Code back.
- Save as .fz and load into FlowZap.
Single source of truth for both views: Because FlowZap can show both a workflow view and a sequence view from the same FlowZap Code, you avoid duplicating diagrams. One .fz file becomes both a business process map and a technical interaction diagram.

Example: From Prompt to Diagram

Here’s what the workflow looks like for a typical developer:

Drop the guidelines into your repo: Copy flowzap-code-guidelines.md into /docs/.
Use your AI coding assistant: In Cursor or Windsurf or whatever, run a prompt like: “Refer to docs/flowzap-code-guidelines.md and output ONLY FlowZap Code for a user login flow: User enters credentials, App validates, Server checks DB, success or error with up to 3 retries.”
Create the .fz file Save the LLM’s response as docs/authentication.fz and commit it to your repo.
Render it in FlowZap: Open FlowZap in the browser, click Load .fz file, choose authentication.fz, and see the workflow and sequence views generated from your text.

Any later code change that impacts the flow? Update your .fz via another prompt (“Modify this FlowZap Code to add OAuth”) and reload it into FlowZap.

Why This Matters for Sequence Diagrams and AI Workflows

Most existing diagrams-as-code tools are either:

General-purpose (PlantUML, Mermaid) with heavier syntax and limited dual-view support, or
Focused on infrastructure/architecture rather than end-to-end business flows.

FlowZap takes a different path:

It specializes in workflows and sequence diagrams—the flows you care about for auth, payments, approvals, and AI agent interactions.
It provides a simple DSL that non-UML experts can grasp quickly.
It fits naturally into AI-assisted development, where LLMs write or update .fz files on demand.

If your team already stores code, docs, and infrastructure definitions in Git, .fz and FlowZap Code let you add sequence diagrams into that same, repeatable workflow—without giving up the visual clarity non-technical stakeholders need.

Getting Started in a Few Minutes

To try this in your own project:

Add flowzap-code-guidelines.md from https://github.com/flowzap-xyz/code/blob/main/flowzap-code-guidelines.md to your /docs/ folder.
Ask your LLM (Cursor, Windsurf, Warp, etc.) to generate FlowZap Code for a simple flow, referencing that file.
Save the result as something.fz under /docs/.
Go to flowzap.xyz, open the diagram editor, and use Load .fz file to visualize it.

From there, you can iterate on both the code and the diagram as your system evolves.

FlowZap Unveils .fz: True Diagrams as Code for Sequence Diagrams and AI-Native Workflows

What “Diagrams as Code” Really Means

The .fz File Format: Text-First Sequence Diagrams

Save as .fz and Load .fz in FlowZap

flowzap-code-guidelines.md: An LLM-Ready Syntax Guide