# apify/fingerprint-suite architecture

> Architecture diagram of the GitHub repository apify/fingerprint-suite, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apify/fingerprint-suite
- Repository: https://github.com/apify/fingerprint-suite

## Overview

##### Project Type and Purpose
- This is a modular monorepo (‘fingerprint-suite’) providing developer libraries and tools for browser fingerprint generation and injection. It is not a user-facing full-stack app but a collection of npm packages (and one Python package) that work together to:
- Collect real header orders (header-order-collector service)
- Generate Bayesian network definitions (generator-networks-creator)
- Generate network-based fingerprints (generative-bayesian-network)
- Create realistic HTTP headers (header-generator)
- Generate full browser fingerprint objects (fingerprint-generator)
- Inject those fingerprints into Playwright/Puppeteer browser contexts (fingerprint-injector)

##### File Structure Analysis
- Top-level: config files (.eslintrc, tsconfig, CI workflows), scripts/, static assets, test/
- packages/: each package is isolated with its own src/, data_files/, and build config; managed by Turborepo (turbo.json)
- apify_fingerprint_datapoints/: Python wrapper publishing typed data points
- packages/header-order-collector/: a standalone Node.js HTTP service (with Dockerfile and certs)
- scripts/: orchestration (data copying, network generation, publishing)
- test/: end-to-end and unit test suites for each package

##### README Insights
- Core use case: camouflage browser automation by generating & injecting realistic fingerprints
- Lists four primary npm packages plus the Bayesian network implementation
- Shows code snippets using Playwright or Puppeteer integration via fingerprint-injector

##### Main Components
a. Data Collection Service
- header-order-collector (Node.js HTTP server, Dockerized)
b. Network Definition Generation
- generator-networks-creator (reads raw data, outputs .zip network definitions)
c. Generative Model
- generative-bayesian-network (inputs definitions, outputs probabilistic fingerprint parameters)
d. Fingerprint Generation
- fingerprint-generator (wraps Bayesian network, outputs JSON fingerprint + HTTP headers blueprint)
e. HTTP Header Generation
- header-generator (takes fingerprint data to synthesize realistic headers)
f. Fingerprint Injection
- fingerprint-injector (Playwright/Puppeteer API hooks to inject fingerprint into browser contexts)
g. Python Data Points Package
- apify_fingerprint_datapoints (exports generated fingerprint types for Python users)
h. Orchestration & Scripts
- scripts/netgen.sh, .ts and copy.ts, publish.sh

##### Relationships and Data Flow
- generator-networks-creator → generative-bayesian-network (network definitions)
- generative-bayesian-network → fingerprint-generator (probabilistic fingerprint data)
- fingerprint-generator ↔ header-generator (fingerprint data used to craft headers)
- fingerprint-generator + header-generator → fingerprint-injector → Playwright/Puppeteer browser instance
- Scripts orchestrate generation pipeline and publishing to npm
- Python package imported by Python workflows

##### Architectural Patterns & Design Principles
- Monorepo with well-defined package boundaries
- Reusable libraries (single responsibility per package)
- Data-driven generation via Bayesian networks
- Service for data collection (header-order-collector) separated from offline generation
- CI/CD via GitHub Actions and Turborepo caching

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Services
    subgraph "Data Services"
        direction TB
        HOC["Header Order Collector\n(Node.js HTTP Service)"]:::data
    end

    %% Network Generation
    subgraph "Network Definition Generation"
        direction TB
        GNC["Generator Networks Creator\n(reads raw data\noutputs .zip)"]:::data
    end

    %% Generative Model
    subgraph "Generative Model"
        direction TB
        GBN["Generative Bayesian Network\n(inputs definitions,\noutputs probabilistic params)"]:::core
    end

    %% Core Libraries
    subgraph "Fingerprint Generation"
        direction TB
        FG["Fingerprint Generator\n(outputs JSON fingerprint\n+ HTTP headers blueprint)"]:::core
        HG["Header Generator\n(synthesizes realistic headers)"]:::core
    end

    %% Integration
    subgraph "Integration"
        direction TB
        FI["Fingerprint Injector\n(Playwright/Puppeteer API hooks)"]:::int
        PY["apify_fingerprint_datapoints\n(Python Data Points Package)"]:::int
    end

    %% Orchestration
    subgraph "Orchestration & Scripts"
        direction TB
        S1["scripts/netgen.sh"]:::script
        S2["scripts/netgen.ts"]:::script
        S3["scripts/copy.ts"]:::script
        S4["scripts/publish.sh"]:::script
    end

    %% External
    PP["Playwright / Puppeteer\nBrowser Instance"]:::external

    %% Data Flow
    HOC -->|"raw header data"| GNC
    GNC -->|"network-definition.zip"| GBN
    GBN -->|"probabilistic fingerprint data"| FG
    FG -->|"fingerprint data"| HG
    HG -->|"headers blueprint"| FG
    FG -->|"fingerprint+headers"| FI
    FI -->|"injects into"| PP

    %% Orchestration Flow
    S1 -.-> GNC
    S2 -.-> GBN
    S3 -.-> FG
    S4 -.-> FI

    %% Python Optional
    PY -.-> FG

    %% Click Events
    click HOC "https://github.com/apify/fingerprint-suite/tree/master/packages/header-order-collector/Dockerfile"
    click HOC "https://github.com/apify/fingerprint-suite/blob/master/packages/header-order-collector/server.js"
    click HOC "https://github.com/apify/fingerprint-suite/blob/master/packages/header-order-collector/serverv2.js"
    click HOC "https://github.com/apify/fingerprint-suite/blob/master/packages/header-order-collector/collector.js"
    click GNC "https://github.com/apify/fingerprint-suite/blob/master/packages/generator-networks-creator/src/generator-networks-creator.ts"
    click GNC "https://github.com/apify/fingerprint-suite/blob/master/packages/generator-networks-creator/src/network_structures/*.zip"
    click GNC "https://github.com/apify/fingerprint-suite/blob/master/packages/generator-networks-creator/src/index.ts"
    click GBN "https://github.com/apify/fingerprint-suite/blob/master/packages/generative-bayesian-network/src/bayesian-network.ts"
    click GBN "https://github.com/apify/fingerprint-suite/blob/master/packages/generative-bayesian-network/src/bayesian-node.ts"
    click GBN "https://github.com/apify/fingerprint-suite/blob/master/packages/generative-bayesian-network/src/index.ts"
    click FG "https://github.com/apify/fingerprint-suite/blob/master/packages/fingerprint-generator/src/fingerprint-generator.ts"
    click FG "https://github.com/apify/fingerprint-suite/blob/master/packages/fingerprint-generator/src/data_files/fingerprint-network-definition.zip"
    click FG "https://github.com/apify/fingerprint-suite/blob/master/packages/fingerprint-generator/src/index.ts"
    click HG "https://github.com/apify/fingerprint-suite/blob/master/packages/header-generator/src/header-generator.ts"
    click HG "https://github.com/apify/fingerprint-suite/blob/master/packages/header-generator/src/data_files/header-network-definition.zip"
    click HG "https://github.com/apify/fingerprint-suite/blob/master/packages/header-generator/src/data_files/headers-order.json"
    click HG "https://github.com/apify/fingerprint-suite/blob/master/packages/header-generator/src/index.ts"
    click FI "https://github.com/apify/fingerprint-suite/blob/master/packages/fingerprint-injector/src/fingerprint-injector.ts"
    click FI "https://github.com/apify/fingerprint-suite/blob/master/packages/fingerprint-injector/src/constants.ts"
    click FI "https://github.com/apify/fingerprint-suite/blob/master/packages/fingerprint-injector/src/index.ts"
    click PY "https://github.com/apify/fingerprint-suite/blob/master/apify_fingerprint_datapoints/__init__.py"
    click PY "https://github.com/apify/fingerprint-suite/blob/master/apify_fingerprint_datapoints/py.typed"
    click PY "https://github.com/apify/fingerprint-suite/blob/master/apify_fingerprint_datapoints/README.md"
    click S1 "https://github.com/apify/fingerprint-suite/blob/master/scripts/netgen.sh"
    click S2 "https://github.com/apify/fingerprint-suite/blob/master/scripts/netgen.ts"
    click S3 "https://github.com/apify/fingerprint-suite/blob/master/scripts/copy.ts"
    click S4 "https://github.com/apify/fingerprint-suite/blob/master/scripts/publish.sh"

    %% Styles
    classDef data fill:#D0E7FF,stroke:#3B82F6,color:#1E40AF
    classDef core fill:#DCFCE7,stroke:#10B981,color:#065F46
    classDef int fill:#FFEDD5,stroke:#F97316,color:#9A3412
    classDef script fill:#E5E7EB,stroke:#6B7280,color:#374151
    classDef external fill:#F3F4F6,stroke:#9CA3AF,color:#4B5563
```
