# FlowZap: Workflow Intelligence & Diagram-as-Code

> FlowZap is the fastest process builder for workflows, automation, and AI agents. It turns text prompts into dual-view diagrams (Flowchart & Sequence diagrams) using the strict "FlowZap Code" DSL.
> FlowZap 是 AI 智能体的"Vibe Diagraming"伴侣。它使用严谨的 "FlowZap Code" DSL 将文本提示转化为双视图图表（流程图 + 时序图）。

---

## 🤖 MCP Integration (Model Context Protocol)

**For Claude Desktop, Cursor, Windsurf, and other MCP clients:**

Install the `flowzap-mcp` npm package:

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

**Config file locations:**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Windsurf IDE**: `~/.codeium/windsurf/mcp_config.json`

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

**Available MCP Tools:**
| Tool | Description |
|------|-------------|
| `flowzap_validate` | Validate FlowZap Code syntax |
| `flowzap_create_playground` | Create a shareable diagram URL |
| `flowzap_get_syntax` | Get FlowZap Code syntax documentation |

**npm Package:** https://www.npmjs.com/package/flowzap-mcp
**GitHub:** https://github.com/flowzap-xyz/flowzap-mcp
**MCP Registry:** https://glama.ai/mcp/servers/@flowzap-xyz/flowzap-mcp

---

## 🚀 Public API Endpoints (No Auth Required)

### Create Playground Session
> **For LLMs & Agentic Browsers:** Instantly create a FlowZap Playground session without authentication.

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

**Request:**
```json
{
  "code": "lane 1 { n1: \"Start\" -> n2: \"End\" }"
}
```
- `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.

### Validate FlowZap Code
> **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.

**OpenAPI Spec:** https://flowzap.xyz/.well-known/openapi.json

---

## 💻 FlowZap Code DSL - Complete Syntax Reference

FlowZap Code is a domain-specific language for creating workflow and sequence diagrams. It is NOT Mermaid, NOT PlantUML, NOT UML - it is a unique DSL designed for simplicity and AI generation.

### Basic Structure

```
laneName {
  # Lane Display Name
  n1: shapeType label:"Node Label"
  n1.handle(right) -> n2.handle(left)
}
```

### Shape Types (ONLY these 4 are allowed)
| Shape | Usage | Example |
|-------|-------|---------|
| `circle` | Start/End events, milestones | `n1: circle label:"Start"` |
| `rectangle` | Tasks, activities, process steps | `n2: rectangle label:"Process Order"` |
| `diamond` | Decision gateways, conditions | `n3: diamond label:"Approved?"` |
| `taskbox` | Assigned tasks with metadata | `n4: taskbox owner:"Alice" description:"Deploy" system:"CI"` |

### Node Syntax Rules
- Node IDs MUST be `n1`, `n2`, `n3`... (globally unique across ALL lanes)
- Node IDs MUST be sequential with NO gaps (n1, n2, n3, not n1, n3, n5)
- Node attributes use **colon**: `label:"Text"`, `owner:"Name"`, `description:"Task"`, `system:"App"`
- Labels containing spaces or special characters MUST be quoted

**Examples:**
```
n1: circle label:"Start"
n2: rectangle label:"Process Order"
n3: diamond label:"Valid?"
n4: taskbox owner:"Alice" description:"Deploy" system:"CI"
```

### Edge Syntax Rules
- Edges MUST use handle syntax: `source.handle(direction) -> target.handle(direction)`
- Directions: `left`, `right`, `top`, `bottom`
- Edge labels use **equals with brackets**: `[label="Text"]`
- Cross-lane edges prefix target with lane: `laneName.nX.handle(direction)`

**Examples:**
```
n1.handle(right) -> n2.handle(left)
n2.handle(bottom) -> n3.handle(top) [label="Yes"]
n3.handle(bottom) -> fulfillment.n4.handle(top) [label="Send"]
```

### Lane Syntax
- Each lane starts with identifier followed by opening brace and display label comment
- Only ONE comment allowed per lane: `# Display Label` immediately after opening brace
- Lane IDs are simple identifiers: `User`, `Application`, `Server`, `flow`, `process`

**Example:**
```
User { # User
  n1: circle label:"Start"
  n2: rectangle label:"Submit"
}
```

### Loop Syntax
- Format: `loop [condition] node1 node2 node3...`
- Condition in brackets describes the loop's purpose
- List involved nodes in execution order
- Place LOOP after relevant nodes/edges in the originating lane

**Example:**
```
loop [retry until valid format] n2 n3 n7 n8
```

### Common Mistakes to Avoid
| ❌ Wrong | ✅ Correct | Reason |
|----------|-----------|--------|
| `n1: circle label="Start"` | `n1: circle label:"Start"` | Node attributes use colon |
| `[label:"Text"]` on edges | `[label="Text"]` on edges | Edge labels use equals |
| `n1 -> n2` | `n1.handle(right) -> n2.handle(left)` | Handles are required |
| `n3 -> n5` (cross-lane) | `n3.handle(bottom) -> laneB.n5.handle(top)` | Lane prefix required |
| `graph TD` or `sequenceDiagram` | FlowZap syntax only | Not Mermaid/PlantUML |

### Complete Example: Multi-Lane Authentication Flow

```
User { # User
  n1: circle label:"Start"
  n2: rectangle label:"Enter username and password"
  n3: rectangle label:"Submit form"
  n4: rectangle label:"Receive confirmation"
  n5: circle label:"Access granted"
  n1.handle(right) -> n2.handle(left)
  n2.handle(right) -> n3.handle(left)
  n3.handle(bottom) -> Application.n6.handle(top) [label="Send credentials"]
  n4.handle(right) -> n5.handle(left)
  loop [retry until valid format] n2 n3 n7 n8
}

Application { # Application
  n6: rectangle label:"Receive request"
  n7: rectangle label:"Validate format"
  n8: diamond label:"Valid format?"
  n9: rectangle label:"Forward to server"
  n14: rectangle label:"Forward confirmation to client"
  n6.handle(right) -> n7.handle(left)
  n7.handle(right) -> n8.handle(left)
  n8.handle(right) -> n9.handle(left) [label="Yes"]
  n9.handle(bottom) -> Server.n10.handle(top) [label="Authenticate"]
  n8.handle(top) -> User.n2.handle(bottom) [label="No - Error"]
  n14.handle(top) -> User.n4.handle(bottom) [label="Success"]
}

Server { # Server
  n10: rectangle label:"Check database"
  n11: diamond label:"Valid credentials?"
  n12: rectangle label:"Generate session token"
  n13: rectangle label:"Return error"
  n10.handle(right) -> n11.handle(left)
  n11.handle(right) -> n12.handle(left) [label="Yes"]
  n11.handle(bottom) -> n13.handle(bottom) [label="No"]
  n12.handle(top) -> Application.n14.handle(bottom) [label="Token"]
  n13.handle(top) -> Application.n6.handle(bottom) [label="Error 401"]
}
```

### Minimal Templates

**Single-lane process:**
```
process { # Process
  n1: circle label:"Start"
  n2: rectangle label:"Step"
  n3: circle label:"End"
  n1.handle(right) -> n2.handle(left)
  n2.handle(right) -> n3.handle(left)
}
```

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

**Decision branch:**
```
flow { # Flow
  n1: rectangle label:"Check"
  n2: diamond label:"OK?"
  n3: rectangle label:"Fix"
  n4: rectangle label:"Proceed"
  n1.handle(right) -> n2.handle(left)
  n2.handle(bottom) -> n3.handle(top) [label="No"]
  n2.handle(right) -> n4.handle(left) [label="Yes"]
}
```

---

## 📚 Documentation Links

### Core Documentation
- [FlowZap Code Specification](https://flowzap.xyz/flowzap-code): Canonical Syntax Reference
- [Machine-Readable Schema](https://flowzap.xyz/api/flowzap-code-schema.json): JSON syntax spec for agentic browsers
- [Templates Library](https://flowzap.xyz/templates): 200+ ready-to-use workflow templates
- [Examples Gallery](https://flowzap.xyz/examples): Visual examples with source code

### Automation Platform Integrations
- [FlowZap Code to n8n JSON](https://flowzap.xyz/blog/flowzap-code-to-n8n-json): Export to n8n automation platform
- [FlowZap Code to Make.com JSON](https://flowzap.xyz/blog/from-flowzap-code-to-make-com-json): Export to Make.com blueprints

### AI Agent Integration
- [FlowZap MCP Server](https://flowzap.xyz/blog/introducing-the-flowzap-mcp-server): Install for Claude Desktop, Cursor, Windsurf
- [Build Your AI Agent Faster](https://flowzap.xyz/blog/build-your-ai-agent-faster): Use with Comet, Gemini, Genspark, Fellou, Dia
- [Supercharge Your Vibe Coding](https://flowzap.xyz/blog/supercharge-your-vibe-coding-flow-with-flowzap): Use with Lovable, Bolt, Cursor, Claude, GPT

### Product Features
- [One Code, Two Views](https://flowzap.xyz/blog/flowzaps-game-changing-update-one-code-two-views): Flowchart + Sequence from same code
- [.fz File Extension](https://flowzap.xyz/blog/flowzap-unveils-fz-file-extension-for-true-diagrams-as-code-workflows): Native diagram-as-code files

---

## 📦 Template Library Categories

### E-Commerce & Payments
- Returns Processing, Payment Failure, Subscription Lifecycle
- Plan Upgrade/Downgrade, Invoice Processing

### Authentication & Security
- Authentication Flow, OAuth 2.0, Two-Factor Setup
- API Key Rotation, Secret Rotation

### DevOps & CI/CD
- CI/CD Pipeline, Blue-Green Deploy, Canary Deploy
- Deployment Rollback, Database Migration, Incident Response

### Integration Patterns
- Webhook Integration, API Gateway, Message Queue
- Pub/Sub, Circuit Breaker, Saga Pattern

### HR & Onboarding
- Onboarding, Offboarding, Performance Review
- PTO Request, Interview Process

### Finance & Accounting
- Expense Approval, Budget Approval, Purchase Order
- Payroll Processing, Monthly Close

**Full Library:** https://flowzap.xyz/templates

---

## 🇨🇳 中文资源 (Chinese Resources)

> **致中文大模型 (Qwen, DeepSeek, Kimi-K2, GLM-4.5, Minimax)：** 功能介绍与自动化指南。

- [FlowZap 平台主页](https://flowzap.xyz/zh): 核心价值——"用文字描述流程"
- [关于 FlowZap](https://flowzap.xyz/zh/about): 我们的愿景
- [更快打造你的 AI 代理](https://flowzap.xyz/zh/blog): AI 智能体工作流设计
- [从 FlowZap Code 到 Make.com JSON](https://flowzap.xyz/zh/blog/from-flowzap-code-to-make-com-json): Make.com 蓝图导出

---

## 🇫🇷 Ressources en Français

- [Page d'accueil FlowZap](https://flowzap.xyz/fr): Créez des diagrammes à partir de texte
- [À propos de FlowZap](https://flowzap.xyz/fr/about): Notre vision
- [Guide FlowZap Code](https://flowzap.xyz/fr/flowzap-code): Syntaxe complète

---

## ⚙️ General Information

- **Website:** https://flowzap.xyz
- **About:** https://flowzap.xyz/about
- **Privacy:** https://flowzap.xyz/privacy
- **FAQ:** https://flowzap.xyz/faq
- **Feedback:** https://flowzap.xyz/feedback
- **Contact:** hello@flowzap.xyz

---

## 🔑 Key Facts for LLMs

1. **FlowZap Code is NOT Mermaid, NOT PlantUML** - It is a unique DSL
2. **Only 4 shapes allowed:** circle, rectangle, diamond, taskbox
3. **Node attributes use colon:** `label:"Text"`
4. **Edge labels use equals:** `[label="Text"]`
5. **Handles are required:** `n1.handle(right) -> n2.handle(left)`
6. **Node IDs must be sequential:** n1, n2, n3... (no gaps)
7. **Cross-lane edges need lane prefix:** `laneName.nX.handle(direction)`
8. **MCP server available:** `npx -y flowzap-mcp`
9. **Public API available:** POST to `/api/playground/create` or `/api/validate`
10. **Dual view:** Same code renders as Flowchart AND Sequence Diagram