# dmidlo/get-datahash architecture

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

- Interactive diagram: https://gitdiagram.com/dmidlo/get-datahash
- Repository: https://github.com/dmidlo/get-datahash

## Overview

##### Main Components
- Core Module (DataHash Engine):
– The heart of the project is implemented in Get-DataHash.psm1 (and its variations in private/types/DataHash.psm1). This is where the hashing logic, normalizations (like sorting unordered collections, preserving ordered ones, handling circular references, and floating-point normalization), and field exclusion are implemented.
- Custom Type Mappers:
– The “private/types/Mappers” directory contains scripts (e.g., Mapper_PSCustomClass_DataHash.ps1) that extend the core module with custom serialization and type-mapping capabilities (leveraging LiteDB’s BsonMapper features).
- Public Interface:
– The “public” folder holds a user-facing script (Get-DataHash.ps1) which acts as an entry point to call the DataHash functions from a script or interactive session.
- External Dependency (LiteDB/BSON Serialization):
– As documented in the README, DataHash uses LiteDB’s BSON serialization (see LiteDB.xml and references in the README) to ensure consistent serialization across runs. This component ensures that PowerShell native quirks (like unordered collections or JSON issues) do not affect the hash.
- Testing and Validation Components:
– The “tests” and individual test scripts (like Constructors.Tests.ps1, ComparisonOperators.Tests.ps1, etc.) validate that the module produces stable, consistent results across various input types.
- Additional Development & Standards:
– Files like STANDARDS.md or the .vscode folder indicate coding standards and development environment configurations but are less central to the runtime architecture from an execution perspective.

##### Relationships and Data Flow
- Input Data (PowerShell objects) → Public Interface:
– Users pass objects to the public script or call the module’s constructors.
- Public Interface → Core Module:
– The main processes call functions within Get-DataHash.psm1 to perform the digest calculations.
- Core Module → LiteDB Serialization:
– When processing objects, the module delegates serialization tasks to LiteDB’s BSON library (illustrated by references to LiteDB.xml) to ensure precision.
- Core Module → Custom Type Mappers:
– For custom or complex objects, the engine calls the mappers found under “private/types/Mappers” to standardize object representation.
- Core Module → Output (Message Digest):
– Once all transformations and normalizations occur, the engine returns a stable message digest (the final output is then used for change tracking, caching, or auditing).
- Tests interact with all these components to ensure consistency.

##### Architectural Patterns and Principles
- Normalization and Determinism:
– Emphasize that the system sorts unordered collections, preserves order when needed, and applies normalization (such as IEEE 754 conversions for floats) to maintain digest stability.
- Separation of Concerns:
– Notice how the design modularizes the core hashing logic, type mapping, and external serialization. This makes it easier to test (see the comprehensive tests folder) and extend.
- Extensibility:
– By having a directory for custom mappers, the architecture supports extensions to handle additional data types without altering core logic.
- External Integration:

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Input Data (PowerShell Objects)"]:::input
    B["Public Interface (Entry Script)"]:::entry
    subgraph "DataHash Core Engine"
        C["Main Module"]:::internal
        D["Helper Module"]:::internal
    end
    E["Output Message Digest"]:::output
    F["LiteDB Serialization (External)"]:::external
    G["Custom Type Mappers"]:::internal
    subgraph "Test Suite"
        T1["ComparisonOperators Tests"]:::test
        T2["Constructors Tests"]:::test
        T3["TypeMapping Tests"]:::test
        T4["IsEnumerable Tests"]:::test
        T5["NormalizeDict Tests"]:::test
        T6["NormalizeList Tests"]:::test
        T7["NormalizedValue Tests"]:::test
        T8["Scratch Tests"]:::test
    end

    A -->|"input"| B
    B -->|"calls"| C
    C -->|"outputs"| E
    C -->|"serializes"| F
    C -->|"delegates"| D
    G -->|"maps"| C
    T1 -->|"validate"| B
    T2 -->|"validate"| C
    T3 -->|"validate"| G
    T4 -->|"validate"| C
    T5 -->|"validate"| C
    T6 -->|"validate"| C
    T7 -->|"validate"| C
    T8 -->|"validate"| C

    click B "https://github.com/dmidlo/get-datahash/blob/main/public/Get-DataHash.ps1"
    click C "https://github.com/dmidlo/get-datahash/blob/main/Get-DataHash.psm1"
    click D "https://github.com/dmidlo/get-datahash/blob/main/private/types/DataHash.psm1"
    click G "https://github.com/dmidlo/get-datahash/blob/main/private/types/Mappers/Mapper_PSCustomClass_DataHash.ps1"
    click F "https://github.com/dmidlo/get-datahash/blob/main/LiteDB.xml"
    click T1 "https://github.com/dmidlo/get-datahash/blob/main/tests/ComparisonOperators.Tests.ps1"
    click T2 "https://github.com/dmidlo/get-datahash/blob/main/tests/Constructors.Tests.ps1"
    click T3 "https://github.com/dmidlo/get-datahash/blob/main/tests/TypeMapping.Tests.ps1"
    click T4 "https://github.com/dmidlo/get-datahash/blob/main/tests/_isEnumerable.Tests.ps1"
    click T5 "https://github.com/dmidlo/get-datahash/blob/main/tests/_normalizeDict.Tests.ps1"
    click T6 "https://github.com/dmidlo/get-datahash/blob/main/tests/_normalizeList.Tests.ps1"
    click T7 "https://github.com/dmidlo/get-datahash/blob/main/tests/_normalizedValue.Tests.ps1"
    click T8 "https://github.com/dmidlo/get-datahash/blob/main/tests/sractch.Tests.ps1"

    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef external fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef entry fill:#FFA500,stroke:#333,stroke-width:2px;
    classDef test fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef input fill:#FFFF99,stroke:#333,stroke-width:2px;
    classDef output fill:#DDA0DD,stroke:#333,stroke-width:2px;
```
