# pareshnavalakha/object-diff architecture

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

- Interactive diagram: https://gitdiagram.com/pareshnavalakha/object-diff
- Repository: https://github.com/pareshnavalakha/object-diff

## Overview

##### Main Components
- Diff Compute Engine: At the heart of the project, represented by classes such as DiffComputeEngine and Engine. This component orchestrates the diff calculation process.
- Diff Calculators: Multiple calculators (e.g., ObjectDiffCalculator, SimpleCollectionDiffCalculator, ComplexCollectionDiffCalculator, MapDiffCalculator, ComplexObjectDiffCalculator) that perform domain-specific comparisons.
- Configuration & Caching: Classes under the config package (DefaultEngineConfiguration, ClassMetaDataConfiguration, ReflectionConfiguration) maintain settings, while the cache package (ClassMetadataCache) is used to optimize reflection metadata operations.
- Annotations: Custom annotations (Identifier, Description, Ignore, Order) applied on POJO getters to guide how properties are compared.
- Renderers: The renderer package (with Renderer and RenderingPreferences) facilitates the output of the diff results in various formats (with Excel Renderer explicitly mentioned).
- Supporting Utilities: Additional utility classes (e.g., ReflectionUtil, CollectionUtil, StringUtil, SummaryHelper) to handle lower-level operations.
- Data Transfer Objects (DTOs): Classes (like Diff, DiffResponse, ClassMetadata) that encapsulate the results and settings related to the diff process.
- Exceptions: A custom exception (NotSatisfactorilyTested) to capture any unique error states during processing.

##### Relationships and Interactions
- The DiffComputeEngine (or Engine) acts as the central controller. When its “findDifferences(before, after)” method is called, it delegates the diff task to one or more specialized DiffCalculator classes based on the type of data.
- The Calculators interact with the Configuration classes which determine parameters like whether to use reflection.
- The Calculators also use the utility classes (ReflectionUtil, CollectionUtil, etc.) and consult the cache (ClassMetadataCache) to speed up metadata lookups.
- The output of the diff computations is encapsulated in DTOs, which are then passed to Renderer classes to generate reports (for example, producing an Excel file).
- The custom annotations are used at the POJO level to affect the behavior of the diff calculators (e.g., which fields to compare, in what order, which fields to ignore, and how to display them).

##### Architectural Patterns/Design Principles
- Modularity and Separation of Concerns: Each package and component has its own responsibility (calculators for domain logic, config for settings, caching for performance, renderers for view/output, etc.).
- Configurability/Extensibility: The use of configuration classes and custom annotations allows developers to extend or alter the diff behavior with minimal changes.
- Use of Java 8 Features: The code leverages modern Java concepts like Streams (and Parallel Streams when appropriate) for performance.

##### Technology and Frameworks
- Java 8+ (with a dependency on Maven, as indicated by the pom.xml)
- Testing framework (evidenced by tests under src/test, indicating unit testing practices)
- CI/CD tools (Travis CI & Coveralls badges in the README indicate automated builds and test coverage reports)

##### Elements
- Clear labels for each component (e.g., "DiffComputeEngine", "ObjectDiffCalculator", "ComplexCollectionDiffCalculator", "Configuration", "Cache", "Renderer").

- “Configuration & Caching” as supportive modules that connect with the calculators.
- Optionally, add ancillary components such as “Utilities” that feed into calculators.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    Input["Objects with POJO Annotations"]:::input
    AnnoGroup["Custom Annotations\n(Identifier,Description,Ignore,Order)"]:::anno

    %% Diff Engine Layer
    subgraph "Diff Engine"
        DCE["DiffComputeEngine"]:::engine
        Engine["Engine"]:::engine
    end

    %% Diff Calculators
    subgraph "Diff Calculators"
        ODC["ObjectDiffCalculator"]:::calc
        SCC["SimpleCollectionDiffCalculator"]:::calc
        CCC["ComplexCollectionDiffCalculator"]:::calc
        MDC["MapDiffCalculator"]:::calc
        CODC["ComplexObjectDiffCalculator"]:::calc
    end

    %% Configuration & Caching
    subgraph "Configuration & Caching"
        DEC["DefaultEngineConfiguration"]:::config
        CMDC["ClassMetaDataConfiguration"]:::config
        EC["EngineConfiguration"]:::config
        RC["ReflectionConfiguration"]:::config
        CMC["ClassMetadataCache"]:::config
    end

    %% Supporting Utilities
    subgraph "Utilities"
        RU["ReflectionUtil"]:::util
        CU["CollectionUtil"]:::util
        SU["StringUtil"]:::util
        SH["SummaryHelper"]:::util
    end

    %% Data Transfer Objects
    subgraph "DTOs"
        Diff["Diff"]:::dto
        DR["DiffResponse"]:::dto
        CM["ClassMetadata"]:::dto
        CT["ChangeType"]:::dto
    end

    %% Renderers
    subgraph "Renderers"
        Rend["Renderer"]:::renderer
        RP["RenderingPreferences"]:::renderer
    end

    %% Exceptions
    Exceptions["NotSatisfactorilyTested"]:::exception

    %% Test Suite
    Tests["Test Suite (Unit Tests)"]:::test

    %% Connections
    Input -->|"provides data"| DCE
    AnnoGroup -->|"guides"| ODC
    AnnoGroup -->|"guides"| SCC
    AnnoGroup -->|"guides"| CCC
    AnnoGroup -->|"guides"| MDC
    AnnoGroup -->|"guides"| CODC

    DCE -->|"delegates"| ODC
    Engine -->|"delegates"| ODC
    DCE -->|"delegates"| SCC
    Engine -->|"delegates"| SCC
    DCE -->|"delegates"| CCC
    Engine -->|"delegates"| CCC
    DCE -->|"delegates"| MDC
    Engine -->|"delegates"| MDC
    DCE -->|"delegates"| CODC
    Engine -->|"delegates"| CODC

    %% Configuration & Caching interactions with Calculators
    DEC --- ODC
    CMDC --- ODC
    EC --- ODC
    RC --- ODC
    CMC --- ODC

    DEC --- SCC
    CMDC --- SCC
    EC --- SCC
    RC --- SCC
    CMC --- SCC

    DEC --- CCC
    CMDC --- CCC
    EC --- CCC
    RC --- CCC
    CMC --- CCC

    DEC --- MDC
    CMDC --- MDC
    EC --- MDC
    RC --- MDC
    CMC --- MDC

    DEC --- CODC
    CMDC --- CODC
    EC --- CODC
    RC --- CODC
    CMC --- CODC

    %% Utilities feeding Calculators
    RU --- ODC
    CU --- SCC
    SU --- ODC
    SH --- ODC

    RU --- SCC
    CU --- CCC

    %% Calculators produce DTOs
    ODC -->|"produces"| Diff
    SCC -->|"produces"| Diff
    CCC -->|"produces"| Diff
    MDC -->|"produces"| Diff
    CODC -->|"produces"| Diff

    %% DTOs to Renderers
    Diff --> DR
    DR -->|"rendered by"| Rend
    DR --> RP

    %% Exceptions and Test Suite
    DCE --- Exceptions
    Engine --- Exceptions
    Tests --- DCE
    Tests --- ODC
    Tests --- SCC
    Tests --- MDC

    %% Click Events
    click DCE "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/calculators/DiffComputeEngine.java"
    click Engine "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/calculators/Engine.java"
    click ODC "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/calculators/ObjectDiffCalculator.java"
    click SCC "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/calculators/SimpleCollectionDiffCalculator.java"
    click CCC "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/calculators/ComplexCollectionDiffCalculator.java"
    click MDC "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/calculators/MapDiffCalculator.java"
    click CODC "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/calculators/ComplexObjectDiffCalculator.java"
    click DEC "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/config/DefaultEngineConfiguration.java"
    click CMDC "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/config/ClassMetaDataConfiguration.java"
    click EC "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/config/EngineConfiguration.java"
    click RC "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/config/reflection/ReflectionConfiguration.java"
    click CMC "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/cache/ClassMetadataCache.java"
    click RU "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/util/ReflectionUtil.java"
    click CU "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/util/CollectionUtil.java"
    click SU "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/util/StringUtil.java"
    click SH "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/util/SummaryHelper.java"
    click Diff "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/dto/Diff.java"
    click DR "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/dto/DiffResponse.java"
    click CM "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/dto/ClassMetadata.java"
    click CT "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/dto/ChangeType.java"
    click Rend "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/renderer/Renderer.java"
    click RP "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/renderer/RenderingPreferences.java"
    click Exceptions "https://github.com/pareshnavalakha/object-diff/blob/master/src/main/java/com/paresh/diff/exception/NotSatisfactorilyTested.java"

    %% Styles
    classDef input fill:#E1F5FE,stroke:#0277BD,stroke-width:2px;
    classDef engine fill:#FFECB3,stroke:#FF8F00,stroke-width:2px;
    classDef calc fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef config fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef anno fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
    classDef util fill:#B3E5FC,stroke:#0288D1,stroke-width:2px;
    classDef dto fill:#FFE0B2,stroke:#F57C00,stroke-width:2px;
    classDef renderer fill:#D7CCC8,stroke:#5D4037,stroke-width:2px;
    classDef exception fill:#FFAB91,stroke:#D84315,stroke-width:2px;
    classDef test fill:#DCEDC8,stroke:#558B2F,stroke-width:2px;
```
