Architecture & Tech Stack

A comprehensive overview of our system design, underlying technologies, and the data pipeline.

System Architecture

High-level data flow and module interactions.

Figma API
--->
figmaFetcher
Playwright / DOM
--->
domCrawler
pixelmatch
--->
visualTester
diffEngine
--->
reporter
--->
Markdown Report

Tech Stack

Core technologies driving the audit pipeline.

Electron

v29.0
Frontend

Desktop runtime that wraps the React renderer and bridges IPC communication between the UI and main process.

React + Vite

v18 / v5
Frontend

UI layer running inside the Electron renderer process. Vite handles fast HMR during development and production bundling.

Playwright

v1.43
Testing

End-to-end browser automation used by domCrawler to navigate pages, trigger lazy-loading, and extract computed CSS styles.

pixelmatch

v5.3
Testing

Fast pixel-level image comparison library powering the visual regression checks in visualTester.

pngjs

v7.0
Testing

Pure JavaScript PNG encoder/decoder used for reading, resizing (bilinear), cropping, and writing screenshot images.

Google Gemini

v1.5
AI/Analysis

Optional LLM that performs semantic design variance analysis and auto-generates CSS fix recommendations.

Figma API

REST
AI/Analysis

Fetches live design tokens, layout properties, and full node trees directly from Figma files.

Node.js

v20.0
Output

Runtime for the Electron main process — executes the audit pipeline, manages file I/O, and handles IPC events.

Markdown

GFM
Output

Human-readable report format generated by reporter.js and rendered inside the app via react-markdown.

File Structure & Modules

Overview of the project's source directories and their roles.

hyper-audit-tools/
├── electron/
│   ├── main.js           # Main process entry
│   └── preload/
│       └── index.js      # IPC bridge (contextBridge)
├── src/
│   ├── App.jsx           # Electron renderer UI
│   └── main.jsx          # Renderer entry point
├── core/
│   ├── domCrawler.js     # Playwright DOM scraper
│   ├── figmaFetcher.js   # Figma API client
│   ├── visualTester.js   # pixelmatch logic
│   ├── diffEngine.js     # CSS & content diff
│   └── reporter.js       # Markdown + Gemini AI
├── audit.config.js       # Thresholds & settings
└── package.json

electron/main.js + preload/index.js

Main process handles IPC events, file I/O, and spawns the audit pipeline. The preload script exposes a safe window.api bridge to the renderer via contextBridge.

domCrawler

Launches a headless Chromium instance via Playwright, scrolls the full page to trigger lazy-loading, captures a full-page screenshot, then extracts computed CSS styles from every relevant DOM element.

figmaFetcher

Queries the Figma REST API at depth=5 to locate the target component by name, then fetches its full node data to extract CSS-equivalent design tokens.

diffEngine & visualTester

visualTester runs pixelmatch on screenshots with bilinear resize to handle dimension differences. diffEngine compares CSS properties, colors (ΔE), pixel values, and content structure.

reporter

Aggregates all diff results into a structured Markdown report. Optionally calls Google Gemini with the diff tables and screenshots for AI-assisted code fix suggestions.

Audit Pipeline Data Flow

A step-by-step breakdown of how a UI audit is executed.

  1. 1

    Initialization

    The Electron renderer sends a run-design-audit IPC event with the target URL, Figma File ID, component name, and credentials to the main process.

  2. 2

    Data Extraction

    In parallel, figmaFetcher pulls design tokens from the Figma API while domCrawler launches Playwright to scrape computed styles and capture a full-page screenshot.

  3. 3

    Comparison & Testing

    diffEngine correlates CSS properties, colors, spacing, and content structure. visualTester runs pixel-level diffing with bilinear resize to handle baseline/live size differences.

  4. 4

    AI Semantic Analysis (Optional)

    If a Gemini API key is provided, Google Gemini receives the diff tables and screenshots to generate Thai-language analysis and ready-to-paste CSS fix code for each CRITICAL discrepancy.

  5. 5

    Report Generation & Display

    reporter writes a Markdown file to disk. The Electron main process sends results back to the renderer via IPC, where the Report and Images tabs display the output inline.