# michael-simons/neo4j-migrations architecture

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

- Interactive diagram: https://gitdiagram.com/michael-simons/neo4j-migrations
- Repository: https://github.com/michael-simons/neo4j-migrations

## Overview

##### Main Components
- Core API (Migration Engine):
– This is the heart of the system and contains the migration logic, versioning, precondition checking, catalog representation, and refactoring code.
– It relies on external dependencies such as the official Neo4j Java Driver and ClassGraph (for classpath scanning).
- Integration Modules / Front‑Ends:
– CLI: A command-line application (with a native binary build) that provides a standalone way to apply migrations.
– Maven Plugin: Allows integration into the build process so that migration commands can be run during a Maven build.
– Spring Boot Starter: Provides autoconfiguration to seamlessly integrate migration capabilities into Spring Boot applications.
– Quarkus Extension: Serves a similar role for Quarkus-based applications.
– Format-specific Modules: Modules like neo4j-migrations-formats-adoc, neo4j-migrations-formats-markdown (and CSV formats, if present) allow the system to interpret migrations written in different file formats.
- Examples and Test Resources:
– Separate directories and modules (e.g., neo4j-migrations-examples, neo4j-migrations-test‑resources) illustrate usage and provide integration tests. Although not part of production runtime, they help clarify how each component interacts.

##### Relationships and Interactions
- The Core API, in turn, communicates with one or more Neo4j database instances. This connection is established via the Neo4j Java Driver.
- The Format-specific modules plug into the Core API, enabling it to read and parse migration definitions from various file formats.
- A separate subsystem or layer may show the “Migration History” – the internal mechanism that stores applied migrations as a graph within the database. This can be shown as part of the Core’s responsibilities.
- You may also show external tools/integrations such as JBang (to run the CLI) and build/deployment pipelines (e.g., CI workflows from the .github directory).

##### Architectural Pattern and Design Principles
- Layered Architecture: Illustrate a bottom layer with external dependencies (the Neo4j database and its driver, the ClassGraph for scanning) and a middle “Core” layer that implements migration logic; on top, show the integration/adaptor modules (CLI, Maven Plugin, Boot Starter, Quarkus Extension).
- Modularity: Emphasize that the core is independent and reusable; integration modules are separate projects that “plug” into the core.

##### Final Recommendations
- Including examples of the migration file lifecycle (from discovery to execution to recording in the database).
- Modular nature of the project – identify each top‑level module from the file tree as a distinct component in the broader system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "Layer 1: Input"
        In["Migration Files & Config"]:::input
    end

    subgraph "Layer 2: Core Components"
        Core["Main Core API (Migration Engine)"]:::core
        ClassGraph["ClassGraph (Classpath Scanning)"]:::external
    end

    subgraph "Layer 3: Format Modules"
        AD["AsciiDoc Format Module"]:::format
        CSV["CSV Format Module"]:::format
        MD["Markdown Format Module"]:::format
    end

    subgraph "Layer 4: Integration Modules"
        CLI["Command Line Interface (CLI)"]:::integration
        Maven["Maven Plugin Integration"]:::integration
        Spring["Spring Boot Starter"]:::integration
        Quarkus["Quarkus Extension"]:::integration
    end

    subgraph "Layer 5: Examples & Tests"
        Examples["Examples"]:::input
        Tests["Test Resources"]:::input
    end

    subgraph "Layer 6: External Systems"
        Neo4j["(Neo4j Database)"]:::external
        JBang["JBang Runner"]:::external
        CI["CI/CD Pipeline"]:::external
    end

    %% Relationships: Input to Core
    In -->|"provides_definitions"| Core
    ClassGraph -->|"scans_classes"| Core

    %% Relationships: Core uses Format Modules
    Core -->|"parses_migration_scripts"| AD
    Core -->|"parses_migration_scripts"| CSV
    Core -->|"parses_migration_scripts"| MD

    %% Integration modules trigger core migrations
    CLI -->|"triggers_migration"| Core
    Maven -->|"triggers_migration"| Core
    Spring -->|"triggers_migration"| Core
    Quarkus -->|"triggers_migration"| Core

    %% Core applies migrations to Neo4j Database
    Core -->|"applies_migrations_via_driver"| Neo4j

    %% Examples and tests using Core API
    Examples -->|"demo_usage"| Core
    Tests -->|"integration_tests"| Core

    %% External tool integrations
    CLI -->|"runnable_via"| JBang
    CI -->|"build_trigger"| Maven
    CI -->|"build_trigger"| Spring

    %% Styling for visual distinction
    classDef core fill:#ffe6e6, stroke:#cc0000, stroke-width:2px;
    classDef integration fill:#e6f2ff, stroke:#0066cc, stroke-width:2px;
    classDef format fill:#e6ffe6, stroke:#009933, stroke-width:2px;
    classDef external fill:#fff2cc, stroke:#e69900, stroke-width:2px;
    classDef input fill:#e6f7ff, stroke:#3399ff, stroke-width:2px;

    %% Click Events for Component Mapping
    click Core "https://github.com/michael-simons/neo4j-migrations/tree/main/neo4j-migrations-core"
    click CLI "https://github.com/michael-simons/neo4j-migrations/tree/main/neo4j-migrations-cli"
    click Maven "https://github.com/michael-simons/neo4j-migrations/tree/main/neo4j-migrations-maven-plugin"
    click Spring "https://github.com/michael-simons/neo4j-migrations/tree/main/neo4j-migrations-spring-boot-starter-parent/neo4j-migrations-spring-boot-autoconfigure"
    click Quarkus "https://github.com/michael-simons/neo4j-migrations/tree/main/neo4j-migrations-quarkus-parent"
    click AD "https://github.com/michael-simons/neo4j-migrations/tree/main/extensions/neo4j-migrations-formats-adoc"
    click CSV "https://github.com/michael-simons/neo4j-migrations/tree/main/extensions/neo4j-migrations-formats-csv"
    click MD "https://github.com/michael-simons/neo4j-migrations/tree/main/extensions/neo4j-migrations-formats-markdown"
    click Examples "https://github.com/michael-simons/neo4j-migrations/tree/main/neo4j-migrations-examples"
    click Tests "https://github.com/michael-simons/neo4j-migrations/tree/main/neo4j-migrations-test-resources"
```
