### Install and Run OpenFlowKit Development Server

Source: https://github.com/vrun-design/openflowkit/blob/main/CONTRIBUTING.md

Commands to install project dependencies, start the development server, and run various test suites for OpenFlowKit. These commands are essential for setting up the local development environment.

```bash
npm install
npm run dev          # http://localhost:5173
npm test
npm run test:watch
npm run e2e
npm run lint
```

--------------------------------

### Initialize Development Environment

Source: https://github.com/vrun-design/openflowkit/blob/main/README.md

Standard commands to set up the local development environment. This includes installing dependencies, starting the development server, and running quality assurance checks.

```bash
npm install
npm run dev
npm test
npm run lint
```

--------------------------------

### Run OpenFlowKit Locally

Source: https://github.com/vrun-design/openflowkit/blob/main/README.md

Instructions to clone the repository, install dependencies, and start the development server for OpenFlowKit. Requires Node.js and npm.

```bash
git clone https://github.com/Vrun-design/openflowkit.git
cd openflowkit
npm install
npm run dev
# → http://localhost:5173
```

--------------------------------

### OpenFlowKit DSL - Complete Diagram Example

Source: https://github.com/vrun-design/openflowkit/blob/main/public/llms.txt

An example demonstrating the combination of metadata, nodes, edges, and groups to create a complete diagram using OpenFlowKit DSL.

```openflow
direction: LR

[start] start: App Launched
[browser] ui: Dashboard UI

group "Backend Services" {
  [process] api: API Gateway
  [decision] cache: Check Redis
  [process] db: Postgres Database
}

start -> ui
ui ->|fetch data| api
api --> cache
cache ->|hit| ui
cache ..>|miss| db
db ==>|return data| cache
```

--------------------------------

### Install OpenFlowKit Core

Source: https://github.com/vrun-design/openflowkit/blob/main/src/lib/README.md

Install the core package via npm to access the diagramming utilities and types.

```bash
npm install @vrun-design/openflowkit-core
```

--------------------------------

### Example AWS Architecture Prompt for AI Drafting

Source: https://github.com/vrun-design/openflowkit/blob/main/docs-site/src/content/docs/aws-architecture.md

This is an example prompt to guide AI in generating an AWS architecture diagram. It specifies the services, their roles, and the desired traffic flow representation.

```text
Create an AWS architecture diagram for a three-tier web app with:
Route 53, CloudFront, ALB, ECS services, RDS PostgreSQL,
ElastiCache Redis, SQS worker queue, S3 assets bucket, and CloudWatch.
Show public ingress, internal service traffic, and async worker processing.
```

--------------------------------

### FlowMind DSL: Example Workflow Definition

Source: https://github.com/vrun-design/openflowkit/blob/main/DSL_MANUAL.md

A comprehensive example of a FlowMind DSL V2 file, demonstrating the integration of document headers, nodes with IDs and attributes, groups, and styled edges to define a user login workflow.

```yaml
flow: "User Login Flow"
direction: TB

# Define Nodes
[start] user: User
[process] login: Login Page { icon: "log-in" }

group "Authentication" {
    [system] auth: Auth Service
    [decision] check: Is Valid?
}

[end] dash: Dashboard
[end] err: Error

# Define Logic
user -> login
login -> auth
auth -> check

check ->|Yes| dash { color: "green" }
check ->|No| err { color: "red", style: "dashed" } // Dashed error path
```

--------------------------------

### OpenFlowKit Development Commands

Source: https://github.com/vrun-design/openflowkit/blob/main/README.md

Common npm scripts for developing and testing OpenFlowKit, including starting the dev server, building for production, linting, and running tests.

```bash
npm run dev           # Start dev server (localhost:5173)
npm run build         # Production build
npm run preview       # Preview production build locally
npm run bundle:check  # Analyze bundle size against budget
npm run lint          # ESLint (zero warnings allowed)
npm test -- --run     # Run all unit + integration tests once
```

--------------------------------

### Embed Diagram in Markdown

Source: https://github.com/vrun-design/openflowkit/blob/main/docs-site/src/content/docs/github-embed.md

Examples of how to link to an interactive OpenFlowKit diagram within a Markdown file. Includes both image-based previews and direct text links.

```markdown
[![Architecture Diagram](https://openflowkit.dev/og-diagram.png)](https://openflowkit.dev/#/view?flow=PASTE_ENCODED_VALUE_HERE)

[View Architecture Diagram →](https://openflowkit.dev/#/view?flow=PASTE_ENCODED_VALUE_HERE)
```

--------------------------------

### Generate and Edit Diagrams with AI

Source: https://context7.com/vrun-design/openflowkit/llms.txt

Provides examples for generating new diagrams, editing existing ones, and querying documentation using various AI providers. Supports streaming responses and cancellation via AbortSignal.

```typescript
import { generateDiagramFromChat, chatWithDocs } from '@/services/aiService';
import type { ChatMessage, AIProvider } from '@/services/aiService';

const chatHistory: ChatMessage[] = [];
const response = await generateDiagramFromChat(
  chatHistory,
  'Create an AWS serverless architecture with API Gateway, Lambda, and DynamoDB',
  undefined,
  undefined,
  'your-api-key',
  'gpt-4o',
  'openai',
  undefined,
  false,
  (delta) => console.log('Streaming:', delta),
  abortController.signal
);

const editResponse = await generateDiagramFromChat(
  chatHistory,
  'Add a caching layer with Redis between API Gateway and Lambda',
  existingDslString,
  undefined,
  apiKey,
  modelId,
  'claude',
  undefined,
  true
);

const docsResponse = await chatWithDocs(
  chatHistory,
  'How do I export a diagram as a cinematic GIF?',
  docsContextString,
  apiKey,
  modelId,
  'gemini'
);
```

--------------------------------

### OpenFlow DSL Example for AWS Architecture

Source: https://github.com/vrun-design/openflowkit/blob/main/README.md

This snippet demonstrates the OpenFlow DSL for defining an AWS architecture. It specifies services like Auth Service, API Gateway, and databases, along with their relationships and resource types. This format is human-readable and machine-parseable, enabling bidirectional editing between code and canvas.

```yaml
# Example: AWS architecture as code
Auth Service   [architecture] provider=aws resource=security
API Gateway    [architecture] provider=aws resource=api
Redis Cache    [architecture] provider=aws resource=database
Postgres DB    [architecture] provider=aws resource=database

Auth Service -> API Gateway
API Gateway  -> Redis Cache
API Gateway  -> Postgres DB
```

--------------------------------

### FlowMind DSL: Comments

Source: https://github.com/vrun-design/openflowkit/blob/main/DSL_MANUAL.md

Explains how to include comments in FlowMind DSL files. Lines starting with a '#' symbol are ignored by the parser, allowing for annotations and explanations within the code.

```plaintext
# This is a comment
[start] Begin
```

--------------------------------

### Define Rollout Flags in TypeScript

Source: https://github.com/vrun-design/openflowkit/blob/main/CONTRIBUTING.md

Example of how to define and use rollout flags in TypeScript for gating new features. This involves defining a type for flag keys and exporting a configuration object that reads flag values from environment variables.

```typescript
export type RolloutFlagKey = 'myFeature' | /* … */;

export const ROLLOUT_FLAGS = {
  myFeature: import.meta.env.VITE_ROLLOUT_MY_FEATURE === 'true',
};
```

--------------------------------

### Parse Diagrams and Generate Palettes with OpenFlowKit Core

Source: https://context7.com/vrun-design/openflowkit/llms.txt

Demonstrates the use of framework-agnostic utilities to parse Mermaid syntax and OpenFlow DSL into flow nodes and edges. Additionally, it shows how to generate a comprehensive color palette from a primary brand color.

```typescript
import { parseMermaid, parseOpenFlowDSL, generatePalette } from '@vrun-design/openflowkit-core';

const mermaidResult = parseMermaid(`
flowchart LR
  A[Input] --> B[Process] --> C[Output]
`);

const dslResult = parseOpenFlowDSL(`
[start] begin: Start
[process] step: Process Data
[end] finish: Complete

begin -> step -> finish
`);

const palette = generatePalette('#6366f1');
```

--------------------------------

### Testing Commands (Bash)

Source: https://github.com/vrun-design/openflowkit/blob/main/ARCHITECTURE.md

Provides essential commands for maintaining code quality and running tests within the project. Includes linting, unit/component tests, and end-to-end tests.

```bash
npm run lint
npm test -- --run
npm run e2e:ci
```

--------------------------------

### FlowMind DSL: Edge Styling with Attributes

Source: https://github.com/vrun-design/openflowkit/blob/main/DSL_MANUAL.md

Demonstrates how to apply specific styles and labels to edges in FlowMind DSL using attribute objects. This allows for detailed customization of connection appearance.

```plaintext
A -> B { style: "dashed", label: "Async" }
```

--------------------------------

### Generate Diagram from Text Prompt

Source: https://github.com/vrun-design/openflowkit/blob/main/docs-site/src/content/docs/quick-start.md

This snippet demonstrates how to use an AI prompt to generate a diagram. It's useful when the structure is not yet defined and a quick draft is needed. Ensure AI is configured with an API key for this functionality.

```text
Create a SaaS onboarding workflow with signup, email verification,
team invite, workspace creation, billing setup, and first success milestone.
```

--------------------------------

### Import Diagram as Code (OpenFlow JSON)

Source: https://github.com/vrun-design/openflowkit/blob/main/docs-site/src/content/docs/quick-start.md

This code snippet illustrates importing a diagram saved in OpenFlow JSON format. This is used for restoring a previously saved graph exactly as it was.

```json
{
  "diagram": {
    "nodes": [
      { "id": "1", "label": "Start" }
    ],
    "edges": []
  }
}
```

--------------------------------

### OpenFlowKit DSL - Node Definition

Source: https://github.com/vrun-design/openflowkit/blob/main/public/llms.txt

Defines nodes within the diagram, specifying their type, ID, label, and optional attributes. Supported node types include start, end, process, decision, system, note, browser, mobile, button, input, and placeholder.

```openflow
[start] start1: User Opens App
[browser] web: E-Commerce Store
[decision] checkAuth: Is Logged In?
[process] db: Query Database { icon: "database" }
```

--------------------------------

### Import Diagram as Code (Mermaid/OpenFlow DSL)

Source: https://github.com/vrun-design/openflowkit/blob/main/docs-site/src/content/docs/quick-start.md

This code snippet shows how to import a diagram defined using Mermaid or OpenFlow DSL. This method is ideal when you have existing diagram-as-code artifacts, allowing for editable and version-controlled diagrams.

```plaintext
graph TD
    A[Start] --> B{Process};
```

--------------------------------

### Generate Payment Recovery Flow via AI Prompt

Source: https://github.com/vrun-design/openflowkit/blob/main/docs-site/src/content/docs/payment-flow.md

A structured text prompt designed to generate a comprehensive SaaS subscription payment recovery flowchart using AI tools like Flowpilot.

```text
Create a payment recovery flow for a SaaS subscription.
Include invoice due, charge attempt, charge success decision,
smart retries, request updated card, manual fraud review,
customer notification, subscription active, and account downgrade.
```

--------------------------------

### FlowMind DSL: Node Styling with Attributes

Source: https://github.com/vrun-design/openflowkit/blob/main/DSL_MANUAL.md

Demonstrates how to customize node appearance in FlowMind DSL using JSON-like attribute objects. Attributes like 'color' and 'icon' can be specified within curly braces.

```plaintext
[process] p1: Critical Step { color: "red", icon: "alert-triangle" }
[system] db: Database { icon: "database" }
```

--------------------------------

### Manage Application State with Zustand

Source: https://context7.com/vrun-design/openflowkit/llms.txt

Demonstrates how to interact with the central Zustand store to manage canvas nodes, tabs, undo/redo history, design themes, AI configurations, and view settings.

```typescript
import { useFlowStore } from '@/store';

const { nodes, edges, setNodes, setEdges } = useFlowStore();

const { tabs, activeTabId, addTab, closeTab, updateTab } = useFlowStore();
const newTabId = addTab();
updateTab(activeTabId, { name: 'My Diagram', diagramType: 'flowchart' });

const { recordHistoryV2, undoV2, redoV2, canUndoV2, canRedoV2 } = useFlowStore();
recordHistoryV2();
if (canUndoV2()) undoV2();

const { designSystems, activeDesignSystemId, setActiveDesignSystem } = useFlowStore();
setActiveDesignSystem('custom-theme-id');

const { aiSettings, setAISettings } = useFlowStore();
setAISettings({
  provider: 'openai',
  apiKey: 'your-api-key',
  model: 'gpt-4o',
  storageMode: 'local'
});

const { viewSettings, setViewSettings, toggleGrid, toggleSnap } = useFlowStore();
setViewSettings({
  showGrid: true,
  snapToGrid: true,
  smartRoutingEnabled: true,
  architectureStrictMode: false
});
```

--------------------------------

### Manage Workspace Development and Builds

Source: https://github.com/vrun-design/openflowkit/blob/main/README.md

Commands to manage specific workspaces within the monorepo. These commands allow for targeted development servers and build processes for the documentation and marketing sites.

```bash
npm run dev --workspace=docs-site
npm run build --workspace=docs-site
npm run dev --workspace=web
npm run build --workspace=web
```

--------------------------------

### Generate Braintree Flow via Ask Flowpilot

Source: https://github.com/vrun-design/openflowkit/blob/main/docs-site/src/content/docs/payment-flow.md

An AI prompt template for generating a Braintree-specific subscription payment flowchart, detailing client token requests and transaction nonces.

```text
Generate a flowchart showing a subscription payment flow using Braintree. Include the client requesting a client token, the server generating it, the user submitting a nonce, and the final server-side transaction creation. Show both success and failure branches.
```

--------------------------------

### Manage Collaboration Sessions with WebRTC and Yjs

Source: https://context7.com/vrun-design/openflowkit/llms.txt

Initializes peer-to-peer collaboration sessions, manages local presence state, and merges presence snapshots from multiple peers. It relies on the @/services/collaboration module to handle CRDT-based state synchronization.

```typescript
import { createCollaborationSessionBootstrap, createLocalPresence, mergePresenceSnapshot } from '@/services/collaboration/session';
import type { CollaborationPresenceState } from '@/services/collaboration/types';

const session = createCollaborationSessionBootstrap({
  roomId: 'my-diagram-room-123',
  roomPassword: 'optional-password',
  clientId: 'user-unique-id',
  name: 'Alice',
  color: '#3b82f6'
});

const presence: CollaborationPresenceState = createLocalPresence(
  'client-id',
  'Bob',
  '#10b981'
);

const currentPresence: CollaborationPresenceState[] = [];
const incomingPresence: CollaborationPresenceState[] = [];
const merged = mergePresenceSnapshot(currentPresence, incomingPresence);
```

--------------------------------

### OpenFlowKit DSL - Metadata Configuration

Source: https://github.com/vrun-design/openflowkit/blob/main/public/llms.txt

Defines global diagram properties such as layout direction and theme. These settings apply to the entire diagram and should be placed at the top of the DSL file.

```openflow
direction: TB
theme: light
```

--------------------------------

### FlowMind DSL: Grouping Nodes

Source: https://github.com/vrun-design/openflowkit/blob/main/DSL_MANUAL.md

Illustrates how to group related nodes together in FlowMind DSL using the 'group' keyword. This helps in organizing complex diagrams and visually separating sections.

```plaintext
group "Backend Services" {
    [process] api: API Server
    [system] db: Database
    api -> db
}
```

--------------------------------

### Import TypeScript Types

Source: https://github.com/vrun-design/openflowkit/blob/main/src/lib/README.md

Access core type definitions for FlowNode, FlowEdge, and DesignSystem to ensure type safety in your implementation.

```typescript
import type { FlowNode, FlowEdge, NodeData, DesignSystem } from '@vrun-design/openflowkit-core';
```

--------------------------------

### FlowMind DSL: Basic Node Definition

Source: https://github.com/vrun-design/openflowkit/blob/main/DSL_MANUAL.md

Illustrates the fundamental syntax for defining nodes in FlowMind DSL. Nodes are declared using brackets with a type, followed by an optional label.

```plaintext
[start] Start Process
[process] Handle Request
[end] End Process
```

--------------------------------

### Collaboration Hooks and Services (TypeScript)

Source: https://github.com/vrun-design/openflowkit/blob/main/ARCHITECTURE.md

Implements real-time collaboration features using a peer-oriented, WebRTC-style transport. Includes fallback mechanisms for unsupported environments. This is an evolving area of active infrastructure.

```typescript
import { useFlowEditorCollaboration } from "./hooks/useFlowEditorCollaboration";
import { CollaborationService } from "./services/collaboration/CollaborationService";

// Example usage (conceptual)
const { collaborate } = useFlowEditorCollaboration();
const collaborationService = new CollaborationService();

collaborate(collaborationService);

```

--------------------------------

### Parse Mermaid DSL to React Flow

Source: https://context7.com/vrun-design/openflowkit/llms.txt

Demonstrates how to convert Mermaid.js syntax into React Flow nodes and edges. It supports both basic parsing and type-aware parsing with plugin dispatch for specific diagram types.

```typescript
import { parseMermaid } from '@/lib/mermaidParser';
import { parseMermaidByType } from '@/services/mermaid/parseMermaidByType';

const mermaidDsl = `
flowchart TD
  A[Start] --> B{Is user logged in?}
  B -- Yes --> C[Dashboard]
  B -- No  --> D[Login Page]
  D --> E[Validate Credentials]
  E --> B

  subgraph Authentication
    D
    E
  end
`;

const result = parseMermaid(mermaidDsl);
const typedResult = parseMermaidByType(mermaidDsl, {
  architectureStrictMode: false
});
```

--------------------------------

### ELK Layout Engine for Diagram Auto-Layout

Source: https://context7.com/vrun-design/openflowkit/llms.txt

A service wrapper for ELK.js to perform automated node and edge positioning. It supports multiple layout algorithms, directional constraints, and edge routing styles, as well as utility functions for rerouting edges after manual adjustments.

```typescript
import { getElkLayout, rerouteEdges, resolveLayoutPresetOptions } from '@/services/elkLayout';

const layoutOptions = {
  algorithm: 'layered',
  direction: 'TB',
  spacing: 80,
  edgeRouting: 'orthogonal'
};

const { nodes, edges } = await getElkLayout(nodes, edges, layoutOptions);
const presetOptions = resolveLayoutPresetOptions('hierarchical');
const result = await getElkLayout(nodes, edges, presetOptions);
const reroutedEdges = rerouteEdges(nodes, edges);
```

--------------------------------

### FlowMind DSL: Labeled Connections

Source: https://github.com/vrun-design/openflowkit/blob/main/DSL_MANUAL.md

Shows how to add labels to edges in FlowMind DSL using pipes or attributes. This is useful for indicating conditions or descriptions on connections.

```plaintext
Is Valid? ->|Yes| Save Data
Is Valid? ->|No| Return Error
```

--------------------------------

### Execute End-to-End Tests

Source: https://github.com/vrun-design/openflowkit/blob/main/README.md

Commands to run the Playwright end-to-end testing suite. Use the standard command for full coverage or the CI-specific command for Chromium-only headless testing.

```bash
npm run e2e
npm run e2e:ci
```

--------------------------------

### ELK Layout Engine

Source: https://context7.com/vrun-design/openflowkit/llms.txt

Service for applying automatic graph layouts to nodes and edges using ELK.js algorithms.

```APIDOC
## POST /services/elkLayout/apply

### Description
Calculates and applies an automatic layout to a set of nodes and edges.

### Method
POST

### Parameters
#### Request Body
- **nodes** (array) - Required - List of node objects.
- **edges** (array) - Required - List of edge objects.
- **options** (object) - Required - Layout configuration including algorithm ('layered', 'mrtree', 'force', 'radial') and direction ('TB', 'LR', 'RL', 'BT').

### Response
#### Success Response (200)
- **nodes** (array) - Nodes with updated coordinates.
- **edges** (array) - Edges with updated routing paths.
```

--------------------------------

### Define OpenFlow DSL Document Header

Source: https://github.com/vrun-design/openflowkit/blob/main/docs-site/src/content/docs/openflow-dsl.md

Sets the flow title and layout direction for the diagram. Supported directions include TB, LR, RL, and BT.

```yaml
flow: "User Signup"
direction: TB
```

--------------------------------

### FlowMind DSL: Edge Styles

Source: https://github.com/vrun-design/openflowkit/blob/main/DSL_MANUAL.md

Explains the different visual styles available for edges in FlowMind DSL, including default solid, dashed, and thick lines, represented by different arrow notations.

```plaintext
A ..> B  # Dashed connection
C ==> D  # Thick connection
```

--------------------------------

### Export Service for Diagram Serialization

Source: https://context7.com/vrun-design/openflowkit/llms.txt

A utility service to transform internal diagram nodes and edges into standard diagramming formats. Currently supports conversion to Mermaid flowchart syntax and PlantUML activity diagrams.

```typescript
import { toMermaid, toPlantUML } from '@/services/exportService';

const mermaidCode = toMermaid(nodes, edges);
const plantUmlCode = toPlantUML(nodes, edges);
```

--------------------------------

### Validate Project Before Wiring

Source: https://github.com/vrun-design/openflowkit/blob/main/assets/third-party-icons/aws/IMPORT_STEPS.md

Runs TypeScript compilation and specific unit tests to validate the project structure and functionality before integrating new assets. This ensures that the shape library ingestion pipeline and manifest validation logic are working correctly.

```bash
npx tsc -b --pretty false
npm run test -- --run \
  src/services/shapeLibrary/ingestionPipeline.test.ts \
  src/services/shapeLibrary/manifestValidation.test.ts \
  src/services/templates.selector.test.ts
```