ddflow

v1.4.0

Published

13 days ago

22+ diagram types from simple text DSL - Mind maps, flowcharts, ERD, architecture, wireframes and more. 100% client-side with drag & drop support.

✨ Why DDFlow?

| Feature | Mermaid | DDFlow | |---------|---------|--------| | Diagram types | 13 | 22+ | | Drag & drop nodes | ❌ | ✅ | | Simple syntax | ❌ Complex | ✅ Intuitive | | Interactive | ❌ Static | ✅ Pan/Zoom | | Wireframes | ❌ | ✅ 35+ elements | | Dark theme | Partial | ✅ Beautiful | | Bundle size | ~200KB | ~50KB | | Server required | Sometimes | Never |

🌐 100% Client-Side

DDFlow runs entirely in the browser. No server, no API calls, no data leaving your machine.

✅ DSL Parsing      → Browser JavaScript
✅ Layout Engine    → Client-side calculations
✅ Rendering        → React + SVG
✅ Interactions     → Mouse events + state
✅ Data             → In-memory (React state)

🚀 Quick Start

Installation

npm install ddflow
# or
yarn add ddflow
# or
pnpm add ddflow

Basic Usage

import { DDFlow } from 'ddflow';

function App() {
  return (
    <DDFlow
      type="mindmap"
      source={`
        Project Plan
          Research
            Market Analysis
            User Interviews
          Design
            Wireframes
            Prototypes
          Development
            Frontend
            Backend
      `}
    />
  );
}

CDN Usage (No Build Tools)

<!-- Required: React and ReactDOM -->
<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>

<!-- DDFlow UMD build -->
<script src="https://unpkg.com/ddflow/dist/ddflow.umd.js"></script>

<div id="diagram"></div>
<script>
  const { UniversalDiagram, Parsers } = DDflow;

  // Render a diagram
  const container = document.getElementById('diagram');
  const root = ReactDOM.createRoot(container);
  root.render(
    React.createElement(UniversalDiagram, {
      type: 'flowchart',
      data: '(start) Begin -> (process) Process -> (end) End'
    })
  );
</script>

📊 Diagram Types

🧠 Mind Map

Project
  Goals
    Revenue
    Growth
  Features
    Auth
    Dashboard

🏗️ Architecture

[clients] Web, Mobile
[gateway] API Gateway
[services] Auth, Users
[databases] PostgreSQL

Web -> API Gateway
API Gateway -> Auth

📈 Flowchart

(start) Begin
Begin -> (decision) Valid?
Valid? -> (end) Success
Valid? -> (process) Retry

🔄 Sequence

participant Client, API, DB

Client -> API: Request
API -> DB: Query
DB --> API: Result
API --> Client: Response

📊 ERD

CREATE TABLE users (
  id UUID PRIMARY KEY,
  email VARCHAR(255),
  name VARCHAR(100)
);

CREATE TABLE posts (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users
);

🚶 User Journey

[actor] User
[page] Landing
[action] Sign Up
[page] Dashboard

User -Visit-> Landing
Landing -Click-> Sign Up
Sign Up -Complete-> Dashboard

⚡ State Machine

(initial) Idle

Idle -> Loading: FETCH
Loading -> Success: RESOLVE
Loading -> Error: REJECT
Error -> Idle: RETRY

📅 Timeline

[Q1] *Kickoff | Started
[Q2] Design | Complete
[Q3] *MVP | Launched
[Q4] Scale | Growth

| Type | Description | Key Syntax | |------|-------------|------------| | mindmap | Hierarchical mind maps | Indentation-based | | architecture | System architecture | [layer] components | | erd | Entity Relationship | SQL CREATE TABLE | | flowchart | Process flows | (type) Label → | | sequence | Sequence diagrams | A -> B: message | | state | State machines | State -> State: event | | journey | User journeys | [type] Node with connections | | timeline | Timelines | [date] Event \| description | | orgchart | Org charts | Indentation-based | | network | Network topology | [device] Name (IP) | | gantt | Gantt charts | Task, start, duration | | deployment | Deployment diagrams | Nested [type] Name | | pie | Pie charts | "Label": value | | quadrant | Quadrant charts | Label: [x, y] | | git | Git graphs | commit, branch, merge | | wireframe | UI wireframes | 35+ element types | | class | Class diagrams | class Name + members | | activity | Activity diagrams | :Action; with decisions | | usecase | Use case diagrams | actor + (use case) | | component | Component diagrams | [component] Name | | c4 | C4 diagrams | [person/system/container] | | requirement | Requirements | requirement Name {...} |

📱 Wireframe DSL

Build UI mockups with 35+ elements - perfect for rapid prototyping:

{App Title}
[[ Home | Products | About ]]

>> Home > Dashboard

# Welcome Back

<Card>
(@John Doe)
[search: Search products...]
[v Select Category]
[slider: 65%]

|Name|Status|Amount|
|Order #1|Shipped|$120|
|Order #2|Pending|$85|

[progress: 78%]

[Submit] [Cancel] [Delete]
</>

@user1 liked your post • 2m ago
@user2 commented: Great work!

{badge:New} {success:Active} {warning:Review}

| Category | Elements | Syntax | |----------|----------|--------| | Layout | Window, Card, Modal | {Title}, <Card>...</>, {{Modal}} | | Navigation | Navbar, Tabs, Breadcrumbs | [[ a \| b ]], (( tab1 \| tab2 )), >> Home > Page | | Forms | Input, Textarea, Dropdown, Search | "placeholder", [""" text], [v Options], [🔍 Search] | | Controls | Button, Toggle, Checkbox, Radio | [Btn], [O] On, [x] Check, (O) Radio | | Feedback | Progress, Alert, Badge, Rating | [progress: 75%], [!] Error, {success:Done}, [★★★☆☆] | | Data | Table, List, Feed | \|a\|b\|, - item, @user text | | Media | Image, Video, Map, Chart | [img], [video], [map], [chart] | | Navigation | Stepper, Pagination | [step: 2/5], [page: 3/10] |

🎮 Interactive Features

Drag & Drop

Click and drag any node to reposition it. The layout adapts automatically.

Pan & Zoom

Scroll to zoom in/out
Click + drag on empty space to pan
Reset button to restore default view

Controls

┌─────────────────────────────────┐
│  [+] [-] [Fit] [Reset]    75%   │
│                                 │
│     Drag nodes • Scroll to      │
│     zoom • Drag canvas to pan   │
└─────────────────────────────────┘

🎨 Customization

Themes

<DDFlow
  type="mindmap"
  source="..."
  theme="dark"  // 'dark' | 'light'
/>

Custom Colors

import { DDFlow, createTheme } from 'ddflow';

const customTheme = createTheme({
  colors: {
    primary: '#8B5CF6',
    secondary: '#0EA5E9',
    success: '#10B981',
  },
  background: '#0f0f1a',
});

<DDFlow theme={customTheme} ... />

Controlled Mode

import { DDFlow, useDDFlowState } from 'ddflow';

function App() {
  const { positions, setPositions, zoom, setZoom } = useDDFlowState();
  
  return (
    <DDFlow
      type="architecture"
      source={source}
      positions={positions}
      onPositionChange={setPositions}
      zoom={zoom}
      onZoomChange={setZoom}
    />
  );
}

🔧 API Reference

`<DDFlow />`

| Prop | Type | Default | Description | |------|------|---------|-------------| | type | DiagramType | required | Diagram type | | source | string | - | DSL source text | | data | object | - | Pre-parsed data | | theme | 'dark' \| 'light' \| Theme | 'dark' | Color theme | | width | string \| number | '100%' | Container width | | height | string \| number | '100%' | Container height | | className | string | - | CSS class | | interactive | boolean | true | Enable drag/pan/zoom | | onNodeClick | (node) => void | - | Node click handler | | onPositionChange | (positions) => void | - | Position change handler |

Parsers

import { parsers } from 'ddflow';

const mindmapData = parsers.mindmap(source);
const erdData = parsers.erd(sqlSource);
const flowData = parsers.flowchart(source);
const wireframeData = parsers.wireframe(source);

Utilities

import { exportToPNG, exportToSVG } from 'ddflow';

// Export diagram
const png = await exportToPNG(diagramRef);
const svg = await exportToSVG(diagramRef);

🤖 AI Integration

DDFlow provides exportable DSL references for AI-powered diagram generation. Use these with any LLM (GPT-4, Claude, etc.) to generate correct DSL.

Using DSL Reference with Your AI

import {
  DSL_REFERENCE,        // Complete DSL syntax documentation
  AI_PROMPT_TEMPLATE,   // Ready-to-use AI prompt
  createAIPrompt,       // Function to create prompts
  getDSLForType,        // Get syntax for specific type
  getCompactReference   // Shorter reference for token limits
} from 'ddflow';

// Option 1: Use the complete AI prompt template
const prompt = AI_PROMPT_TEMPLATE.replace('{USER_INPUT}', 'Create an e-commerce architecture');

// Option 2: Create a custom prompt
const myPrompt = createAIPrompt('Draw a user authentication flowchart');

// Option 3: Get syntax for specific diagram type
const archSyntax = getDSLForType('architecture');

// Option 4: Use compact reference (for token-limited contexts)
const shortRef = getCompactReference();

Example: Using with OpenAI

import { createAIPrompt, Parsers } from 'ddflow';

async function generateDiagram(description) {
  const prompt = createAIPrompt(description);

  const response = await openai.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: prompt }]
  });

  const dsl = response.choices[0].message.content;
  const type = dsl.match(/<!-- type: (\w+) -->/)?.[1] || 'flowchart';
  const data = Parsers[type](dsl);

  return { type, data, dsl };
}

Architecture Diagram with Boundaries (C4 Style)

title: E-Commerce Platform
subtitle: Container Diagram

[person] Customer: Online shopper
[external] Payment Gateway: Stripe

boundary "Web Layer" {
  [webapp] Web App: React SPA
  [mobileapp] Mobile App: React Native
}

boundary "Services" {
  [service] User Service: Authentication
  [service] Order Service: Order management
}

boundary "Data Layer" {
  [database] PostgreSQL: Primary DB
  [cache] Redis: Session cache
}

Customer -> Web App: Uses
Web App -> User Service: API calls
Order Service -> PostgreSQL: Writes

📦 Individual Components

Import only what you need for smaller bundles:

import { MindMap } from 'ddflow/mindmap';
import { Flowchart } from 'ddflow/flowchart';
import { ERD } from 'ddflow/erd';
import { Wireframe } from 'ddflow/wireframe';
import { Architecture } from 'ddflow/architecture';

🌐 Framework Support

Next.js

'use client';

import dynamic from 'next/dynamic';

const DDFlow = dynamic(() => import('ddflow'), { ssr: false });

export default function Diagram({ source }) {
  return <DDFlow type="mindmap" source={source} />;
}

Vanilla JS

<!-- Load React (required peer dependency) -->
<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
<script src="https://unpkg.com/ddflow/dist/ddflow.umd.js"></script>

<div id="diagram" style="width: 800px; height: 600px;"></div>
<script>
  const { UniversalDiagram } = DDflow;
  const container = document.getElementById('diagram');
  const root = ReactDOM.createRoot(container);

  root.render(
    React.createElement(UniversalDiagram, {
      type: 'architecture',
      data: `
        [clients] Web, Mobile
        [services] API, Auth
        Web -> API
      `
    })
  );
</script>

Vue (Coming Soon)

<template>
  <DDFlow type="flowchart" :source="source" />
</template>

🛠️ Development

# Clone
git clone https://github.com/ddflow/ddflow
cd ddflow

# Install
npm install

# Dev server
npm run dev

# Run playground
npm run playground

# Build
npm run build

# Test
npm test

📋 Roadmap

[x] 22 diagram types
[x] Drag & drop nodes
[x] Pan & zoom
[x] Dark theme
[x] 100% client-side
[ ] Light theme
[ ] Export PNG/SVG/PDF
[ ] Mermaid import
[ ] VS Code extension
[ ] Figma plugin
[ ] AI diagram generation
[ ] Real-time collaboration

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

# Create feature branch
git checkout -b feature/amazing-feature

# Make changes & test
npm test

# Submit PR

💬 Community

Discord - Chat with the community
GitHub Discussions - Ask questions
Twitter - Follow for updates

👨‍💻 Author

Durgesh Dandotiya (DD)

GitHub: @durgeshdandotiya
Twitter: @ddaborat
Website: sdlc.dev