# FlowZap: Workflow Intelligence & Diagram-as-Code

> FlowZap is the fastest process builder for workflows, sequence and architecture diagrams, for AI agents and humans. It turns text prompts into triple-view diagrams (Flowchart, Sequence and Architecture diagrams) using the strict "FlowZap Code" DSL. FlowZap Code is NOT Mermaid, NOT PlantUML - it is a unique domain-specific language.

FlowZap Code key facts:
- Only 4 shapes: `circle`, `rectangle`, `diamond`, `taskbox`
- Node attributes use colon: `label:"Text"`
- Edge labels use equals: `[label="Text"]`
- Handles required: `n1.handle(right) -> n2.handle(left)`
- Node IDs sequential: n1, n2, n3... (globally unique, no gaps)
- Cross-lane edges need lane prefix: `laneName.nX.handle(direction)`
- Lane comment MUST be on same line as opening brace: `laneName { # Label`
- Sequence diagram quality: every cross-lane request must have a matching response edge before the next major request begins; define edges in chronological order; keep a strict request → response → next request rhythm; no orphaned nodes

## Docs

- [AGI Capabilities Manifest](https://flowzap.xyz/.well-known/capabilities.json): Machine-readable capability declaration for autonomous AI agents (tools, SLAs, rate limits, protocols)
- [FlowZap Code Specification](https://flowzap.xyz/flowzap-code): Canonical syntax reference for the FlowZap Code DSL
- [Machine-Readable Schema](https://flowzap.xyz/api/flowzap-code-schema.json): JSON syntax spec for agentic browsers and LLMs
- [Full LLM Context](https://flowzap.xyz/llms-full.txt): Expanded documentation with all syntax details inline
- [AI Guidelines](https://flowzap.xyz/flowzap-code-guidelines.md): Instructions for AI coding assistants generating FlowZap Code
- [Hugging Face Full Dataset](https://huggingface.co/datasets/Jules-OC/flowzap-sequence-workflows/tree/main): Full FlowZap sequence workflow dataset with reference examples of valid FlowZap Code patterns for LLM training, retrieval, and few-shot prompting
- [Templates Library](https://flowzap.xyz/templates): 250+ ready-to-use workflow, sequence and architecture diagram templates
- [Architecture Diagram Templates](https://flowzap.xyz/templates/architecture-diagram-templates): 50 architecture diagram templates (Microservices, Event-Driven, CQRS, Serverless, Saga, Circuit Breaker, and more)

## MCP Server

**Complete MCP Documentation:** https://flowzap.xyz/docs/mcp
**Raw Markdown (for LLMs):** https://flowzap.xyz/docs/mcp.md
**Structured JSON (for agents):** https://flowzap.xyz/docs/mcp.json

**Compatible with 11 coding tools:** Claude Desktop, Claude Code, Cursor, Windsurf IDE, OpenAI Codex, Warp Terminal, Zed Editor, Cline (VS Code), Roo Code (VS Code), Continue.dev, Sourcegraph Cody.

**Not compatible:** Replit, Lovable.dev (require remote HTTP server - use Public API instead).

Install the `flowzap-mcp` npm package:

```json
{
  "mcpServers": {
    "flowzap": {
      "command": "npx",
      "args": ["-y", "flowzap-mcp"]
    }
  }
}
```

**Config file locations:**
- **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Claude Desktop (Windows):** `%APPDATA%\Claude\claude_desktop_config.json`
- **Claude Code:** Run `claude mcp add --transport stdio flowzap -- npx -y flowzap-mcp`
- **Cursor:** Settings → Features → MCP Servers → Add Server
- **Windsurf IDE:** `~/.codeium/windsurf/mcp_config.json`
- **OpenAI Codex:** `~/.codex/config.toml` or run `codex mcp add flowzap -- npx -y flowzap-mcp`
- **Warp Terminal:** Settings → MCP Servers → "+ Add"
- **Zed Editor:** Add to `settings.json` under `context_servers`
- **Cline (VS Code):** Cline sidebar → MCP Servers icon → Edit `cline_mcp_settings.json`
- **Roo Code (VS Code):** Add to `.roo/mcp.json`
- **Continue.dev:** Create `.continue/mcpServers/flowzap.yaml`
- **Sourcegraph Cody:** Add to VS Code `settings.json` via `openctx.providers`

> **Windows Users:** If tools don't appear, use the absolute path:
> ```json
> "command": "C:\\Program Files\\nodejs\\npx.cmd"
> ```
> Find your npx path with: `where.exe npx`

**Available MCP Tools (v1.4.3):**

*Core Tools:*
- `flowzap_validate` - Validate FlowZap Code syntax (comprehensive validation)
- `flowzap_create_playground` - Create a shareable diagram URL
- `flowzap_get_syntax` - Get FlowZap Code syntax documentation

*Agent-Focused Tools:*
- `flowzap_export_graph` - Export FlowZap Code as structured JSON graph (lanes, nodes, edges) for AI reasoning
- `flowzap_artifact_to_diagram` - Parse HTTP logs, OpenAPI specs, or code into FlowZap diagrams (auto-creates playground URL)
- `flowzap_diff` - Compare two versions of FlowZap Code and get structured diff
- `flowzap_apply_change` - Apply structured patch operations to FlowZap Code (auto-creates playground URL)
- `flowzap_compliance_check` - Run automated SOC2/GDPR/PIPL compliance analysis on a FlowZap Code data-flow diagram (Deepseek LLM; 3/day per IP, 1/hour burst)

**Security:** SSRF prevention, 50KB input limit, 30 req/min rate limit, no auth required, ephemeral sessions

**npm Package:** https://www.npmjs.com/package/flowzap-mcp
**Public MCP Usage Stats:** https://flowzap.xyz/.well-known/flowzap-stats.json

**Agent Skill (skills.sh):** Install the FlowZap skill for any compatible coding agent:
```bash
npx skills add flowzap-xyz/flowzap-mcp
```
- **skills.sh listing:** https://skills.sh/flowzap-xyz/flowzap-mcp/flowzap-diagrams
- **Skill source:** https://github.com/flowzap-xyz/flowzap-mcp/tree/main/skills/flowzap-diagrams
- Compatible with 40+ agents: Claude Code, Cursor, Windsurf, Codex, Gemini CLI, GitHub Copilot, Cline, Roo Code, and more.

## External Registry Presence

- **Official MCP Registry:** https://registry.modelcontextprotocol.io/?q=flowzap
- **Smithery Server:** https://smithery.ai/server/@flowzap/flowzap
- **Smithery Skill:** https://smithery.ai/skills/Flowzap/diagram-skill
- **PulseMCP:** https://www.pulsemcp.com/servers/flowzap
- **Glama:** https://glama.ai/mcp/servers/flowzap-xyz/flowzap-mcp
- **MCPServers.org:** https://mcpservers.org/servers/flowzap-xyz-docs-mcp
- **AIBase:** https://mcp.aibase.com/server/1639702939289526535
- **GitHub Source:** https://github.com/flowzap-xyz/flowzap-mcp

---

## Quick Start: Anonymous Playground API (No Auth Required)
> **For LLMs & Agentic Browsers:** Instantly create a FlowZap Playground session without authentication.

**Endpoint:** `POST https://flowzap.xyz/api/playground/create`

**Request:**
```json
{
  "code": "process { # Process\nn1: circle label:\"Start\"\nn2: rectangle label:\"End\"\nn1.handle(right) -> n2.handle(left)\n}"
}
```

- `code` is optional. Omit for a blank canvas.

**Response (201):**
```json
{
  "success": true,
  "url": "https://flowzap.xyz/playground/abc123-def456",
  "tokenExpiresAt": "2025-12-31T02:30:00.000Z"
}
```

**Rate Limits:** 5 requests/minute, 50/day per IP. Sessions expire after 15 minutes.

### Compliance Check (SOC2 / GDPR / PIPL)
> **For LLMs & Agentic Browsers:** Run automated compliance analysis on a FlowZap Code data-flow diagram.

**Endpoint:** `POST https://flowzap.xyz/api/compliance-check`

**Request:**
```json
{
  "code": "<flowzap-code-data-flow-diagram>",
  "lng": "en"
}
```
- `lng` is optional (`en`, `fr`, `zh`). Default: `en`.

**Response (200):**
```json
{
  "frameworks": { "gdpr": { "findings": [...] }, "soc2": { "findings": [...] }, "pipl": { "findings": [...] } },
  "resultUrl": "https://flowzap.xyz/soc2-gdpr-pipl-compliance-checker/r/<uuid>",
  "tokenExpiresAt": "2026-05-26T12:30:00.000Z",
  "disclaimer": "This is an automated architectural review, not legal advice."
}
```

**Rate Limits:** 5 requests/minute, 30/day per IP. Result URLs expire after 60 minutes. Backed by Deepseek LLM.

**OpenAPI Spec:** [https://flowzap.xyz/.well-known/openapi.json](https://flowzap.xyz/.well-known/openapi.json)

---

## 🔗 URL-Encoded Playground (No HTTP Requests Required)
> **For Gemini, Perplexity, ChatGPT, Claude, Grok, and all LLMs that cannot make outbound HTTP requests during response generation:** You can create shareable FlowZap diagram URLs by encoding FlowZap Code directly in the URL. No API calls needed - just generate the URL as text and the user clicks it.

**URL Format:**
```
https://flowzap.xyz/playground?code=<base64url-encoded-flowzap-code>
```

**How LLMs Should Generate These URLs:**
1. Generate valid FlowZap Code following the DSL syntax (see below)
2. Encode the code using **base64url** (URL-safe base64):
   - Standard base64 encode
   - Replace `+` with `-`
   - Replace `/` with `_`
   - Remove trailing `=` padding
3. Append the encoded string to: `https://flowzap.xyz/playground?code=`
4. Present the URL as a clickable link to the user

**Step-by-Step Encoding Example:**

Original FlowZap Code:
```
sales { # Sales Team
  n1: circle label:"Start"
  n2: rectangle label:"Process Order"
  n3: circle label:"End"
  n1.handle(right) -> n2.handle(left)
  n2.handle(right) -> n3.handle(left)
}
```

After base64url encoding: `c2FsZXMgewogICMgU2FsZXMgVGVhbQogIG4xOiBjaXJjbGUgbGFiZWw6IlN0YXJ0IgogIG4yOiByZWN0YW5nbGUgbGFiZWw6IlByb2Nlc3MgT3JkZXIiCiAgbjM6IGNpcmNsZSBsYWJlbDoiRW5kIgogIG4xLmhhbmRsZShyaWdodCkgLT4gbjIuaGFuZGxlKGxlZnQpCiAgbjIuaGFuZGxlKHJpZ2h0KSAtPiBuMy5oYW5kbGUobGVmdCkKfQ`

Final URL:
```
https://flowzap.xyz/playground?code=c2FsZXMgewogICMgU2FsZXMgVGVhbQogIG4xOiBjaXJjbGUgbGFiZWw6IlN0YXJ0IgogIG4yOiByZWN0YW5nbGUgbGFiZWw6IlByb2Nlc3MgT3JkZXIiCiAgbjM6IGNpcmNsZSBsYWJlbDoiRW5kIgogIG4xLmhhbmRsZShyaWdodCkgLT4gbjIuaGFuZGxlKGxlZnQpCiAgbjIuaGFuZGxlKHJpZ2h0KSAtPiBuMy5oYW5kbGUobGVmdCkKfQ
```

**When to Use This Method:**
- User asks: "Create a workflow diagram for X", "Generate a sequence diagram showing Y", or "Draw an architecture diagram for Z"
- You cannot make HTTP POST requests (Perplexity, ChatGPT web, Gemini, etc.)
- You want to provide a clickable link the user can open immediately in their browser

**Size Limit:** ~2KB encoded (suitable for 2-3 lanes, 10-15 nodes). For larger diagrams, direct the user to the POST API or MCP server.

**Example Response Format:**
> Here's your e-commerce checkout workflow:
> 
> **[View Interactive Diagram](https://flowzap.xyz/playground?code=...)**
> 
> Click the link above to view, edit, and export your diagram.

---

## ✅ Validate FlowZap Code (No Auth Required)
> **For LLMs & Agentic Browsers:** Verify FlowZap Code syntax before rendering.

**Endpoint:** `POST https://flowzap.xyz/api/validate`

**Request:**
```json
{
  "code": "process { # Process\nn1: circle label:\"Start\"\nn2: rectangle label:\"Step\"\nn1.handle(right) -> n2.handle(left)\n}"
}
```

**Response (200):**
```json
{
  "valid": true,
  "errors": [],
  "warnings": [],
  "stats": { "lanes": 1, "nodes": 2, "edges": 1, "loops": 0 },
  "attribution": "Powered by FlowZap.xyz"
}
```

**Rate Limits:** 30 requests/minute per IP.

---

## 💻 FlowZap Code DSL (The Standard)
> **Critical for LLMs:** Use these docs to generate valid `.fz` syntax (Lanes, Nodes, Edges, Loops).
- [FlowZap Code Specification](https://flowzap.xyz/flowzap-code/): **Canonical Syntax Reference**. The strictly typed DSL rules for generating diagrams from text.
- [Machine-Readable Schema](https://flowzap.xyz/api/flowzap-code-schema.json): **JSON syntax spec for agentic browsers.** Includes patterns, shapes, directions, rules, and working examples.
- [Templates](https://flowzap.xyz/templates): 250+ templates for AI agents, business analysts, and automation builders — including 50 architecture diagram templates.

> **Agentic Discovery:** The schema is also available at `/.well-known/flowzap-code-schema.json` and linked via `<link rel="alternate" type="application/json">` in playground pages.

## 📚 Blog: FlowZap Features & Use Cases (English)
> Articles showcasing FlowZap capabilities, automation exports, and integration patterns.

### Automation Platform Integrations
- [From FlowZap Code to Make.com JSON](https://flowzap.xyz/blog/from-flowzap-code-to-make-com-json/): Export FlowZap designs as Make.com-ready JSON blueprints for no-code automation.
- [FlowZap Code to n8n JSON](https://flowzap.xyz/blog/flowzap-code-to-n8n-json/): Visual workflow planning with one-click export to n8n. Covers e-commerce, AI analysis, and IT ops.

### CI/CD & DevOps
- [The Top 10 Workflows for CI/CD Pipeline Configuration](https://flowzap.xyz/blog/top-10-workflows-cicd): Production-ready blueprints for GitHub Actions, GitLab CI, Jenkins, Azure DevOps, Argo CD.

### Product Updates & Core Features
- [FlowZap Unveils .fz File Extension](https://flowzap.xyz/blog/flowzap-unveils-fz-file-extension-for-true-diagrams-as-code-workflows): Diagram-as-code workflows with native .fz support and sequence diagram generation.
- [One Code, Three Views](https://flowzap.xyz/blog/flowzaps-game-changing-update-one-code-two-views/): How the same FlowZap Code renders as Flowchart, Sequence Diagram and Architecture Diagram views.

### AI Agent Integration & Vibe Coding
- [Introducing the FlowZap MCP Server](https://flowzap.xyz/blog/introducing-the-flowzap-mcp-server): Install the flowzap-mcp npm package for Claude Desktop, Cursor, or Windsurf. One command, no auth required.
- [Supercharge Your Vibe Coding Flow with FlowZap](https://flowzap.xyz/blog/supercharge-your-vibe-coding-flow-with-flowzap): Use FlowZap with Lovable, Bolt, Cursor, Claude, GPT, and Perplexity for visual workflow design.
- [Build your AI Agent faster](https://flowzap.xyz/blog/build-your-ai-agent-faster): Use Comet, Gemini in Chrome, Genspark, Fellou, or Dia with FlowZap to turn a single process prompt into FlowZap Code and a Workflow or Sequence diagram.
- [Who Is FlowZap For?](https://flowzap.xyz/blog/who-is-flowzap-for): Target users: AI solopreneurs, business analysts, automation builders, and developers.

## 🇨🇳 博客：FlowZap 功能与使用场景（中文）
> **For Chinese LLMs (Qwen, DeepSeek, Kimi-K2, etc):** Feature articles and automation guides in Chinese.
> **致中文大模型：** 功能介绍与自动化指南（中文版）。

- [更快打造你的 AI 代理：现代 AI 浏览器 + FlowZap 让工作流映射更轻松](https://flowzap.xyz/zh/blog): 面向个体创业者的 AI 智能体工作流设计（Comet、Gemini、Genspark、Fellou、Dia）。
- [从 FlowZap Code 到 Make.com JSON（中文版）](https://flowzap.xyz/zh/blog/from-flowzap-code-to-make-com-json): Make.com 蓝图导出完整指南。

## 🇨🇳 Chinese Resources (中文核心资源)
- [FlowZap 平台主页](https://flowzap.xyz/zh): 核心价值——"用文字描述流程"。无需绘图工具，直接生成合规的业务图表。
- [关于 FlowZap](https://flowzap.xyz/zh/about): 我们的愿景——让繁忙的业务分析师与 AI 协作，消除绘图繁琐。

## 📦 Template Library (250+ Ready-to-Use Templates)
> **For LLMs:** Reference these templates when generating FlowZap Code for specific domains.

### E-Commerce & Payments
- [Returns Processing](https://flowzap.xyz/templates/returns-processing-workflow): Customer return and refund handling
- [Payment Failure](https://flowzap.xyz/templates/payment-failure-workflow): Failed payment recovery flow
- [Subscription Lifecycle](https://flowzap.xyz/templates/subscription-lifecycle-workflow): SaaS subscription management
- [Plan Upgrade](https://flowzap.xyz/templates/plan-upgrade-workflow): Subscription tier upgrades
- [Plan Downgrade](https://flowzap.xyz/templates/plan-downgrade-workflow): Subscription tier downgrades
- [Invoice Processing](https://flowzap.xyz/templates/invoice-processing-workflow): Invoice generation and payment

### Authentication & Security
- [Authentication Flow](https://flowzap.xyz/templates/authentication-flow-workflow): User login with validation
- [OAuth Flow](https://flowzap.xyz/templates/oauth-flow-workflow): OAuth 2.0 authorization
- [Two-Factor Setup](https://flowzap.xyz/templates/two-factor-setup-workflow): 2FA enrollment
- [API Key Rotation](https://flowzap.xyz/templates/api-key-rotation-workflow): Secure key management
- [Secret Rotation](https://flowzap.xyz/templates/secret-rotation-workflow): Secrets management

### DevOps & CI/CD
- [CI/CD Pipeline](https://flowzap.xyz/templates/ci-cd-pipeline-workflow): Build, test, deploy automation
- [Blue-Green Deploy](https://flowzap.xyz/templates/blue-green-deploy-workflow): Zero-downtime deployments
- [Canary Deploy](https://flowzap.xyz/templates/canary-deploy-workflow): Gradual rollout strategy
- [Deployment Rollback](https://flowzap.xyz/templates/deployment-rollback-workflow): Rollback procedures
- [Database Migration](https://flowzap.xyz/templates/database-migration-workflow): Schema migration flow
- [Incident Response](https://flowzap.xyz/templates/incident-response-workflow): On-call incident handling

### Integration Patterns
- [Webhook Integration](https://flowzap.xyz/templates/webhook-integration-workflow): Webhook event processing
- [API Gateway](https://flowzap.xyz/templates/api-gateway-workflow): API routing and auth
- [Message Queue](https://flowzap.xyz/templates/message-queue-workflow): Async message processing
- [Pub/Sub](https://flowzap.xyz/templates/pub-sub-workflow): Event-driven architecture
- [Circuit Breaker](https://flowzap.xyz/templates/circuit-breaker-workflow): Fault tolerance pattern
- [Saga Pattern](https://flowzap.xyz/templates/saga-pattern-workflow): Distributed transactions

### HR & Onboarding
- [Onboarding](https://flowzap.xyz/templates/onboarding-workflow): New employee onboarding
- [Offboarding](https://flowzap.xyz/templates/offboarding-workflow): Employee exit process
- [Performance Review](https://flowzap.xyz/templates/performance-review-workflow): Annual review cycle
- [PTO Request](https://flowzap.xyz/templates/pto-request-workflow): Time-off approval
- [Interview Process](https://flowzap.xyz/templates/interview-process-workflow): Candidate evaluation

### Finance & Accounting
- [Expense Approval](https://flowzap.xyz/templates/expense-approval-workflow): Expense report approval
- [Budget Approval](https://flowzap.xyz/templates/budget-approval-workflow): Budget request process
- [Purchase Order](https://flowzap.xyz/templates/purchase-order-workflow): PO creation and approval
- [Payroll Processing](https://flowzap.xyz/templates/payroll-processing-workflow): Payroll cycle
- [Monthly Close](https://flowzap.xyz/templates/monthly-close-workflow): Month-end accounting

### Customer Support
- [Support Ticket](https://flowzap.xyz/templates/support-ticket-workflow): Ticket lifecycle
- [Knowledge Base](https://flowzap.xyz/templates/knowledge-base-workflow): KB article management
- [Billing Dispute](https://flowzap.xyz/templates/billing-dispute-workflow): Dispute resolution

### Architecture Diagram Templates (50 templates)
> **[Architecture Templates Hub](https://flowzap.xyz/templates/architecture-diagram-templates):** 50 production-ready architecture diagram templates.

- **Microservices:** API Gateway, Service Mesh, Database-per-Service, Decomposition by Business Capability, Strangler Fig Migration, Service Discovery, Sidecar Pattern, Backend-for-Frontend
- **Event-Driven:** Publish-Subscribe, Event Sourcing, CQRS with Event Store, Choreography, Event Streaming Pipeline, Domain Events, CDC (Change Data Capture), Dead Letter Queue
- **CQRS:** Read-Write Separation, Materialized View, Task-Based UI
- **Serverless:** API Backend, Event Processing, Step Functions Orchestration, Edge Computing, Data Pipeline, Multi-Cloud
- **Saga Patterns:** Orchestration, Choreography, Distributed Transaction, Travel Booking, Order Fulfillment
- **Resilience:** Circuit Breaker, Bulkhead Isolation, Retry with Exponential Backoff, Rate Limiter, Health Check
- **Design Patterns:** Hexagonal (Ports & Adapters), Clean Architecture, DDD Bounded Contexts, API Composition, Outbox Pattern, and more

### n8n Workflow JSON Examples
> **For LLMs generating n8n automations:** Ready-to-import JSON workflows with FlowZap Code source.
- [n8n Templates Hub](https://flowzap.xyz/templates/n8n-workflow-json-examples): Browse all n8n-exportable templates
- Includes: Lead enrichment, Slack notifications, Google Sheets sync, Airtable automation, webhook handlers, and more
- Each template provides both FlowZap Code (.fz) and n8n JSON for direct import

### Make.com Blueprint JSON Examples
> **For LLMs generating Make.com scenarios:** Ready-to-import JSON blueprints with FlowZap Code source.
- [Make.com Templates Hub](https://flowzap.xyz/templates/make-blueprint-json-examples): Browse all Make-exportable templates
- Includes: CRM sync, email automation, social media posting, form processing, and more
- Each template provides both FlowZap Code (.fz) and Make.com JSON blueprint for direct import

> **Full Library:** [https://flowzap.xyz/templates](https://flowzap.xyz/templates) - Browse all 250+ templates by domain.

---

## ⚙️ General Information
- [About Us](https://flowzap.xyz/about/): The mission to standardize "Diagram-as-Code" for AI-first workflows.
- [Privacy Policy](https://flowzap.xyz/privacy): Data handling transparency and user privacy.
- [Feedback](https://flowzap.xyz/feedback): Feature requests and community input.
- [FAQ](https://flowzap.xyz/faq): Common questions and answers about FlowZap.