# carr1005/lighthouse-batch-parallel architecture

> Architecture diagram of the GitHub repository carr1005/lighthouse-batch-parallel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/carr1005/lighthouse-batch-parallel
- Repository: https://github.com/carr1005/lighthouse-batch-parallel

## Overview

##### Project type and purpose
- This is a Node.js‑based library + CLI tool (“lighthouse-batch-parallel”) for running Google Lighthouse audits on a batch of URLs in parallel.
- It can be required as a module in other Node.js apps or invoked as a standalone command‑line utility.

##### File structure
- Top‑level files and directories:
- index.js – the core module entry point exporting `lighthouseBatchParallel`
- worker.js – implements a single audit worker (spawns headless Chrome, runs Lighthouse)
- lighthouse-batch-parallel.js – CLI wrapper invoking the core module
- utils.js – shared utilities (parsing CSV/JSON, formatting output, event wiring)
- assets/ – default and example input/custom‑audit configurations
- package.json, .eslintrc.json, README.md, LICENSE, .gitignore
- Patterns:
- Worker Pool / Producer‑Consumer for parallel audits
- Event‑driven (EventEmitter) for streaming results and progress
- Modular separation: CLI vs core API vs worker implementation
- Input/Output abstraction supporting streams, files, and various formats (CSV, JSON, JS objects)

##### README for additional insights
- Core API: `lighthouseBatchParallel(parameters) → EventEmitter`
- Configurable params: input source, custom audits, throttling, output format, number of workers
- Events emitted: ‘data’, ‘error’, ‘end’
- CLI options mirror core parameters and handle file I/O

##### Main components
a. Front‑end / Invocation layers
- CLI Script (`lighthouse-batch-parallel.js`)
- Consumer code calling `require('lighthouse-batch-parallel')`
b. Core Orchestrator
- index.js – parses args/params, loads utils, initializes task queue and worker pool, wires up EventEmitter
c. Worker Pool
- worker.js – each process/thread:
– launches headless Chrome instance via Lighthouse Node API
– runs audit for one URL
– returns audit report back to orchestrator
d. Utilities
- utils.js – file/stream parsing (CSV/JSON), output formatting, progress calculation
- assets/defaultConfig.js – default audit configuration
e. External dependencies
- Lighthouse package (runs audits under the hood)
- Headless Chrome (controlled via DevTools Protocol)
- Node.js EventEmitter, child_process or worker_threads (depending on implementation)
f. Input and Output flows
- Input sources:
– File (CSV/JSON) → parsed to stream of URL tasks
– In‑memory JS array or CSV string stream
- Output sinks:
– Stream/event callbacks (data, error, end)
– Files (CSV/JSON) when used via CLI

##### Relationships and interactions
- The CLI or consumer invokes the orchestrator (index.js).
- The orchestrator:
1. Parses inputs and custom‑audit configs via utils.
2. Enqueues tasks into a central queue.
3. Spawns N worker instances (workersNum) in parallel.
4. Distributes tasks to workers (round‑robin or queue pull).
5. Listens for worker responses (audit report or error).
6. Emits ‘data’ or ‘error’ events back to caller.
7. On completion of all tasks, emits ‘end’.
- Each worker:
- Receives a task (URL + device + audit config)
- Launches a headless Chrome via Lighthouse API
- Runs audit, returns results (scores, metrics)
- Utils handle serialization and formatting at each stage.

##### Architectural patterns and design principles
- Producer‑Consumer (Orchestrator produces tasks, workers consume)
- Event‑Driven: decoupling of core logic from consumers via EventEmitter
- Strategy / Plugin: custom audit configuration loaded at runtime
- Single Responsibility:
- CLI wrapper (arg parsing, file I/O)
- Core orchestrator (parallelization, eventing)
- Worker (single audit execution)
- Utils (parsing/formatting)

##### Relevant technologies and libraries
- Node.js (v10+)
- Google Chrome Lighthouse (Node module)
- child_process or worker_threads (to parallelize)
- CSV / JSON parsing libraries
- EventEmitter (built‑in)
- npm scripts (for packaging)
- ESLint (code quality)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Invocation Layer
    subgraph "Invocation Layer"
        CLI["CLI Script\n(lighthouse-batch-parallel.js)"]:::cli
        Consumer["Consumer Code\n(require('lighthouse-batch-parallel'))"]:::external
    end

    %% Core Orchestrator
    subgraph "Core Orchestrator"
        Index["Orchestrator\n(index.js)"]:::core
        TaskQueue["Task Queue"]:::core
        EventOut["EventEmitter Output\ndata / error / end"]:::external
    end

    %% Worker Pool
    subgraph "Worker Pool"
        Worker["Worker\n(worker.js)"]:::worker
    end

    %% Utilities
    subgraph "Utilities"
        Utils["Utils\n(utils.js)"]:::util
    end

    %% Assets and Config
    subgraph "Assets / Config"
        DefaultConfig["Default Config\n(assets/defaultConfig.js)"]:::assets
        CustomCSV["Custom Audits CSV\n(assets/custom-audits.csv)"]:::assets
        CustomJSON["Custom Audits JSON\n(assets/custom-audits.json)"]:::assets
        InputCSV["Input CSV\n(assets/input.csv)"]:::assets
        InputJSON["Input JSON\n(assets/input.json)"]:::assets
        Package["package.json"]:::assets
        Readme["README.md"]:::assets
    end

    %% External Services
    subgraph "External Dependencies"
        Lighthouse["Lighthouse Module"]:::external
        Chrome["Headless Chrome"]:::external
    end

    %% Output Files
    OutputFiles["Output Files\n(CSV/JSON)"]:::assets

    %% Connections
    CLI -->|invokes| Index
    Consumer -->|calls| Index
    InputCSV -->|parsed by| Utils
    InputJSON -->|parsed by| Utils
    DefaultConfig -->|loaded by| Utils
    CustomCSV -->|loaded by| Utils
    CustomJSON -->|loaded by| Utils
    Utils -->|provides tasks| Index
    Index -->|enqueues| TaskQueue
    TaskQueue -->|dispatches| Worker
    Worker -->|calls| Lighthouse
    Lighthouse -->|controls| Chrome
    Worker -->|returns report| Index
    Index -->|emits| EventOut
    Index -->|sends for formatting| Utils
    Utils -->|writes| OutputFiles

    %% Click Events
    click CLI "https://github.com/carr1005/lighthouse-batch-parallel/blob/master/lighthouse-batch-parallel.js"
    click Index "https://github.com/carr1005/lighthouse-batch-parallel/blob/master/index.js"
    click Worker "https://github.com/carr1005/lighthouse-batch-parallel/blob/master/worker.js"
    click Utils "https://github.com/carr1005/lighthouse-batch-parallel/blob/master/utils.js"
    click DefaultConfig "https://github.com/carr1005/lighthouse-batch-parallel/blob/master/assets/defaultConfig.js"
    click CustomCSV "https://github.com/carr1005/lighthouse-batch-parallel/blob/master/assets/custom-audits.csv"
    click CustomJSON "https://github.com/carr1005/lighthouse-batch-parallel/blob/master/assets/custom-audits.json"
    click InputCSV "https://github.com/carr1005/lighthouse-batch-parallel/blob/master/assets/input.csv"
    click InputJSON "https://github.com/carr1005/lighthouse-batch-parallel/blob/master/assets/input.json"
    click Package "https://github.com/carr1005/lighthouse-batch-parallel/blob/master/package.json"
    click Readme "https://github.com/carr1005/lighthouse-batch-parallel/blob/master/README.md"

    %% Styles
    classDef cli fill:#f9c74f,stroke:#e76f51,color:#000
    classDef core fill:#90be6d,stroke:#2a9d8f,color:#000
    classDef worker fill:#577590,stroke:#4d908e,color:#fff
    classDef util fill:#f9844a,stroke:#f8961e,color:#000
    classDef assets fill:#adb5bd,stroke:#6c757d,color:#000
    classDef external fill:#ffadad,stroke:#e63946,color:#000
```
