Architecture

AutoMFlows is built as a monorepo using npm workspaces, with a clear separation between backend execution, frontend interface, shared types, and AI integration capabilities.

Monorepo Structure

The project is organized into four main workspaces:

Backend

Node.js/Express server with Playwright-based execution engine

Frontend

React + ReactFlow visual workflow editor

Shared

TypeScript types and utilities shared across workspaces

MCP Server

Model Context Protocol server for AI/IDE integration

Backend Architecture

The backend is the core execution engine responsible for running workflows and managing browser automation.

Key Components

Execution Engine

Located in backend/src/engine/, this is the heart of AutoMFlows:

Executor (executor/core.ts): Main execution orchestrator that manages workflow lifecycle
WorkflowParser (parser.ts): Parses workflow JSON and builds dependency graphs
ContextManager (context.ts): Manages execution state, variables, and browser contexts
PlaywrightManager (utils/playwright.ts): Handles browser lifecycle and page management

// Simplified executor flow
export class Executor {
  private workflow: Workflow;
  private parser: WorkflowParser;
  private context: ContextManager;
  private playwright: PlaywrightManager;
  
  async execute() {
    const executionOrder = this.parser.getExecutionOrder();
    for (const nodeId of executionOrder) {
      const node = this.parser.getNode(nodeId);
      const handler = getNodeHandler(node.type);
      await handler.execute(node, this.context);
    }
  }
}

Node Handlers

Located in backend/src/nodes/, each node type has a dedicated handler:

Browser Nodes (browser.ts): OpenBrowser, Navigation, Context manipulation
Interaction Nodes (handlers/action.ts, handlers/type.ts): Click, type, form inputs
Data Nodes (handlers/elementQuery.ts, handlers/dataExtractor.ts): Extract text, attributes, structured data
Logic Nodes (logic.ts): JavaScript code execution, loops
API Nodes (api.ts): HTTP requests, cURL commands
Database Nodes (database.ts): Database connections and queries
Verification Nodes (handlers/verify.ts): Assertions for browser, API, and database

// Node handler interface (backend/src/nodes/base.ts:4)
export interface NodeHandler {
  execute(node: BaseNode, context: ContextManager): Promise<void>;
}

Utilities

VariableInterpolator (utils/variableInterpolator.ts): Resolves ${data.key} expressions
RetryHelper (utils/retryHelper.ts): Handles retry logic with exponential backoff
WaitHelper (utils/waitHelper.ts): Advanced waiting strategies (selector, URL, condition)
LocatorHelper (utils/locatorHelper.ts): Creates Playwright locators with modifiers
ReportGenerator (utils/reportGenerator/): Generates execution reports (HTML, Allure, JSON, JUnit, CSV, Markdown)

Server API

The backend exposes a RESTful API and WebSocket interface:

// Key endpoints (backend/src/server.ts)
POST /api/execute        // Execute workflow
POST /api/stop/:id       // Stop execution
GET  /api/status/:id     // Get execution status
GET  /api/workflows      // List workflows
GET  /api-docs           // Swagger documentation

// WebSocket events
execution_start          // Workflow execution started
node_start              // Node execution started
node_complete           // Node completed successfully
node_error              // Node failed
execution_complete      // Workflow completed

Frontend Architecture

The frontend provides an interactive visual workflow builder using React and ReactFlow.

Technology Stack

React 18

Modern React with hooks for component state management

ReactFlow

Node-based workflow editor with drag-and-drop canvas

Zustand

Lightweight state management for workflow data and execution state

Material-UI

Component library for consistent UI design

Monaco Editor

Code editor for JavaScript nodes and advanced configuration

Key Features

Visual Editor: Drag nodes from sidebar, connect with edges, configure properties
Real-time Execution Tracking: Live node highlighting via WebSocket
Builder Mode: Record browser actions and auto-generate nodes
Selector Finder: Visual element picker that generates optimal selectors
Report Viewer: Display execution results, screenshots, and accessibility snapshots

Shared Package

The shared workspace contains TypeScript definitions used by both backend and frontend:

Types
Node Data
Selector System

// shared/src/types.ts

// Node types (70+ node types defined)
export enum NodeType {
  START = 'start',
  OPEN_BROWSER = 'openBrowser',
  TYPE = 'type',
  ACTION = 'action',
  VERIFY = 'verify',
  // ... 65+ more types
}

// Workflow structure
export interface Workflow {
  nodes: BaseNode[];
  edges: Edge[];
  groups?: Group[];
  metadata?: WorkflowMetadata;
}

// Execution context
export interface ExecutionContext {
  page?: any;           // Playwright Page
  browser?: any;        // Playwright Browser
  data: Record<string, any>;
  variables: Record<string, any>;
}

// Each node type has a dedicated data interface
export interface TypeNodeData {
  selector: string;
  selectorType?: SelectorType;
  selectorModifiers?: SelectorModifiers;
  text: string;
  inputMethod?: 'fill' | 'type' | 'pressSequentially';
  timeout?: number;
  failSilently?: boolean;
  // Wait conditions
  waitForSelector?: string;
  waitForUrl?: string;
  waitForCondition?: string;
  // Retry configuration
  retryEnabled?: boolean;
  retryStrategy?: 'count' | 'untilCondition';
  // Property input connections
  _inputConnections?: { [key: string]: Connection };
}

// Supports multiple selector strategies
export type SelectorType = 
  | 'text'              // Auto-detect from text
  | 'css'               // CSS selectors
  | 'xpath'             // XPath expressions
  | 'getByRole'         // ARIA role
  | 'getByText'         // Text content
  | 'getByLabel'        // Form label
  | 'getByPlaceholder'  // Input placeholder
  | 'getByTestId'       // data-testid attribute
  | 'getByTitle'        // Title attribute
  | 'getByAltText';     // Alt text (images)

// Advanced selector modifiers
export interface SelectorModifiers {
  nth?: number;                    // Select nth element
  filterText?: string;             // Filter by text content
  filterSelector?: string;         // Filter by child selector
  chainSelector?: string;          // Scoped sub-query
  pierceShadow?: boolean;          // Shadow DOM piercing
}

MCP Server

The Model Context Protocol server enables AI assistants and IDEs to interact with AutoMFlows:

The MCP server exposes workflow management operations as structured tools that AI models can invoke, enabling natural language workflow creation and modification.

// MCP capabilities
- List available workflows
- Create new workflows
- Execute workflows programmatically
- Query execution results
- Generate workflow documentation

Data Flow

Here’s how data flows through the system during workflow execution:

Workflow Loading

Frontend loads workflow JSON → Backend receives via API

Parsing

WorkflowParser builds dependency graph and determines execution order

Execution

Executor iterates through nodes, calling appropriate handlers

State Management

ContextManager stores variables, page references, API responses

Real-time Updates

WebSocket events sent to frontend for live node highlighting

Report Generation

ExecutionTracker collects node results → Generates reports in multiple formats

Plugin System

AutoMFlows supports custom node types through a plugin architecture:

// Plugin structure
{
  "pluginId": "custom-plugin",
  "version": "1.0.0",
  "nodes": [
    {
      "type": "custom.myNode",
      "category": "custom",
      "handler": "./handler.js",
      "config": "./config.tsx"
    }
  ]
}

Built-in Plugins

Reusable Node: Define and execute reusable sub-workflows
Switch Node: Conditional branching based on UI state, API response, or JavaScript
Set Config Node: Set runtime configuration from workflow
Comment Box: Add annotations to canvas
Shortcut: Custom keyboard shortcuts in editor

Dependencies

Backend

Playwright: Browser automation engine (Chromium, Firefox, WebKit)
Express: HTTP server and REST API
Socket.io: Real-time WebSocket communication
Various DB clients: PostgreSQL, MySQL, MongoDB, SQLite, Oracle, SQL Server, Redis

Frontend

ReactFlow: Visual node editor library
Socket.io-client: Real-time execution updates
Monaco Editor: Code editing for JavaScript nodes
Material-UI: UI component framework

Shared

TypeScript: Type definitions shared across workspaces

Performance Considerations

Parallel Execution

Property input connections enable parallel node execution when dependencies allow

Context Isolation

Multiple browser contexts for concurrent workflow execution

Resource Management

Automatic browser cleanup and connection pooling for databases

Report Retention

Configurable report retention to manage disk usage (default: 10 reports)

Get Started

Core Concepts

Guides

Advanced

Monorepo Structure

Backend

Frontend

Shared

MCP Server

Backend Architecture

Key Components

Server API

Frontend Architecture

Technology Stack

Key Features

Shared Package

MCP Server

Data Flow

Plugin System

Dependencies

Backend

Frontend

Shared

Performance Considerations

Parallel Execution

Context Isolation

Resource Management

Report Retention

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

​Monorepo Structure

Backend

Frontend

Shared

MCP Server

​Backend Architecture

​Key Components

​Server API

​Frontend Architecture

​Technology Stack

​Key Features

​Shared Package

​MCP Server

​Data Flow

​Plugin System

​Dependencies

​Backend

​Frontend

​Shared

​Performance Considerations

Parallel Execution

Context Isolation

Resource Management

Report Retention

Build docs developers (and LLMs) love

Monorepo Structure

Backend Architecture

Key Components

Server API

Frontend Architecture

Technology Stack

Key Features

Shared Package

MCP Server

Data Flow

Plugin System

Dependencies

Backend

Frontend

Shared

Performance Considerations