# nmervaillie/neo4j-db-copy architecture

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

- Interactive diagram: https://gitdiagram.com/nmervaillie/neo4j-db-copy
- Repository: https://github.com/nmervaillie/neo4j-db-copy

## Overview

##### Project Type and Purpose
- This is a command-line tool designed for copying data from one Neo4j database to another using the Bolt protocol.
- The tool accepts runtime parameters (addresses, credentials, database names, options for excluding properties, and a flag for locking the source), initiates connections to both source and target Neo4j servers, and streams data between them.
- Since it does not need administrator privileges and is intended for moving test/reference data, its design focuses on connectivity, data transfer, and optional pre-copy state management (e.g., locking).

##### File Structure
- The top-level directories and files indicate a Maven-based Java project. Important files:
- pom.xml: Shows the build configuration.
- The src/main directory contains the core application code inside the Java package "org.neo4j.dbcopy".
- The src/test directory holds test cases, ensuring you include testing components in your design’s lifecycle when needed.
- The presence of GitHub workflows (.github/workflows) reflects CI/CD integration.
- Key classes include:
- DbCopyCli.java: Likely the entry point with the main() method handling argument parsing and initiating the copy process.
- CopyOptions.java: For reading and managing the command-line parameters.
- DataTransfer.java: Implements the actual logic for moving data between databases.
- DatabaseStateManager.java and LockingDatabaseStateManager.java: Manage the source database state (notably locking it in read-only mode if required).
- MappingContext.java and ProgressBar.java: Support classes for managing data mapping during transfer and providing user feedback.

a. Main Components:
- CLI Interface: Represented by DbCopyCli which reads the command line input.
- Options Manager: CopyOptions, parsing and validating input parameters.
- Data Transfer Engine: DataTransfer that orchestrates the copying process.
- Database State Management: Components offering standard (DatabaseStateManager) or locked interaction (LockingDatabaseStateManager) with the source database.
- Utility Components: MappingContext for handling potential schema or property transformations, and ProgressBar for real-time feedback.
- External Database Connections: Two external components representing the Source and Target Neo4j databases, connected through the Bolt protocol.
- Build Environment: Maven configuration (pom.xml) and CI/CD (GitHub workflows) which, although not runtime components, are part of the overall project ecosystem.

b. Relationships and Data Flows:
- The flow begins when a user invokes the CLI (DbCopyCli). The CLI calls CopyOptions to parse command-line arguments.
- Next, based on those arguments (such as the –lock flag), the system selects between DatabaseStateManager and LockingDatabaseStateManager to manage the source database.
- DataTransfer utilizes these managers along with MappingContext and ProgressBar to orchestrate the process of reading data from the source database and writing it to the target database using Neo4j’s Bolt driver.

c. Architectural Patterns and Design Principles:
- Modular design: Each core functionality (CLI, options parsing, state management, data transfer, and utility feedback) is separated into its own class, promoting separation of concerns.
- Strategy Pattern: The selection between a standard and locking state manager is an example of using interchangeable strategies for database state handling.
- Layered Architecture: Input layer (CLI), business logic layer (DataTransfer and state management), and external integration layer (Neo4j databases via Bolt).
- Testability: The presence of a dedicated test suite illustrates adherence to unit testing and separation of core logic from external dependencies.

d. Relevant Technologies, Frameworks, or Libraries:
- Java 17 (as specified).
- Maven for build management.
- Neo4j drivers (for Bolt protocol connectivity) – although not directly visible, they are implied.
- GitHub Actions for CI/CD.

##### Execution
- Zoom in on the internals of the tool showing the CLI entry point and how it drives the subsequent processing layers.
- Annotations to clarify interactions (e.g., “parses command-line args”, “selects DatabaseStateManager strategy based on the –lock flag”, “streams data using bolt protocol”, “updates progress bar”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Process
    subgraph "Core Process"
        U["User"]:::actor
        CLI["CLI Interface (DbCopyCli)"]:::cli
        OPT["Options Manager (CopyOptions)"]:::options
        DT["Data Transfer Engine (DataTransfer)"]:::engine
        U -->|"invokes"| CLI
        CLI -->|"parses-args"| OPT
        OPT -->|"initiates"| DT
    end

    %% State Management Strategies
    subgraph "Database State Management"
        DSM1["Standard Manager (DatabaseStateManager)"]:::state
        DSM2["Locking Manager (LockingDatabaseStateManager)"]:::state
    end
    DT -->|"selects"| DSM1
    DT -->|"selects"| DSM2

    %% Utility Components
    subgraph "Utilities"
        MC["Mapping Context (MappingContext)"]:::utility
        PB["User Feedback (ProgressBar)"]:::utility
    end
    DT -->|"uses"| MC
    DT -->|"uses"| PB

    %% External Databases
    subgraph "External Databases"
        SN["Source Neo4j Database"]:::database
        TN["Target Neo4j Database"]:::database
    end
    DT -->|"reads-from"| SN
    DT -->|"writes-to"| TN

    %% Project Infrastructure
    subgraph "Project Infrastructure"
        MAVEN["Maven Build (pom.xml)"]:::build
        CICD["CI/CD Integration (.github/workflows)"]:::build
    end
    MAVEN -->|"builds"| CLI
    CICD -->|"automates"| CLI

    %% Styles
    classDef actor fill:#f4d03f,stroke:#333,stroke-width:2px;
    classDef cli fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef options fill:#d5f5e3,stroke:#333,stroke-width:2px;
    classDef engine fill:#fad7a0,stroke:#333,stroke-width:2px;
    classDef state fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef utility fill:#d2b4de,stroke:#333,stroke-width:2px;
    classDef database fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef build fill:#aed6f1,stroke:#333,stroke-width:2px;

    %% Click Events
    click CLI "https://github.com/nmervaillie/neo4j-db-copy/blob/main/src/main/java/org/neo4j/dbcopy/DbCopyCli.java"
    click OPT "https://github.com/nmervaillie/neo4j-db-copy/blob/main/src/main/java/org/neo4j/dbcopy/CopyOptions.java"
    click DT "https://github.com/nmervaillie/neo4j-db-copy/blob/main/src/main/java/org/neo4j/dbcopy/DataTransfer.java"
    click DSM1 "https://github.com/nmervaillie/neo4j-db-copy/blob/main/src/main/java/org/neo4j/dbcopy/DatabaseStateManager.java"
    click DSM2 "https://github.com/nmervaillie/neo4j-db-copy/blob/main/src/main/java/org/neo4j/dbcopy/LockingDatabaseStateManager.java"
    click MC "https://github.com/nmervaillie/neo4j-db-copy/blob/main/src/main/java/org/neo4j/dbcopy/MappingContext.java"
    click PB "https://github.com/nmervaillie/neo4j-db-copy/blob/main/src/main/java/org/neo4j/dbcopy/ProgressBar.java"
    click MAVEN "https://github.com/nmervaillie/neo4j-db-copy/blob/main/pom.xml"
    click CICD "https://github.com/nmervaillie/neo4j-db-copy/tree/main/.github/workflows"
```
