# mapbox/pixelmatch architecture

> Architecture diagram of the GitHub repository mapbox/pixelmatch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mapbox/pixelmatch
- Repository: https://github.com/mapbox/pixelmatch

## Overview

##### Project type and purpose
- From the README and file tree, this is an open-source JavaScript library and command-line tool (“pixelmatch”) for pixel-level image comparison. It exposes a compact core API for image diffing, a CLI frontend, benchmark script, test suite, and supports both Node.js and browser environments.

##### File structure
- Top-level files:
- index.js – the core pixelmatch function implementation (≈150 lines, zero dependencies)
- bin/pixelmatch – CLI wrapper that parses args, reads PNGs, invokes index.js, writes output
- bench.js – benchmarking harness to measure performance
- test/ – test suite with fixtures and test runner (test/test.js + test/fixtures)
- tsconfig.json, eslint.config.js – configuration for TypeScript checks (if any) and linting
- .github/workflows/node.yml – CI pipeline for Node tests
- package.json + package-lock.json – npm packaging and metadata
- No frontend/backend split or microservices—this is a single-module library + CLI tool.

##### README for additional insights
- Mentions zero dependencies, bench.js for speed, and pngjs as an example consumer in Node.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Adapters and External
    Dev["Developers"]:::external
    CI["CI/CD Pipeline"]:::ci
    NPM["NPM Registry"]:::registry

    subgraph Adapters
        CLI["CLI Frontend"]:::adapter
        Browser["Browser Adapter"]:::adapter
        Test["Test Suite"]:::adapter
        Bench["Benchmark Harness"]:::adapter
    end

    subgraph External_Integrations
        FS["Node FS / pngjs"]:::external
        Canvas["Canvas API<br/>ImageData"]:::external
        Fixtures["Test Fixtures"]:::external
    end

    %% Core Module
    Core["Core Algorithm Module"]:::core

    %% Runtime Flows
    CLI -->|"reads PNGs"| FS
    FS -->|"provides Uint8Array"| Core
    Core -->|"returns diff data"| CLI

    Browser -->|"provides ImageData"| Core
    Core -->|"returns ImageData"| Browser
    Canvas --> Browser

    %% Test & Bench
    Fixtures -->|"input images"| Test
    Test -->|"asserts results"| Core

    Bench -->|"measures time"| Core

    %% CI/CD & Dev
    Dev --> CI
    CI -->|"runs tests"| Test
    CI -->|"runs benchmark"| Bench
    CI -->|"publishes"| NPM

    %% Click Events
    click Core "https://github.com/mapbox/pixelmatch/blob/main/index.js"
    click CLI "https://github.com/mapbox/pixelmatch/tree/main/bin/pixelmatch"
    click Test "https://github.com/mapbox/pixelmatch/blob/main/test/test.js"
    click Fixtures "https://github.com/mapbox/pixelmatch/tree/main/test/fixtures"
    click Bench "https://github.com/mapbox/pixelmatch/blob/main/bench.js"
    click CI "https://github.com/mapbox/pixelmatch/blob/main/.github/workflows/node.yml"

    %% Styles
    classDef core fill:#ffd54f,stroke:#333,stroke-width:2px
    classDef adapter fill:#90caf9,stroke:#333,stroke-width:1px
    classDef external fill:#a5d6a7,stroke:#333,stroke-width:1px
    classDef ci fill:#ce93d8,stroke:#333,stroke-width:1px
    classDef registry fill:#ffab91,stroke:#333,stroke-width:1px
```
