# l1ttps/nestjs-fingerprint architecture

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

- Interactive diagram: https://gitdiagram.com/l1ttps/nestjs-fingerprint
- Repository: https://github.com/l1ttps/nestjs-fingerprint

## Overview

##### Project Type and Purpose
- This is an open-source NestJS dynamic module (“nestjs-fingerprint”) that provides server-side browser/device fingerprinting for any NestJS application.
- It supplies middleware to compute a fingerprint on each HTTP request, sets a cookie, and offers decorators to inject the fingerprint (and real IP) into controller methods.

##### File-Structure Highlights
- src/nestjs-fingerprint.module.ts – the dynamic NestJS module entry point (forRoot configuration)
- src/middlewares/nestjs-fingerprint.middleware.ts – middleware that runs on each request
- src/decorators/*.ts – @Fingerprint() and @RealIp() parameter decorators
- src/core/generateFingerprint.ts – core fingerprint computation logic
- src/helpers/uniqueParams.ts – utility for normalizing parameters
- example/ – a minimal NestJS app showing module integration
- tests/ – unit and e2e tests validating middleware, helper, and decorator behavior

##### Main Components
A. Host NestJS Application
- AppModule imports NestjsFingerprintModule.forRoot(…)
- Controllers (e.g. AppController) annotated with @Fingerprint() / @RealIp()
B. Nestjs-Fingerprint Dynamic Module
- Configuration (params list, cookieOptions)
- Middleware registration
- Decorators registration as custom parameter decorators
- Providers (if any shared services or tokens)
C. Middleware Flow
- Incoming HTTP Request
- Middleware extracts headers, userAgent, IP
- Calls generateFingerprint() to produce fingerprint object
- Attaches fingerprint to Request context and sets cookie on HTTP Response
- Passes control to the next handler
D. Decorator Flow
- Controller method decorated with @Fingerprint() reads fingerprint from Request context
- @RealIp() reads the extracted IP value

##### Interactions & Data Flow
1. Client → HTTP Request → NestJS HTTP Server
2. NestJS Core → Executes FingerprintMiddleware
– Extract config params (headers, UA, IP)
– Call generateFingerprint()
– Store result on request.fp, set response cookie
3. NestJS Core → Controller Handler
– @Fingerprint() decorator fetches request.fp and injects into method argument
– @RealIp() decorator fetches request.fp.ipAddress and injects
4. Controller returns data → HTTP Response to Client

##### Architectural Patterns & Principles
- NestJS Module Pattern (dynamic module with forRoot configuration)
- Middleware for cross-cutting concerns (fingerprint generation)
- Custom Parameter Decorators for seamless injection into controllers
- Functional decomposition: core logic (generateFingerprint) separated from NestJS specifics
- Extensibility: developer can supply which params to include and cookie options

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    ClientBrowser[/"Client Browser"/]:::external

    %% Host Application
    subgraph "Host NestJS Application"
        direction TB
        AppModule["AppModule"]:::module
        AppController["AppController"]:::module
        Main["main.ts"]:::module
    end

    %% Fingerprint Library
    subgraph "nestjs-fingerprint Library"
        direction TB
        FingerprintModule["NestjsFingerprintModule"]:::module
        Middleware["FingerprintMiddleware"]:::middleware
        DecoratorsBarrel["decorators/index.ts"]:::module
        FingerprintDecorator["@Fingerprint Decorator"]:::decorator
        RealIpDecorator["@RealIp Decorator"]:::decorator
        CoreLogic["generateFingerprint()"]:::helper
        UniqueParams["uniqueParams()"]:::helper
        Types["type.ts"]:::module
        EntryExports["index.ts"]:::module
    end

    %% Tests
    subgraph "Tests"
        direction TB
        E2ETest["example.e2e.spec.ts"]:::external
        UnitTest["generateFingerprint.spec.ts"]:::external
    end

    %% Example App
    subgraph "Example Application"
        direction TB
        ExampleModule["example/src/app.module.ts"]:::module
        ExampleController["example/src/app.controller.ts"]:::module
        ExampleMain["example/src/main.ts"]:::module
    end

    %% Flow
    ClientBrowser -->|"HTTP Request"| AppModule
    AppModule -->|"imports forRoot()"| FingerprintModule
    FingerprintModule --> Middleware
    Middleware -->|"extract headers, UA, IP"| CoreLogic
    CoreLogic --> UniqueParams
    CoreLogic -->|"fingerprint object"| Middleware
    Middleware -->|"attach fp to req, set cookie"| ClientBrowser
    Middleware --> AppController
    AppController -->|"@Fingerprint() injects req.fp"| FingerprintDecorator
    AppController -->|"@RealIp() injects req.fp.ipAddress"| RealIpDecorator
    FingerprintDecorator --> AppController
    RealIpDecorator --> AppController

    %% Example integration
    ExampleModule -->|"imports NestjsFingerprintModule"| FingerprintModule
    ExampleMain --> ExampleModule
    ExampleController -->|"uses @Fingerprint/@RealIp"| FingerprintDecorator

    %% Tests linkage
    E2ETest --> ExampleMain
    UnitTest --> CoreLogic

    %% Click Events
    click FingerprintModule "https://github.com/l1ttps/nestjs-fingerprint/blob/main/src/nestjs-fingerprint.module.ts"
    click Middleware "https://github.com/l1ttps/nestjs-fingerprint/blob/main/src/middlewares/nestjs-fingerprint.middleware.ts"
    click FingerprintDecorator "https://github.com/l1ttps/nestjs-fingerprint/blob/main/src/decorators/nestjs-fingerprint.decorator.ts"
    click RealIpDecorator "https://github.com/l1ttps/nestjs-fingerprint/blob/main/src/decorators/realIp.decorator.ts"
    click DecoratorsBarrel "https://github.com/l1ttps/nestjs-fingerprint/blob/main/src/decorators/index.ts"
    click CoreLogic "https://github.com/l1ttps/nestjs-fingerprint/blob/main/src/core/generateFingerprint.ts"
    click UniqueParams "https://github.com/l1ttps/nestjs-fingerprint/blob/main/src/helpers/uniqueParams.ts"
    click Types "https://github.com/l1ttps/nestjs-fingerprint/blob/main/src/type.ts"
    click EntryExports "https://github.com/l1ttps/nestjs-fingerprint/blob/main/src/index.ts"
    click ExampleModule "https://github.com/l1ttps/nestjs-fingerprint/blob/main/example/src/app.module.ts"
    click ExampleController "https://github.com/l1ttps/nestjs-fingerprint/blob/main/example/src/app.controller.ts"
    click ExampleMain "https://github.com/l1ttps/nestjs-fingerprint/blob/main/example/src/main.ts"
    click E2ETest "https://github.com/l1ttps/nestjs-fingerprint/blob/main/tests/example.e2e.spec.ts"
    click UnitTest "https://github.com/l1ttps/nestjs-fingerprint/blob/main/tests/generateFingerprint.spec.ts"

    %% Styles
    classDef module fill:#E3F2FD,stroke:#2196F3,color:#0D47A1;
    classDef middleware fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef decorator fill:#E8F5E9,stroke:#43A047,color:#1B5E20;
    classDef helper fill:#F3E5F5,stroke:#8E24AA,color:#4A148C;
    classDef external fill:#ECEFF1,stroke:#90A4AE,color:#37474F;
```
