# spring-projects/spring-data-neo4j architecture

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

- Interactive diagram: https://gitdiagram.com/spring-projects/spring-data-neo4j
- Repository: https://github.com/spring-projects/spring-data-neo4j

## Overview

This project is Spring Data Neo4j, the Spring Data module that integrates the Neo4j graph database with Spring applications. It provides both imperative and reactive repository support, a robust mapping and conversion engine, comprehensive transaction management, and even support for ahead-of-time (AOT) processing.

##### Main Components
- Core Modules:
– Mapping and Conversion Layer: Represent the classes that handle entity-to-database mapping (e.g., Neo4jMappingContext, Neo4jEntityConverter, and related converters).
– Repository Support: Include the repository abstraction interfaces (Neo4jRepository, ReactiveNeo4jRepository) and repository support classes (such as repository factory beans) that create and manage Spring Data repositories.
– Neo4j Client / Template: Denote the Neo4jClient, Neo4jTemplate, and their reactive counterparts (DefaultNeo4jClient, ReactiveNeo4jClient) that encapsulate low-level database access.
– Transaction Management: Highlight the transaction manager implementations (Neo4jTransactionManager and ReactiveNeo4jTransactionManager) that integrate with Spring’s transaction management.
– AOT / Native Support: Represent the AOT processing classes, hinting at the project’s support for native builds and runtime hints (e.g., classes under org.springframework.data.neo4j.aot).

##### External Dependencies and Integration Points
- Neo4j Graph Database: An external system that communicates over the Bolt protocol. Show the Neo4j driver (GraphDatabase.driver) as a bridge between the client/template and the database.

##### Relationships and Interactions
- Link the Client/Template layer with the Mapping/Conversion layer, demonstrating that data persistence involves converting between domain objects (annotated with @Node, for instance) and database representations.
- Transaction Management component as a facilitator that wraps operations on the repository and client layers.
- Two parallel flows (imperative and reactive) to clarify the dual approach supported by SDN.

##### Architectural Patterns and Design Principles
- Repository Pattern: Encompassing the repository interfaces and implementations.
- Template/Facade Pattern: In the Neo4jTemplate and ReactiveNeo4jTemplate classes, which simplify database interactions.
- Mapping and Conversion: Using a central mapping context and dedicated converters to manage object/graph conversion.
- Separation of Concerns: Each module (configuration, mapping, repository, transactions) is clearly separated.
- AOT Support: Incorporation of native-image reflection configuration and hints, which is crucial for optimized builds.

##### Additional Details
- A side annotation for “Documentation & Tests” to emphasize that the project is well-documented (Antora docs under src/main/antora) and that extensive integration, unit, and AOT-related tests are present under src/test.
- If space allows, indicate the build and CI/CD infrastructure (with files like Jenkinsfile, Maven wrapper) as peripheral support infrastructure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    SF["Spring Framework"]:::spring
    ND["Neo4j Graph Database (Bolt)"]:::database

    %% Core Modules Subgraph
    subgraph "Core Modules"
        %% Mapping & Conversion Layer
        subgraph "Mapping & Conversion"
            M1["Neo4jMappingContext"]:::mapping
            M2["Neo4jEntityConverter"]:::mapping
            M1 ---|"&"| M2
        end

        %% Repository Support Layer
        subgraph "Repository Support"
            R1["Neo4jRepository (Imperative)"]:::repository
            R2["ReactiveNeo4jRepository (Reactive)"]:::repository
        end

        %% Neo4j Client/Template Layer
        subgraph "Neo4j Client/Template"
            subgraph "Imperative Client/Template"
                C1["Neo4jClient"]:::client
                C2["Neo4jTemplate"]:::client
                C1 -->|"uses"| C2
            end
            subgraph "Reactive Client/Template"
                RC1["ReactiveNeo4jClient"]:::clientreact
                RC2["ReactiveNeo4jTemplate"]:::clientreact
                RC1 -.->|"uses"| RC2
            end
        end

        %% Transaction Management Layer
        subgraph "Transaction Management"
            T1["Neo4jTransactionManager"]:::transaction
            T2["ReactiveNeo4jTransactionManager"]:::transaction
        end

        %% AOT / Native Support
        AOTNode["AOT/Native Support"]:::aot
    end

    %% Relationships from Spring Framework to Core Modules
    SF -->|"configures"| R1
    SF -->|"configures"| R2
    SF -->|"manages"| T1
    SF -->|"manages"| T2

    %% Repository delegation to Client/Template layers
    R1 -->|"delegates"| C1
    R2 -.->|"delegates"| RC1

    %% Client/Template layer interactions with Mapping & Conversion
    C2 -->|"maps"| M1
    RC2 -.->|"maps"| M1

    %% Transaction Management wraps operations in Repository and Client layers
    T1 -->|"wraps"| R1
    T1 -->|"wraps"| C1
    T2 -.->|"wraps"| R2
    T2 -.->|"wraps"| RC1

    %% Client/Template calls to external Neo4j Database
    C2 -->|"calls"| ND
    RC2 -.->|"calls"| ND

    %% AOT support provides build-time hints
    AOTNode -->|"providesHintsTo"| SF

    %% Click Events for Mapping & Conversion Layer
    click M1 "https://github.com/spring-projects/spring-data-neo4j/tree/main/src/main/java/org/springframework/data/neo4j/core/mapping"
    click M2 "https://github.com/spring-projects/spring-data-neo4j/tree/main/src/main/java/org/springframework/data/neo4j/core/convert"

    %% Click Events for Repository Support
    click R1 "https://github.com/spring-projects/spring-data-neo4j/tree/main/src/main/java/org/springframework/data/neo4j/repository"
    click R2 "https://github.com/spring-projects/spring-data-neo4j/tree/main/src/main/java/org/springframework/data/neo4j/repository"

    %% Click Events for Neo4j Client/Template (Imperative)
    click C1 "https://github.com/spring-projects/spring-data-neo4j/blob/main/src/main/java/org/springframework/data/neo4j/core/Neo4jClient.java"
    click C2 "https://github.com/spring-projects/spring-data-neo4j/blob/main/src/main/java/org/springframework/data/neo4j/core/Neo4jTemplate.java"

    %% Click Events for Neo4j Client/Template (Reactive)
    click RC1 "https://github.com/spring-projects/spring-data-neo4j/blob/main/src/main/java/org/springframework/data/neo4j/core/ReactiveNeo4jClient.java"
    click RC2 "https://github.com/spring-projects/spring-data-neo4j/blob/main/src/main/java/org/springframework/data/neo4j/core/ReactiveNeo4jTemplate.java"

    %% Click Events for Transaction Management
    click T1 "https://github.com/spring-projects/spring-data-neo4j/tree/main/src/main/java/org/springframework/data/neo4j/core/transaction"
    click T2 "https://github.com/spring-projects/spring-data-neo4j/tree/main/src/main/java/org/springframework/data/neo4j/core/transaction"

    %% Click Event for AOT / Native Support
    click AOTNode "https://github.com/spring-projects/spring-data-neo4j/tree/main/src/main/java/org/springframework/data/neo4j/aot"

    %% Styles
    classDef mapping fill:#d1ffd1,stroke:#333,stroke-width:2px;
    classDef repository fill:#d1e8ff,stroke:#333,stroke-width:2px;
    classDef client fill:#ffd1d1,stroke:#333,stroke-width:2px;
    classDef clientreact fill:#ffb6c1,stroke:#333,stroke-width:2px;
    classDef transaction fill:#fff7d1,stroke:#333,stroke-width:2px;
    classDef aot fill:#e8d1ff,stroke:#333,stroke-width:2px;
    classDef spring fill:#ffedd1,stroke:#333,stroke-width:2px;
    classDef database fill:#fdd,stroke:#333,stroke-width:2px;
```
