Skip to content

nickxar1/n2c

BranchesTags

Repository files navigation

Automation Platform

A lightweight, self-hosted automation platform for workflows, scheduling, and integrations.

Features

  • 🎯 Multi-Page Web UI: Full-featured web application with navigation, dashboard, execution history, and schedule management
  • 🚀 Visual Workflow Execution: Interactive graph visualization to execute and monitor workflows in real-time
  • ⚡ Live Node Highlighting: Real-time visual feedback with WebSocket - watch nodes light up as they execute
  • 📊 Dashboard: Overview with stats, recent executions, and quick access to workflows
  • 📜 Execution History: Browse, filter, and search through all workflow executions with detailed node-level data
  • 📅 Schedule Management: Full CRUD interface for cron-based schedules with visual cron builder
  • 🔄 Workflow Engine: Execute workflows defined as JSON with directed acyclic graphs (DAG)
  • 💾 Persistence: SQLite database tracks all executions, node results, errors, and performance metrics
  • 🌐 REST API + WebSocket: Express-based API with real-time Socket.io updates
  • 🤖 LLM Integration: Chat completions via OpenAI-compatible APIs (llama.cpp, LM Studio, OpenAI)
  • 🎨 ComfyUI Integration: Execute ComfyUI image generation workflows with dynamic input mapping
  • 🛠️ Visual Workflow Editor: Drag-and-drop node placement, connection drawing, save/load workflows from UI
  • 🔀 Conditional Routing: If/else branching with visual True/False output handles
  • 📂 Workflow Browser: Browse, search, duplicate, and manage saved workflows from a dedicated library page
  • 💾 Auto-Save: Debounced 2-second auto-save for previously-saved workflows with status indicator
  • 📥 Export/Import: Download workflows as JSON or upload JSON files into the editor
  • 📋 Copy/Paste: Ctrl+C/V to copy selected nodes (with internal edges) and paste with offset
  • ⌨️ Command Palette: Ctrl+K quick-add overlay with search and keyboard navigation
  • 🖱️ Double-Click to Add: Double-click empty canvas area to open command palette at cursor position
  • 📄 Templates: 5 pre-built workflow templates to start from (API, Data Processing, LLM, Conditional, Webhook)
  • 🔧 17 Built-in Nodes: Triggers, flow control, HTTP requests, data transformation, file operations, LLM, ComfyUI, Discord, email, CSV, regex, and more
  • 📏 Node Size Slider: Adjustable node scale (60%-160%) via toolbar slider
  • 🎨 Color-Coded Nodes: Visual distinction by type with dynamic status updates during execution
  • 🔒 Path Traversal Protection: File nodes validate paths stay within allowed directories
  • 🔑 Secret Field Masking: Passwords, API keys, and tokens are masked in the config panel
  • 📈 Real-Time Progress: Live progress counter and animated progress bar during execution
  • ✅ Custom Confirm Dialogs: Animated modal confirmations replacing browser confirm() dialogs
  • 📋 Copy-to-Clipboard: One-click copy on all JSON node outputs in execution results
  • 🎭 Smooth Animations: Entrance animations (fade + slide) on all modals and overlays
  • 🏷️ Node Type Icons: Per-type SVG icons in the visual editor node headers (17 icons)
  • 📁 Collapsible Palette: Clickable category headers in the node palette with auto-expand on search
  • 📊 Status Icons: Per-status visual indicators (pulsing dot, checkmarks, X marks) on status badges
  • 📄 Smart Pagination: Ellipsis pagination showing first/last + current ±1 with ... for gaps
  • 🔔 Toast Notifications: User-friendly success/error notifications throughout the UI
  • 🔍 Deep Inspection: Click any node to view detailed configuration and execution results
  • 🧩 Extensible: Easy to add custom node types
  • 📦 TypeScript: Type-safe workflow engine with full TypeScript support
  • 🗂️ Monorepo: Clean separation of concerns with packages for core, API, and web UI

Quick Start

Prerequisites

  • Node.js >= 18.0.0
  • pnpm >= 8.0.0

Installation

# Install dependencies
pnpm install

Visual Workflow Execution (Recommended)

Launch both the API server and web UI to execute workflows:

# From project root - starts both servers concurrently
pnpm dev:all

This starts:

Web UI Pages:

  • 🏠 Dashboard (/) - Overview with stats, recent executions, and active schedules
  • 📂 Workflows (/workflows) - Browse, search, duplicate, and manage saved workflows
  • ▶️ Execute Workflow (/execute) - Visual executor with real-time node highlighting
  • 🛠️ Workflow Editor (/editor) - Drag-and-drop visual workflow builder with node palette
  • 📜 Execution History (/history) - Browse and filter all workflow executions
  • 📅 Schedules (/schedules) - Manage cron-based workflow schedules
  • ⚙️ Settings (/settings) - Theme (light/dark/auto), API URL, auto-save interval, timezone

Key Features:

  • 📊 Interactive ReactFlow graph with zoom, pan, and drag
  • ⚡ Real-time node highlighting - Watch nodes light up blue while executing, turn green on success
  • 📈 Live progress counter - "3/5 nodes completed" updates in real-time
  • 🔄 WebSocket integration for instant execution updates
  • 📊 View detailed results with node-level timing and output
  • 🎨 Color-coded nodes by type with dynamic status animations
  • 🔍 Click nodes to view detailed configuration
  • 📁 Load workflow JSON files or try example workflows
  • 🗺️ Mini-map for easy navigation
  • 📋 Paginated execution history (50 per page) with smart ellipsis pagination
  • 📅 Visual cron builder with presets (every minute, hourly, daily, etc.)
  • 🔔 Toast notifications for all user actions
  • 💾 Auto-save with "Auto-saved HH:MM" status indicator
  • 📥 Export/import workflows as JSON files
  • 📋 Copy/paste nodes with Ctrl+C/V
  • ⌨️ Command palette (Ctrl+K) for quick node search and addition
  • 🖱️ Double-click canvas to add nodes at cursor position
  • 📏 Adjustable node sizes via toolbar slider
  • 📄 Start from pre-built templates
  • 📋 Copy-to-clipboard on all JSON outputs
  • 🎭 Smooth modal entrance animations
  • 🏷️ Per-type node icons in editor
  • 📁 Collapsible node palette categories
  • ✅ Custom confirm dialogs (no more browser alerts)
  • 📈 Animated execution progress bar

Running Workflows via CLI

Execute workflows directly from the command line:

# Run the example workflow
cd packages/core
pnpm cli ../../examples/simple-workflow.json

Project Structure

automation-platform/
├── packages/
│   ├── core/                 # Core workflow engine ✅
│   │   ├── src/
│   │   │   ├── engine/       # Workflow execution
│   │   │   ├── nodes/        # Node implementations
│   │   │   ├── storage/      # Database & repositories ✅
│   │   │   └── scheduler/    # Cron scheduler ✅
│   ├── api/                  # API server ✅
│   │   ├── src/
│   │   │   ├── routes/       # API endpoints ✅
│   │   │   └── middleware/   # Error handling ✅
│   ├── web/                  # Visual workflow viewer & executor ✅
│   └── workers/              # Worker implementations (coming soon)
├── examples/                 # Example workflows
├── data/                     # SQLite database (created at runtime)
├── output/                   # Generated output files
└── docs/                     # Documentation

Available Node Types (17)

Triggers

  • manual-trigger: Start workflow manually
  • webhook-trigger: Trigger workflow via HTTP webhook
    • Config: path (required), method (POST/GET/PUT), responseStatus, responseBody
    • Receives: { body, headers, query, method, path }

Flow Control

  • conditional: If/else branching based on input data
    • Config: field (required), operator (required: equals, not_equals, greater_than, less_than, contains, is_empty, is_truthy, etc.), value
    • Visual True/False output handles for routing downstream nodes
  • loop: Iterate over arrays in input data
    • Config: arrayField (required, dot notation path), outputField (default: "results"), maxIterations (default: 10000), script (optional per-item transform)
  • delay: Pause execution for a specified duration
    • Config: duration (required), unit (ms/seconds/minutes, default: seconds)
  • switch: Multi-way branching based on field value (up to 3 cases + default)
    • Config: field (required), case1Value, case2Value, case3Value
    • Visual output handles: case1 (blue), case2 (amber), case3 (violet), default (gray)

Actions

  • http-request: Make HTTP requests to APIs
    • Config: url, method, headers, body, params
    • Supports {{input.field}} templates in URL and body
  • data-transform: Transform data using mappings or custom scripts
    • Config: mappings (object) or script (JavaScript)
  • file-write: Write data to files
    • Config: path, content, field, encoding
  • file-read: Read files from disk
    • Config: path (required), encoding (default: utf8), parseAs (auto/json/text)
    • Auto-detects JSON by file extension
  • csv-read: Read and parse CSV/TSV files
    • Config: path (required), delimiter (comma/tab/semicolon/pipe), hasHeader (default: true), encoding
    • Output: { data: [...], rowCount, headers, path }
  • directory-scan: List files in a directory with optional glob filtering
    • Config: path (required), pattern (e.g., *.json), recursive (default: false)
    • Output: { files: [{name, path, size, modifiedAt}], count }
  • discord: Send messages via Discord Bot API
    • Config: botToken (required), channelId (required, supports {{input.field}} templates), content (supports templates), embeds
    • Auth: Authorization: Bot <token> header
  • email: Send emails via SMTP
    • Config: smtpHost (required), smtpPort, secure, username, password, from (required), to (required), subject (required), body, html
    • Supports {{input.field}} templates in to, subject, body, html
  • regex: Pattern matching and text extraction
    • Config: pattern (required), flags (default: g), inputField (required), mode (match/matchAll/replace/test/split), replacement
    • Supports {{input.field}} templates in pattern and replacement

AI & Generation

  • llm: Chat completions via OpenAI-compatible APIs
    • Config: baseUrl (required), userPrompt (required), systemPrompt, model, apiKey, temperature, maxTokens
    • Compatible with: llama.cpp server, LM Studio, OpenAI
    • Supports template variables in prompts: {{input.fieldName}}
  • comfyui: Execute ComfyUI image generation workflows
    • Config: workflow (required, ComfyUI API format), serverUrl, inputMappings, outputDir, timeout
    • Queues prompt, polls for completion, downloads output images

API Endpoints

Workflow Execution

  • POST /api/workflows/execute?persist=true - Execute workflow with persistence
  • GET /api/health - Health check

Execution History

  • GET /api/executions - List executions (supports filters: workflow_id, trigger_type, status, limit, offset)
  • GET /api/executions/:id - Get execution details with node results
  • DELETE /api/executions/:id - Delete execution

Schedule Management

  • GET /api/schedules - List all schedules
  • POST /api/schedules - Create schedule (requires: workflow_file_path, name, cron_expression)
  • GET /api/schedules/:id - Get schedule details
  • PUT /api/schedules/:id - Update schedule
  • POST /api/schedules/:id/pause - Pause schedule
  • POST /api/schedules/:id/resume - Resume schedule
  • DELETE /api/schedules/:id - Delete schedule

Webhooks

  • ALL /api/webhooks/:path - Trigger workflows with webhook-trigger nodes matching the path

Node Types

  • GET /api/node-types - List all available node type metadata (configFields, categories, colors)

Templates

  • GET /api/templates - List pre-built workflow templates

Scheduling Workflows

Create cron-based schedules to run workflows automatically:

curl -X POST http://localhost:4000/api/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_file_path": "../../examples/simple-workflow.json",
    "name": "Hourly Data Sync",
    "cron_expression": "0 0 * * * *",
    "timezone": "UTC"
  }'

Cron Format: <second> <minute> <hour> <day-of-month> <month> <day-of-week>

  • Every minute: 0 * * * * *
  • Every hour: 0 0 * * * *
  • Every day at midnight: 0 0 0 * * *

Execution History

View workflow execution history with full node-level details:

# List all executions
curl http://localhost:4000/api/executions

# Filter by trigger type
curl "http://localhost:4000/api/executions?trigger_type=schedule"

# Get execution details
curl http://localhost:4000/api/executions/<execution-id>

Execution records include:

  • Workflow metadata (ID, name, trigger type)
  • Execution status and timestamps
  • Duration metrics
  • Node-level results with input/output data
  • Error messages and stack traces

Example Workflows

The examples/ directory contains ready-to-use workflows:

  • simple-workflow.json - Fetch API data, transform, and save to file
  • data-processing-workflow.json - Multi-user data processing pipeline
  • llm-workflow.json - Fetch article from API and summarize with local LLM
  • comfyui-workflow.json - Generate images with ComfyUI from text prompts
  • llm-to-comfyui-workflow.json - LLM generates optimized prompt, then ComfyUI generates the image

All examples are also available in the web UI via the Examples dropdown.

LLM Setup

The LLM node works with any OpenAI-compatible API. Point baseUrl to your server:

Server Default baseUrl
llama.cpp http://localhost:8080/v1
LM Studio http://localhost:1234/v1
OpenAI https://api.openai.com/v1

ComfyUI Setup

  1. Start ComfyUI (default: http://localhost:8188)
  2. Export your workflow in API format (Enable Dev Mode in settings, then Save API Format)
  3. Paste the API JSON into the workflow config field
  4. Use inputMappings to inject dynamic values: { "6.inputs.text": "input.prompt" }

Creating a Workflow

Workflows are defined as JSON files:

{
  "id": "my-workflow",
  "name": "My Workflow",
  "description": "Optional description",
  "nodes": [
    {
      "id": "node-1",
      "type": "manual-trigger",
      "config": {}
    },
    {
      "id": "node-2",
      "type": "http-request",
      "config": {
        "url": "https://api.example.com/data",
        "method": "GET"
      }
    }
  ],
  "connections": [
    { "from": "node-1", "to": "node-2" },
    { "from": "node-3", "to": "node-4", "sourceHandle": "true" }
  ]
}

Development

# Build all packages
pnpm build

# Watch mode for development
pnpm dev

# Clean build artifacts
pnpm clean

Roadmap

  • Phase 1: Core workflow engine with basic nodes
  • Phase 2: Scheduler & persistence (SQLite, execution history, cron scheduling)
  • Phase 3: REST API server (execution, schedules, history endpoints)
  • Phase 4: Complete Web UI with real-time monitoring
    • Phase 4a: Navigation & Layout (multi-page routing, sidebar)
    • Phase 4b: Dashboard & Execution History (stats, browsing, filtering)
    • Phase 4c: Schedule Management (CRUD with visual cron builder)
    • Phase 4d: Real-Time Monitoring (WebSocket with live node highlighting)
  • Phase 5: LLM & ComfyUI integration (TypeScript HTTP nodes)
    • LLM node for OpenAI-compatible APIs (llama.cpp, LM Studio, OpenAI)
    • ComfyUI node for image generation workflows
    • Shared template utility with nested path support
    • Example workflows: LLM summarization, ComfyUI image gen, LLM-to-ComfyUI pipeline
  • Phase 6: Visual workflow editor (drag-and-drop creation)
    • ReactFlow-based drag-and-drop editor with node palette
    • Connection drawing, auto-layout, undo/redo
    • Save/load workflows from UI, workflow validation
    • Node config panel with per-type fields
  • Phase 7: Expanded node types (6 new nodes)
    • Conditional (if/else) with visual True/False branching
    • Loop/Iterator for array processing
    • Delay/Sleep for timed workflows
    • File Read with JSON auto-detection
    • Webhook Trigger with API endpoint
    • Discord message sender via Bot API
    • Engine support for conditional routing and node skipping
  • Phase 8: Editor polish & UX
    • Workflow browser/library page (/workflows) with search, duplicate, delete
    • Auto-save (debounced 2s for saved workflows)
    • Export/import workflow JSON
    • Copy/paste nodes (Ctrl+C/V with ID remapping)
    • Command palette (Ctrl+K) for quick node addition
    • 5 pre-built workflow templates with API endpoint
  • Phase 9: Settings & Dark Mode
    • Settings page with theme, API URL, auto-save interval, timezone
    • Dark mode with Tailwind darkMode: 'class' across all components
    • Flash prevention with inline localStorage script
  • Phase 10: Utility Nodes (csv-read, directory-scan, email, regex, switch)
  • Phase 11: Security & UX Polish
    • Path traversal protection on all file nodes (safePath utility)
    • Secret field masking for passwords/tokens in config panel
    • Loop node max iterations guard (default 10,000)
    • HttpRequestNode refactored to shared template utility
    • Double-click canvas to add nodes at cursor position
    • Hierarchical sidebar navigation (grouped sections)
    • Node size slider (60%-160%) in editor toolbar
    • Template loading bug fix (stale closure in auto-layout)
    • Drizzle ORM typed database export (AppDatabase)
  • Phase 12: UX Visual Polish
    • CSS animation utilities (fadeIn, slideUp) for all modals/overlays
    • StatusBadge with per-status icons (pulsing dot, checkmark, X, etc.)
    • Smart ellipsis pagination (first/last + current ±1 with ...)
    • StatCard accent borders + hover shadows
    • Sidebar active indicator (blue left border) + header gradient
    • Reusable ConfirmDialog component replacing browser confirm() calls
    • Relative timestamps in execution history ("2h ago" with full date below)
    • ScheduleCard color-coded left border (green=active, gray=paused)
    • Animated execution progress bar
    • Copy-to-clipboard on all JSON node outputs
    • Expand All / Collapse All toggle in execution results
    • Per-type SVG icons in CustomNode headers (all 17 node types)
    • Collapsible NodePalette categories with rotating chevron

License

MIT

About

automation project

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages