Skip to main content
Figranium is a modular, event-driven automation platform built on top of the NodeJS ecosystem. It is designed to be self-contained and run on a single server, with optional scalability via container orchestration. At the heart of Figranium lies Figranite, a high-performance, deterministic workflow interpreter designed for sophisticated, stateful browser automation. It serves as the primary execution kernel, responsible for translating abstract block definitions into complex, human-like browser behaviors.

​
High-Level Overview

Figranium is composed of three main layers:

Frontend (UI)

React-based visual editor for building tasks, managing settings, and inspecting captures.

Backend (API & Runner)

Node.js and Express.js API that orchestrates execution and manages data persistence.

Browser Engine (Playwright)

Playwright and got-scraping power real browser interactions and lightweight scraping.

​
Frontend Layer

  • Technology: React, TypeScript, Vite, Tailwind CSS.
  • Purpose: Provides the visual interface for creating tasks, managing settings, viewing execution logs, and inspecting captured data.
  • Components:
    • Dashboard: Overview of tasks and recent activity.
    • Editor: A drag-and-drop block editor for defining automation logic.
    • Settings: Configuration panels for proxies, API keys, and system preferences.
    • Captures: Visual gallery for screenshots and video recordings.

​
Backend Layer

  • Technology: Node.js, Express.js.
  • Purpose: Serves the API, manages data persistence, and orchestrates browser automation.
  • Key Modules:
    • server.js: The main entry point, handling HTTP routes (/api/*) and WebSocket/SSE streams.
    • agent.js: The core logic for executing “Agent” mode tasks (complex flows with logic).
    • scrape.js: A lightweight, browserless runner for high-performance, single-page data extraction. It fetches HTML with got-scraping (with proxy and user-agent rotation) and parses it with Cheerio. No Playwright browser is launched.
    • headful.js: Manages interactive, visible browser sessions for debugging and manual intervention.
    • storage.js: Handles file-based persistence for tasks, executions, and settings.

​
Browser Engine Layer

  • Technology: Playwright (Chromium) for Agent and Headful modes; got-scraping + Cheerio for Scrape mode.
  • Purpose: Agent and Headful modes execute real browser interactions (clicking, typing, navigating). Scrape mode issues an HTTP request and parses the response DOM without a browser.
  • Features:
    • Context Isolation: Each Agent task runs in a fresh or persistent Playwright context, depending on configuration.
    • Stealth Plugin: Integrates puppeteer-extra-plugin-stealth in Agent mode to hide Playwright/Chromium fingerprints (navigator.webdriver and friends).
    • Cookie-Consent Auto-Dismissal: Every Agent page injects the idcac-playwright community ruleset on domcontentloaded and automatically clicks the “reject” or “close” button on known consent banners (OneTrust, Cookiebot, TrustArc, and hundreds more). See Stealth & Anti-Detection.
    • Network Interception: Captures network requests/responses for debugging and data extraction in Agent mode.

​
Figranite Engine

Unlike simple script-based runners, Figranite is a structured execution environment that manages task state, variable resolution, and environmental interaction through a modular architecture. It is built to handle everything from simple scraping to multi-step agentic workflows that require logic, looping, and error recovery.

​
Core Components

The engine is divided into several specialized modules:
  • Action Handler: Processes individual interaction blocks such as clicks, typing, navigation, and HTTP requests.
  • Logic Handler: Evaluates structured conditions and JavaScript expressions to drive decision-making.
  • Human Interaction Layer: Simulates organic user behavior, including non-linear mouse movements (Bezier curves), varying typing speeds, and “dead clicks” to evade bot detection.
  • Workflow Orchestrator: Manages the execution flow, including block mapping, jump logic (for loops and conditionals), and error handling state.

​
Key Features

Advanced Variable Templating

Figranite features a powerful template engine that allows for dynamic injection of data into any action property.
  • Syntax: {$variable_name}
  • Supports global variables, task-specific variables, and loop-local variables (e.g., loop.index, loop.item).
  • Built-in helpers like {$now} for timestamps.

Stealth & Humanization

One of Figranite’s standout features is its “sentient-like” interaction model. Instead of mechanical automation, it implements:
  • Human Typing: Simulates keystrokes with realistic delays and optional typos.
  • Cursor Glide: Moves the mouse across the page using natural paths rather than instant jumps.
  • Restlessness: Simulates idle cursor movements and scrolling during “wait” periods.
  • Randomized Target Selection: Clicks on slightly different parts of an element each time to avoid signature patterns.

Flow Control & Logic

The engine supports complex control structures that allow for non-linear execution:
  • Conditionals: if / else blocks based on page state or variable values.
  • Loops: while, repeat, and foreach (iterating over lists or DOM elements).
  • Error Handling: on_error blocks that allow workflows to recover gracefully from failures.

Intelligent Data Extraction

Figranite integrates tightly with a sandboxed extraction worker to parse DOM content. It supports:
  • Structured Extraction: Defining JSON schemas for data capture.
  • Shadow DOM Support: Seamlessly penetrating shadow roots to access encapsulated content.
  • Auto-Formatting: Converting results into JSON or CSV formats automatically.

​
Execution Lifecycle

1

Initialization

The engine loads the action sequence and initializes the runtimeVars.
2

Browser Setup

A new Playwright context is created with specific stealth configurations and user-agent rotation.
3

Block Mapping

The engine builds a jump map to handle control flow (e.g., finding the end of a loop or an else branch).
4

Step Execution

Each block is processed sequentially. For each step, the engine:
  • Resolves templates.
  • Reports progress via WebSockets/SSE.
  • Executes the specific action or logic.
  • Updates the block.output for the next step.
5

Finalization

The engine performs final data extraction, captures a terminal screenshot, and closes the browser context before returning the output payload.

​
Data Storage

Figranium uses a file-based storage system by default, keeping all data local to the deployment directory. This simplifies backup and migration.

​
Execution Flow

1

Trigger

A task is triggered via the UI or API (POST /api/tasks/:id/api).
2

Orchestration

The backend validates the request and spawns a new browser context.
3

Execution

The agent.js or scrape.js module executes the defined actions step-by-step.
4

Result

The browser captures screenshots, extracts data, and returns a JSON payload.
5

Persistence

The backend saves the execution log and any captured files to disk.

Action Blocks

Learn about the reusable blocks that power Figranite workflows.

Variables

Understand how dynamic data flows through tasks at runtime.

Control Flow

Explore conditionals, loops, and error recovery in workflows.

Data Extraction

See how structured data is captured from pages and shadow DOM.