# georgeaaron7/graph-rag architecture

> Architecture diagram of the GitHub repository georgeaaron7/graph-rag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/georgeaaron7/graph-rag
- Repository: https://github.com/georgeaaron7/graph-rag

## Overview

GraphRAG Knowledge Assistant ingests PDFs into shared, provenance-tagged chunks, indexes them in FAISS and extracts entity relationships into Neo4j. For questions, the backend retrieves semantically similar chunks and traverses graph relationships from query entities, then fuses both rankings and generates a cited answer, optionally streamed to the frontend. The UI supports PDF upload, chat, citations, and a provenance visualization. The graph follows the sampled pipeline and endpoint calls; some modules, including PDF loading, graph extraction, and answer generation, are represented from their paths and documented behavior, but their internals were not sampled.

Main entry points: [`backend/app/pipeline.py`](https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/pipeline.py) (Ingest and query), [`frontend/app/page.tsx`](https://github.com/georgeaaron7/graph-rag/blob/master/frontend/app/page.tsx) (Chat interface), [`backend/app/main.py`](https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/main.py) (HTTP endpoints), [`frontend/app/lib/api.ts`](https://github.com/georgeaaron7/graph-rag/blob/master/frontend/app/lib/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_page["Chat interface<br/>[page.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_provenance["Provenance graph"]
end

subgraph group_api["API and orchestration"]
  node_fastapi["HTTP endpoints<br/>[main.py]"]
  node_pipeline["Ingest and query<br/>[pipeline.py]"]
end

subgraph group_ingestion["Ingestion and indexing"]
  node_pdf_loader["PDF loader<br/>[pdf_loader.py]"]
  node_chunking["Document chunking<br/>[chunking.py]"]
  node_embedder["Text embeddings<br/>[embeddings.py]"]
  node_extraction["Graph extraction<br/>[extraction.py]"]
end

subgraph group_retrieval["Retrieval and answers"]
  node_hybrid["Rank fusion<br/>[hybrid.py]"]
  node_answer["Cited answer<br/>[answer.py]"]
  node_llm_client["LLM client<br/>[client.py]"]
end

subgraph group_stores["Knowledge stores"]
  node_vector_store[("Vector index<br/>[store.py]")]
  node_graph_store[("Knowledge graph<br/>[store.py]")]
end

node_user(("User"))
node_model_service{{"LLM service"}}
node_embedding_service{{"Embedding API"}}
node_neo4j[("Neo4j")]
node_faiss[("FAISS index")]

node_user -->|"asks or uploads"| node_page
node_page -->|"calls"| node_api_client
node_page -->|"renders citations"| node_provenance
node_api_client -->|"sends requests"| node_fastapi
node_fastapi -->|"dispatches ingest and chat"| node_pipeline
node_pipeline -->|"loads PDF pages"| node_pdf_loader
node_pipeline -->|"chunks text"| node_chunking
node_pipeline -->|"embeds chunks and queries"| node_embedder
node_pipeline -->|"adds and searches chunks"| node_vector_store
node_pipeline -->|"extracts chunk relations"| node_extraction
node_extraction -->|"requests extraction"| node_llm_client
node_pipeline -->|"upserts graph and retrieves"| node_graph_store
node_graph_store -->|"reads and writes"| node_neo4j
node_vector_store -->|"persists and searches"| node_faiss
node_embedder -.->|"requests embeddings"| node_embedding_service
node_pipeline -->|"fuses retrieval hits"| node_hybrid
node_pipeline -->|"generates grounded answer"| node_answer
node_answer -->|"requests answer"| node_llm_client
node_llm_client -->|"sends chat requests"| node_model_service
node_fastapi -->|"returns answers and citations"| node_api_client

click node_page "https://github.com/georgeaaron7/graph-rag/blob/master/frontend/app/page.tsx"
click node_api_client "https://github.com/georgeaaron7/graph-rag/blob/master/frontend/app/lib/api.ts"
click node_provenance "https://github.com/georgeaaron7/graph-rag/blob/master/frontend/app/components/ProvenanceGraph.tsx"
click node_fastapi "https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/main.py"
click node_pipeline "https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/pipeline.py"
click node_pdf_loader "https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/ingestion/pdf_loader.py"
click node_chunking "https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/ingestion/chunking.py"
click node_embedder "https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/vector/embeddings.py"
click node_extraction "https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/graph/extraction.py"
click node_vector_store "https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/vector/store.py"
click node_graph_store "https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/graph/store.py"
click node_hybrid "https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/retrieval/hybrid.py"
click node_answer "https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/rag/answer.py"
click node_llm_client "https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/llm/client.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_page,node_api_client,node_provenance,node_user toneBlue
class node_fastapi,node_pipeline,node_neo4j,node_faiss toneAmber
class node_pdf_loader,node_chunking,node_embedder,node_extraction,node_embedding_service toneMint
class node_hybrid,node_answer,node_llm_client toneRose
class node_vector_store,node_graph_store,node_model_service toneIndigo
```

## Components

### User interface

- [Chat interface](https://github.com/georgeaaron7/graph-rag/blob/master/frontend/app/page.tsx): `frontend/app/page.tsx`
- [API client](https://github.com/georgeaaron7/graph-rag/blob/master/frontend/app/lib/api.ts): `frontend/app/lib/api.ts`
- [Provenance graph](https://github.com/georgeaaron7/graph-rag/blob/master/frontend/app/components/ProvenanceGraph.tsx): `frontend/app/components/ProvenanceGraph.tsx`

### API and orchestration

- [HTTP endpoints](https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/main.py): `backend/app/main.py`
- [Ingest and query](https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/pipeline.py): `backend/app/pipeline.py`

### Ingestion and indexing

- [PDF loader](https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/ingestion/pdf_loader.py): `backend/app/ingestion/pdf_loader.py`
- [Document chunking](https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/ingestion/chunking.py): `backend/app/ingestion/chunking.py`
- [Text embeddings](https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/vector/embeddings.py): `backend/app/vector/embeddings.py`
- [Graph extraction](https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/graph/extraction.py): `backend/app/graph/extraction.py`

### Retrieval and answers

- [Rank fusion](https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/retrieval/hybrid.py): `backend/app/retrieval/hybrid.py`
- [Cited answer](https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/rag/answer.py): `backend/app/rag/answer.py`
- [LLM client](https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/llm/client.py): `backend/app/llm/client.py`

### Knowledge stores

- [Vector index](https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/vector/store.py): `backend/app/vector/store.py`
- [Knowledge graph](https://github.com/georgeaaron7/graph-rag/blob/master/backend/app/graph/store.py): `backend/app/graph/store.py`

### Other components

- **User**
- **LLM service**
- **Embedding API**
- **Neo4j**
- **FAISS index**

## Connections

- User → Chat interface: asks or uploads
- Chat interface → API client: calls
- Chat interface → Provenance graph: renders citations
- API client → HTTP endpoints: sends requests
- HTTP endpoints → Ingest and query: dispatches ingest and chat
- Ingest and query → PDF loader: loads PDF pages
- Ingest and query → Document chunking: chunks text
- Ingest and query → Text embeddings: embeds chunks and queries
- Ingest and query → Vector index: adds and searches chunks
- Ingest and query → Graph extraction: extracts chunk relations
- Graph extraction → LLM client: requests extraction
- Ingest and query → Knowledge graph: upserts graph and retrieves
- Knowledge graph → Neo4j: reads and writes
- Vector index → FAISS index: persists and searches
- Text embeddings → Embedding API: requests embeddings
- Ingest and query → Rank fusion: fuses retrieval hits
- Ingest and query → Cited answer: generates grounded answer
- Cited answer → LLM client: requests answer
- LLM client → LLM service: sends chat requests
- HTTP endpoints → API client: returns answers and citations