metabuilder/workflowui/docs/START_GUIDE.md

WorkflowUI - Getting Started

Quick Start

1. Start the Development Server

cd /Users/rmac/Documents/metabuilder/workflowui
npm run dev

The server will start on http://localhost:3005 (or the next available port).

2. Open in Browser

Navigate to: http://localhost:3005

---

Features Available

Dashboard

• View all workflows
• Create new workflows
• Quick actions (edit, delete, duplicate)

Workflow Editor (React Flow)

• Drag-and-drop nodes
• Connect workflow steps
• Configure node properties
• Real-time preview

Project Canvas (NEW - Uses Fakemui!)

• Infinite canvas with workflow cards
• Drag-and-drop card positioning
• Zoom in/out controls
• Material Design 3 interface
• Responsive grid layout

Built-in Workflows

The system comes with example workflows:

• User Authentication Flow
• Data Processing Pipeline
• Email Notification System
• Payment Processing

---

Key Endpoints

Route	Purpose
/	Dashboard - view all workflows
/editor/:workflowId	Workflow editor (React Flow)
/project/:projectId	Project canvas (infinite canvas with cards)
/workspace	Workspace selector

---

Technology Stack

• Frontend: Next.js 14.2, React 18, TypeScript
• UI Components: Fakemui (Material Design 3)
• State Management: Redux + Custom Hooks
• Data: IndexedDB (offline-first) + Backend API
• Workflow Engine: Multi-language execution (TS, Python, Go, Rust, etc.)

---

Project Structure

workflowui/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── page.tsx            # Dashboard
│   │   ├── editor/[id]/        # Workflow editor
│   │   ├── project/[id]/       # Project canvas (NEW)
│   │   └── layout.tsx          # Root layout
│   ├── components/             # React components
│   ├── hooks/                  # Custom hooks
│   ├── services/               # API clients
│   ├── store/                  # Redux slices + middleware
│   ├── db/                     # IndexedDB schema
│   └── types/                  # TypeScript types
├── backend/                    # Flask API server
│   ├── server_sqlalchemy.py    # Main server
│   ├── models.py               # Database models
│   └── workflows/              # Workflow definitions
├── Dockerfile                  # Docker configuration
└── package.json

---

Creating Your First Workflow

1. Click "Create Workflow" on the dashboard
2. Enter workflow name (e.g., "My AI Pipeline")
3. Click "Create"
4. You're now in the workflow editor!

In the Workflow Editor:

• Drag nodes from the left panel onto the canvas
• Connect nodes by dragging from output → input ports
• Click nodes to configure parameters
• Click "Save" to persist your workflow

---

Available Node Types

Control Flow

• Trigger (start workflow)
• If/Then/Else (conditional branching)
• Loop (iterate over items)
• Wait (delay execution)

Data Operations

• Filter (filter arrays)
• Map (transform items)
• Reduce (aggregate data)
• Merge (combine datasets)

AI/ML

• ChatGPT (call Claude/GPT APIs)
• Image Generation (DALL-E, Midjourney)
• Embedding (vector embeddings)
• Classification (categorize data)

External Services

• HTTP Request (call APIs)
• Database (SQL queries)
• File Operations (read/write files)
• Email (send messages)

---

Running Workflows

1. Open a workflow in the editor
2. Click "Execute" button in the top toolbar
3. Provide input values if the workflow has parameters
4. Watch the execution in real-time
5. View results in the output panel

---

Exporting & Importing

Export Workflow as JSON

# Click the "Export" button in the workflow editor
# This downloads the workflow as a .json file

Import Workflow from JSON

# Drag a .json file onto the import zone
# Or click "Import" and select the file

---

Using with Docker

Build the Docker image:

docker build -t metabuilder-workflowui:latest .

Run the container:

docker run -p 3000:3000 \
  -e NEXT_PUBLIC_API_URL=http://localhost:5000 \
  metabuilder-workflowui:latest

---

Automating AI Workflows

Example: Content Generation Pipeline

1. Trigger: Webhook or scheduled time
2. Input: Topic, style, length
3. Process:
   • Call Claude API to generate content
   • Call image generation API for graphics
   • Format output as Markdown
4. Output: Send to email, save to file, or publish

Example: Data Analysis Pipeline

1. Trigger: New data file uploaded
2. Process:
   • Load CSV file
   • Filter by criteria
   • Calculate statistics
   • Generate visualizations
3. Output: Send report via email

Example: Workflow Orchestration

1. Trigger: Main workflow starts
2. Process:
   • Run multiple AI workflows in parallel
   • Combine results
   • Apply business logic
3. Output: Save to database or trigger other workflows

---

Troubleshooting

Port Already in Use

# Kill existing process
lsof -i :3005
kill -9 <PID>

# Or try a different port
PORT=3010 npm run dev

Database Errors

# Clear IndexedDB cache (in browser DevTools)
# Application > Storage > IndexedDB > Clear All

Build Errors

# Clear Next.js cache
rm -rf .next
npm run dev

---

Next Steps

1. ✅ Start the dev server: npm run dev
2. ✅ Open http://localhost:3005 in browser
3. ✅ Create your first workflow
4. ✅ Add nodes and connect them
5. ✅ Test execution
6. ✅ Save and export

---

Documentation

• Fakemui Components: See /fakemui/COMPONENT_GUIDE.md
• Migration Summary: See /fakemui/MIGRATION_SUMMARY.md
• Architecture: See CLAUDE.md in root
• Workflow Engine: See /workflow/README.md

---

Support

For issues or questions:

1. Check the logs: npm run dev (shows errors in real-time)
2. Check browser console: F12 → Console tab
3. Check Network tab: F12 → Network to see API calls
4. Review workflow definitions: /workflow/examples/

Happy workflow automation! 🚀