# fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration architecture

> Architecture diagram of the GitHub repository fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration
- Repository: https://github.com/fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration

## Overview

##### Project type and purpose
- This is a serverless edge-compute proxy integration for Fingerprint Pro, built on Fastly Compute.
- Its job is to sit in front of Fingerprint’s identification API and JavaScript agent CDN, forwarding requests from client browsers through your Fastly network, using Fastly Config and Secret stores for runtime parameters and credentials.

##### File structure
- Top-level:
- src/ – TypeScript entry points and handler implementations
- plugins/ – extension points (e.g., saveToKVStore)
- scripts/ – CLI and CI helpers for service lifecycle (createService, deployPackage, mock tests)
- __mocks__/ – test doubles for Fastly runtime bindings
- test/ – unit and integration tests for handlers and utilities
- Configuration files for linting, formatting, deployment (babel.config.js, build.ts, fastly.toml, GitHub workflows).
- The src/handlers folder holds three core routes:
- handleDownloadScript.ts – serves the Fingerprint JS agent
- handleIngressAPI.ts – forwards identify (GET_RESULT_PATH) requests
- handleStatusPage.ts – health/status endpoint
- src/utils contains common HTTP helpers, encryption/unsealing logic, proxy headers, plugin registration, etc.

##### README for additional insights
- Describes Fastly Config store keys (AGENT_SCRIPT_DOWNLOAD_PATH, GET_RESULT_PATH, OPEN_CLIENT_RESPONSE_PLUGINS_ENABLED).
- Describes Fastly Secret store key (PROXY_SECRET).
- Emphasizes two distinct proxy flows: one for the JS agent download and one for identification requests.

##### Main components and interactions
a. Client Browser (Customer Website)
– Runs FingerprintJS agent configured to point at your Fastly domain + AGENT_SCRIPT_DOWNLOAD_PATH/GET_RESULT_PATH.
b. Fastly CDN / Edge Compute Service
– DNS entry (e.g., metrics.yourwebsite.com)
– Compute edge runtime hosting the compiled package (handler.ts + plugins)
– Config Store (AGENT_SCRIPT_DOWNLOAD_PATH, GET_RESULT_PATH, plugin flags)
– Secret Store (PROXY_SECRET)
c. Fingerprint Pro API (External Service)
– Identification endpoint behind Fingerprint’s CDN/API
– JavaScript agent CDN fallback
d. (Optional) KV Store Plugin
– If enabled, used by saveToKVStore plugin to cache or log requests at edge
e. CI/CD / GitHub Actions (build, test, release)
– Build pipeline compiles TS, runs jest, packages fingerprint-proxy-integration.tar.gz, and publishes releases

##### Relationships and data flows
1) Browser requests https://metrics.yourwebsite.com/AGENT_SCRIPT_DOWNLOAD_PATH → Fastly Compute → src/handlers/handleDownloadScript → fetch JS agent from Fingerprint CDN or local cache → return to browser.
2) Browser calls https://metrics.yourwebsite.com/GET_RESULT_PATH?region=us → Fastly Compute → src/handlers/handleIngressAPI → authenticate with PROXY_SECRET → forward to Fingerprint Pro Identification API → receive JSON identity → apply any open-client-response plugins → return to browser.
3) Health checks to / (or /status) → src/handlers/handleStatusPage → return 200 OK.

##### Architectural patterns and highlights
- Edge-compute proxy pattern: small handlers orchestrating HTTP forwarding, authentication, and response transformation.
- Plugin registry: src/utils/registerPlugin dynamically hooks into request/response lifecycle.
- Configuration via Fastly Config + Secret stores keeps code generic and zero-config at compile time.
- TypeScript modularity: clear separation of handlers, utilities, and plugins.

- Fastly Compute@Edge (Rust-powered edge environment)
- TypeScript / Babel / build.ts → compiled to a WebAssembly or JS package
- Fastly Config Store & Secret Store
- Fingerprint Pro REST API & JS agent CDN
- GitHub Actions for CI/CD
- Jest for unit tests, husky & commitlint for repo quality

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    Browser["Client Browser"]:::client

    %% Fastly Edge Compute
    subgraph "Fastly Edge Compute" 
        direction TB
        Entry["Index Entry"]:::edge
        Router["Request Router"]:::edge
        ConfigStore["Config Store"]:::edge
        SecretStore["Secret Store"]:::edge

        subgraph "Handlers"
            direction TB
            DownloadHandler["Download Script Handler"]:::edge
            APIHandler["Identification API Handler"]:::edge
            StatusHandler["Health/Status Handler"]:::edge
        end

        PluginRegistry["Plugin Registry"]:::edge
        KVPlugin["KV Store Plugin"]:::edge

        subgraph "Utilities"
            direction TB
            GetStore["getStore.ts"]:::edge
            UnsealData["unsealData.ts"]:::edge
            Decrypt["decrypt.ts"]:::edge
            ProxyHeaders["addProxyIntegrationHeaders.ts"]:::edge
            CreateRoute["createRoute.ts"]:::edge
            ProcessResponse["processOpenClientResponse.ts"]:::edge
        end
    end

    %% External Services
    subgraph "Fingerprint Pro Services"
        direction TB
        FingerprintCDN["Fingerprint JS Agent CDN"]:::external
        FingerprintAPI["Fingerprint Pro Identification API"]:::external
    end

    %% CI/CD & Dev
    subgraph "CI/CD & Dev"
        direction TB
        Build["build.ts"]:::ci
        FastlyToml["fastly.toml"]:::ci
        CreateServiceScript["scripts/api/createService.ts"]:::ci
        Workflows[".github/workflows/*.yml"]:::ci
    end

    %% Flows
    Browser -->|"GET /AGENT_SCRIPT_DOWNLOAD_PATH"| Entry
    Entry --> Router
    Router -->|"route to Download"| DownloadHandler
    DownloadHandler -->|"fetch JS agent"| FingerprintCDN
    FingerprintCDN --> DownloadHandler
    DownloadHandler --> Browser

    Browser -->|"GET /GET_RESULT_PATH"| Entry
    Router -->|"route to API"| APIHandler
    APIHandler --> SecretStore
    APIHandler -->|"forward request"| FingerprintAPI
    FingerprintAPI --> APIHandler
    APIHandler --> PluginRegistry
    PluginRegistry --> KVPlugin
    PluginRegistry --> ProcessResponse
    ProcessResponse --> APIHandler
    APIHandler --> Browser

    Browser -->|"GET /status"| Entry
    Router --> StatusHandler
    StatusHandler --> Browser

    Router --> ConfigStore
    APIHandler --> ConfigStore

    %% Click Events
    click Entry "https://github.com/fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration/blob/main/src/index.ts"
    click Router "https://github.com/fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration/blob/main/src/handler.ts"
    click DownloadHandler "https://github.com/fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration/blob/main/src/handlers/handleDownloadScript.ts"
    click APIHandler "https://github.com/fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration/blob/main/src/handlers/handleIngressAPI.ts"
    click StatusHandler "https://github.com/fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration/blob/main/src/handlers/handleStatusPage.ts"
    click PluginRegistry "https://github.com/fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration/blob/main/src/utils/registerPlugin.ts"
    click KVPlugin "https://github.com/fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration/blob/main/plugins/saveToKVStore.ts"
    click GetStore "https://github.com/fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration/blob/main/src/utils/getStore.ts"
    click UnsealData "https://github.com/fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration/blob/main/src/utils/unsealData.ts"
    click Decrypt "https://github.com/fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration/blob/main/src/utils/decrypt.ts"
    click ProxyHeaders "https://github.com/fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration/blob/main/src/utils/addProxyIntegrationHeaders.ts"
    click CreateRoute "https://github.com/fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration/blob/main/src/utils/createRoute.ts"
    click ProcessResponse "https://github.com/fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration/blob/main/src/utils/processOpenClientResponse.ts"
    click Build "https://github.com/fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration/blob/main/build.ts"
    click FastlyToml "https://github.com/fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration/blob/main/fastly.toml"
    click CreateServiceScript "https://github.com/fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration/blob/main/scripts/api/createService.ts"
    click Workflows "https://github.com/fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration/blob/main/.github/workflows/*.yml"

    %% Styles
    classDef client fill:#add8e6,stroke:#333,stroke-width:1px
    classDef edge fill:#90ee90,stroke:#333,stroke-width:1px
    classDef external fill:#ffa500,stroke:#333,stroke-width:1px
    classDef ci fill:#d3d3d3,stroke:#333,stroke-width:1px
```
