# neo4j-graphacademy/genai-workshop-graphrag architecture

> Architecture diagram of the GitHub repository neo4j-graphacademy/genai-workshop-graphrag, 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/neo4j-graphacademy/genai-workshop-graphrag
- Repository: https://github.com/neo4j-graphacademy/genai-workshop-graphrag

## Overview

##### Main Components
- Knowledge Graphs & Vectors Module – This is represented by the “1-knowledge-graphs-vectors” directory. It contains scripts like build_graph.py and create_and_embed_chunks.py that focus on building knowledge graphs, generating vector embeddings, and likely indexing these vectors.
- Neo4j GraphRAG Module – Found in the “2-neo4j-graphrag” directory, this module includes components like:
– hybrid_cypher_retriever.py
– hybrid_retriever.py
– text2cypher_retriever.py
– vector_cypher_retriever.py
– vector_retriever.py
– multimodal_app.py
These scripts indicate an architecture that integrates Neo4j database functionality with methods for retrieving information both via Cypher (graph queries) and vector similarity search. The “solutions” folders under each module contain tested sample solutions that illustrate the intended usage.
- Database Component – Although there isn’t a database configuration in the repository itself, the README instructs users to create a Neo4j instance preloaded with a “recommendations” dataset. This Neo4j instance is a critical external component that the application interacts with.
- Environment & Configuration – Files such as .env.example, devcontainer configuration files, and setup instructions in SETUP.md indicate that containerization and environment setup are integral to running and testing the system.

##### Relationships and Data Flow
- Data Ingestion & Preprocessing: The “build_graph.py” and “create_and_embed_chunks.py” scripts process raw data to create embeddings and build a knowledge graph. The outputs here feed into the Neo4j instance.
- Retrieval Operations: In the Neo4j GraphRAG module, different retriever components (text-based, vector-based, hybrid, etc.) are responsible for querying the database. The multimodal_app.py likely ties together these retrieval modalities.
- Testing & Solutions: The “solutions” directories in both modules contain ready-made examples that demonstrate how each component should work and integrate with Neo4j, serving as interactable proofs of concept.

##### Architectural Patterns & Design Principles
- Modular Design: The separation into “1-knowledge-graphs-vectors” and “2-neo4j-graphrag” shows a deliberate modular split between data preparation (embedding and graph construction) and retrieval mechanisms (querying data via different strategies).
- Layered Architecture: Although not a full-stack application (i.e., no distinct frontend-backend separation), the project shows a clear separation between the “data processing” layer and the “retrieval/query” layer.
- Extensibility: The presence of multiple retriever types (vector, cypher, hybrid, and text-to-cypher) highlights the emphasis on experimentation with different retrieval methods.

##### Technologies and Frameworks
- Neo4j Database – Central to the architecture for storing and querying the knowledge graphs and vector indices.
- Python Modules – The various Python scripts and modules represent the logic handling data processing, embedding creation, and retrieval methods.
- Development Container – The .devcontainer settings indicate a containerized development environment, which should be depicted as a supportive, enabling infrastructure component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Environment & Configuration
    subgraph "Environment & Configuration"
        EC1[".devcontainer"]:::env
        EC2[".env.example"]:::env
        EC3["SETUP.md"]:::env
    end

    %% Knowledge Graph & Vector Processing Component
    subgraph "Knowledge Graph & Vector Processing"
        KG1["build_graph.py"]:::logic
        KG2["create_and_embed_chunks.py"]:::logic
        KGSol["Solutions (KG & Vectors)"]:::logic
    end

    %% Neo4j GraphRAG Retrieval Component
    subgraph "Neo4j GraphRAG Retrieval"
        GRA1["hybrid_cypher_retriever.py"]:::logic
        GRA2["hybrid_retriever.py"]:::logic
        GRA3["text2cypher_retriever.py"]:::logic
        GRA4["vector_cypher_retriever.py"]:::logic
        GRA5["vector_retriever.py"]:::logic
        GRA6["multimodal_app.py"]:::logic
        GRASol["Solutions (GraphRAG)"]:::logic
    end

    %% Neo4j Database Instance
    Neo4j["Neo4j Database Instance"]:::database

    %% Testing & Example Solutions Component
    subgraph "Testing & Example Solutions"
        T1["conftest.py"]:::test
        T2["test_environment.py"]:::test
    end

    %% Data Flow: Knowledge Graph & Vector Processing -> Neo4j Database
    KG1 -->|"embedding_data"| Neo4j
    KG2 -->|"embedding_data"| Neo4j
    KGSol -->|"embedding_data"| Neo4j

    %% Data Flow: Neo4j GraphRAG Retrieval -> Neo4j Database
    GRA1 -->|"query"| Neo4j
    GRA2 -->|"query"| Neo4j
    GRA3 -->|"query"| Neo4j
    GRA4 -->|"query"| Neo4j
    GRA5 -->|"query"| Neo4j
    GRA6 -->|"query"| Neo4j
    GRASol -->|"query"| Neo4j

    %% Environment & Configuration supporting Components
    EC1 --> KG1
    EC1 --> GRA1
    EC2 --> KG2
    EC2 --> GRA2
    EC3 --> KGSol
    EC3 --> GRASol

    %% Testing integrations
    T1 --- KGSol
    T2 --- GRASol

    %% Click Events for Knowledge Graph & Vector Processing
    click KG1 "https://github.com/neo4j-graphacademy/genai-workshop-graphrag/blob/main/1-knowledge-graphs-vectors/build_graph.py"
    click KG2 "https://github.com/neo4j-graphacademy/genai-workshop-graphrag/blob/main/1-knowledge-graphs-vectors/create_and_embed_chunks.py"
    click KGSol "https://github.com/neo4j-graphacademy/genai-workshop-graphrag/tree/main/1-knowledge-graphs-vectors/solutions/"

    %% Click Events for Neo4j GraphRAG Retrieval
    click GRA1 "https://github.com/neo4j-graphacademy/genai-workshop-graphrag/blob/main/2-neo4j-graphrag/hybrid_cypher_retriever.py"
    click GRA2 "https://github.com/neo4j-graphacademy/genai-workshop-graphrag/blob/main/2-neo4j-graphrag/hybrid_retriever.py"
    click GRA3 "https://github.com/neo4j-graphacademy/genai-workshop-graphrag/blob/main/2-neo4j-graphrag/text2cypher_retriever.py"
    click GRA4 "https://github.com/neo4j-graphacademy/genai-workshop-graphrag/blob/main/2-neo4j-graphrag/vector_cypher_retriever.py"
    click GRA5 "https://github.com/neo4j-graphacademy/genai-workshop-graphrag/blob/main/2-neo4j-graphrag/vector_retriever.py"
    click GRA6 "https://github.com/neo4j-graphacademy/genai-workshop-graphrag/blob/main/2-neo4j-graphrag/multimodal_app.py"
    click GRASol "https://github.com/neo4j-graphacademy/genai-workshop-graphrag/tree/main/2-neo4j-graphrag/solutions/"

    %% Click Events for Environment & Configuration
    click EC1 "https://github.com/neo4j-graphacademy/genai-workshop-graphrag/blob/main/.devcontainer"
    click EC2 "https://github.com/neo4j-graphacademy/genai-workshop-graphrag/blob/main/.env.example"
    click EC3 "https://github.com/neo4j-graphacademy/genai-workshop-graphrag/blob/main/SETUP.md"

    %% Click Events for Testing & Example Solutions
    click T1 "https://github.com/neo4j-graphacademy/genai-workshop-graphrag/blob/main/conftest.py"
    click T2 "https://github.com/neo4j-graphacademy/genai-workshop-graphrag/blob/main/test_environment.py"

    %% Styles
    classDef logic fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef env fill:#ffedcc,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
    classDef database fill:#bbdefb,stroke:#333,stroke-width:2px;
    classDef test fill:#e0e0e0,stroke:#333,stroke-width:2px;
```
