# binnong/llm-graph-builder architecture

> Architecture diagram of the GitHub repository binnong/llm-graph-builder, 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/binnong/llm-graph-builder
- Repository: https://github.com/binnong/llm-graph-builder

## Overview

##### Main Components
- Frontend: Built with React (using tools like Vite, Tailwind, ESLint, etc.) located in the “frontend” directory. It is responsible for user interactions such as file uploads, choosing LLM models, setting schemas, viewing generated graphs, and chatting with the data.
- Backend: A FastAPI-based service (Python) in the “backend” folder. It contains multiple modules for processing unstructured data, integrating LLMs (OpenAI, Diffbot, Gemini, etc.), managing document sources, handling chunking, and interfacing with Neo4j.
- Data Sources: The system supports multiple file sources, including local file uploads, AWS S3 buckets, Google Cloud Storage (GCS), YouTube, web pages, and Wikipedia. This is apparent from both the README and the many document source modules found in the backend (e.g., local_file.py, s3_bucket.py, gcs_bucket.py, web_pages.py, wikipedia.py, youtube.py).
- Knowledge Graph Database: It integrates with a Neo4j database (with APOC extension) that stores nodes, relationships, and metadata extracted from files.
- LLM and Processing Modules: The backend’s modules (such as QA_integration.py, llm.py, openAI_llm.py, and others) indicate that the system uses different LLMs to extract and process information.
- Orchestration/Infrastructure: Docker and docker-compose are used for deployment and local setup, and the project includes configuration files (.env files in both frontend and backend) that determine environment-specific settings.

##### Relationships and Interactions
- The user interacts with the Frontend UI to upload files, select data sources and LLM models, and set the knowledge graph schema.
- The Frontend calls API endpoints exposed by the Backend (via FastAPI) to initiate file processing, graph extraction, or chat queries.
- The Backend accepts incoming requests, reads configuration/environment variables, interfaces with various document sources (such as local files or S3 buckets), and then hands the data over to the appropriate LLM processing module to extract nodes and relationships.
- After processing, the processed information is stored as a structured knowledge graph in the Neo4j database.
- When a user requests to view the knowledge graph (or chat with the data), the backend queries Neo4j and returns the data back to the frontend.
- Additionally, the system supports advanced features such as chunking for large files, embedding generation, and configurable chat modes (vector, graph+vector, graph).

##### Architectural Patterns and Design Principles
- Separation of Concerns: The frontend and backend are clearly separated, with the backend managing business logic and data processing while the frontend is solely responsible for the user interface.
- Modular Design: The backend organizes its source code into modules and subdirectories based on functionality (e.g., document sources, entities, graph transformers, shared utilities). This modularity helps isolate responsibilities.
- Service-Oriented Architecture: The backend acts as an API service with clearly defined endpoints, and each module (or service component) handles a specific task such as LLM integration or Neo4j data access.
- Containerization: The inclusion of Dockerfiles and a docker-compose file indicates that containerization is used for consistent deployments and integrating multiple services in one environment.
- Configurability and Environment-Driven Behavior: The extensive use of environment variables and example configuration files (.env and example.env) shows that the system is built to be easily configured for different deployment environments.

##### Relevant Technologies and Frameworks
- Frontend: React (with TypeScript), Vite, Tailwind CSS, and supporting libraries for UI components.
- Backend: Python with FastAPI, Uvicorn for serving the API, and multiple Python modules that integrate with LLMs.
- LLM Integrations: Modules for several LLM providers (OpenAI, Diffbot, Gemini, etc.) indicate multi-model support.
- Database: Neo4j (version ≥ 5.15) with APOC installed for graph storage and querying.
- Orchestration: Docker and Docker Compose for containerized deployment, as well as scripts for cloud deployment (e.g., on Google Cloud Run).

##### Additional Detailed Suggestions
- Details from the README such as LLM model selection and document source configurations.
- Visually including the environment variables that affect system behavior (e.g., keys for OpenAI, Diffbot, Neo4j connection details) in a configuration block or side note.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    User["User"]:::user

    %% Frontend Layer
    F["Frontend (React UI)"]:::frontend

    %% Backend Layer
    B["Backend (FastAPI API)"]:::backend

    %% Subgraph: Backend Service Components
    subgraph "Backend Service Components"
        DS["Document Sources Modules"]:::document
        LLM["LLM Processing Modules"]:::llm
        GT["Graph Transformation Utilities"]:::transformation
        DB["GraphDB Access"]:::database
        GQ["Graph Query"]:::database
        Shared["Shared Utilities & Configurations"]:::utility
    end

    %% Subgraph: Deployment & Configurations
    subgraph "Containerization & Deployment"
        DS1["Docker Compose"]:::deployment
        BDock["Backend Dockerfile"]:::deployment
        FDock["Frontend Dockerfile"]:::deployment
        BEEnv["Backend Env Config"]:::deployment
        FEEnv["Frontend Env Config"]:::deployment
    end

    %% Connections
    User -->|"interacts"| F
    F -->|"calls"| B

    %% Backend internal flow
    B -->|"file_process"| DS
    B -->|"llm_integration"| LLM

    DS -->|"extract_text"| GT
    LLM -->|"extract_info"| GT

    GT -->|"store_graph"| DB
    GT -->|"query_graph"| GQ

    DB -->|"response"| B
    GQ -->|"response"| B

    %% Shared Utilities usage (dotted lines)
    DS -.->|"uses"| Shared
    LLM -.->|"uses"| Shared
    GT -.->|"uses"| Shared
    DB -.->|"uses"| Shared
    GQ -.->|"uses"| Shared

    %% Deployment connections (dotted lines to indicate containerized deployment)
    DS1 ---|"deploys"| F
    DS1 ---|"deploys"| B
    BDock ---|"builds"| B
    FDock ---|"builds"| F
    BEEnv ---|"configures"| B
    FEEnv ---|"configures"| F

    %% Styles
    classDef user fill:#E6E6FA,stroke:#000,stroke-width:2px;
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef document fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef llm fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef transformation fill:#F08080,stroke:#000,stroke-width:2px;
    classDef database fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef utility fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef deployment fill:#AFEEEE,stroke:#000,stroke-width:2px;

click F "https://github.com/binnong/llm-graph-builder/tree/main/frontend/"
click B "https://github.com/binnong/llm-graph-builder/tree/main/backend/"
click DS "https://github.com/binnong/llm-graph-builder/tree/main/backend/src/document_sources/"
click LLM "https://github.com/binnong/llm-graph-builder/blob/main/backend/src/llm.py"
click DB "https://github.com/binnong/llm-graph-builder/blob/main/backend/src/graphDB_dataAccess.py"
click GQ "https://github.com/binnong/llm-graph-builder/blob/main/backend/src/graph_query.py"
click GT "https://github.com/binnong/llm-graph-builder/tree/main/backend/src/graph_transformers/"
click Shared "https://github.com/binnong/llm-graph-builder/tree/main/backend/src/shared/"
click DS1 "https://github.com/binnong/llm-graph-builder/blob/main/docker-compose.yml"
click BDock "https://github.com/binnong/llm-graph-builder/tree/main/backend/Dockerfile"
click FDock "https://github.com/binnong/llm-graph-builder/tree/main/frontend/Dockerfile"
click BEEnv "https://github.com/binnong/llm-graph-builder/blob/main/backend/example.env"
click FEEnv "https://github.com/binnong/llm-graph-builder/blob/main/frontend/example.env"
```
