# bhavy-ranka/graphitti architecture

> Architecture diagram of the GitHub repository bhavy-ranka/graphitti, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bhavy-ranka/graphitti
- Repository: https://github.com/bhavy-ranka/graphitti

## Overview

#### Purpose and Entry Points
Graphitti builds a temporary, graph-native knowledge base from a crawled website, then answers questions using routed text and graph retrieval. The primary backend entry point is `graphitti/api/app.py`; interactive use is through `graphitti/streamlit_app.py`. The API serves an interactive graph view from `graphitti/api/static/graph.html`.

#### Ingestion Control Flow
An ingest request orchestrates crawl-to-graph construction. By default it resets prior graph and text-index state, enforcing a single active crawled corpus. The central workflow is implemented in `graphitti/orchestration/orchestrator.py`, using crawl output from `graphitti/crawling/crawler.py` and graph loading in `graphitti/graph/loader.py`.

#### Crawl and Local Extraction
The crawler performs breadth-first browser crawling with Playwright in `graphitti/crawling/crawler.py`. Page text is segmented into sentence-aware chunks by `graphitti/extraction/chunking.py`. `graphitti/extraction/nlp_pipeline.py` and `graphitti/extraction/triple_extractor.py` derive entity-relation-entity triples locally with NLTK POS tagging, NER, grammar rules, SVO/passive handling, pronoun heuristics, and confidence scoring; extraction does not call an LLM.

#### Entity and Graph Quality Boundary
Extracted triples use typed schemas in `graphitti/extraction/schemas.py`, then pass through direction normalization and alias/entity merging in `graphitti/extraction/direction.py` and `graphitti/extraction/entity_resolution.py`. Graph conflict detection marks contested relationships before persistence in `graphitti/graph/consistency.py`. This separates noisy web-text interpretation from graph storage and retrieval.

#### Graph and Text Persistence
`graphitti/graph/store.py` provides Neo4j and in-memory graph-store implementations. `graphitti/graph/loader.py` batch-loads nodes and edges through Neo4j `UNWIND`/`MERGE` operations with rollback behavior. Raw chunks remain addressable in `graphitti/retrieval/text_index.py` for textual evidence and citations. Neo4j is the material external persistence dependency; Playwright/Chromium is required for crawling.

#### Query Routing and Retrieval
Questions enter intent classification and decomposition chains in `graphitti/routing/chains.py`, with strategy selection and confidence fallback in `graphitti/routing/query_router.py`. Low-confidence routing selects hybrid retrieval. Available evidence sources are BM25 (`graphitti/retrieval/bm25.py`), dense vector search with Sentence-Transformers or TF-IDF fallback (`graphitti/retrieval/dense.py`), and entity/multi-hop graph traversal (`graphitti/retrieval/graph_retrieval.py`). `graphitti/retrieval/base.py` registers strategies and combines rankings with reciprocal-rank fusion.

#### Answer Orchestration and Presentation
A LangGraph state machine coordinates routing, retrieval, and final synthesis in `graphitti/orchestration/orchestrator.py`. `graphitti/orchestration/synthesis_chain.py` produces provenance-backed answers from retrieved graph/text evidence. FastAPI exposes ingest, query, and graph-facing operations in `graphitti/api/app.py`; Streamlit drives those APIs and refreshes the visualized graph after each reset-and-ingest cycle.

Main entry points: [`graphitti/retrieval/base.py`](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/retrieval/base.py) (Evidence Retrieval), [`graphitti/api/app.py`](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/api/app.py) (FastAPI API), [`graphitti/orchestration/orchestrator.py`](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/orchestration/orchestrator.py) (Workflow Orchestrator), [`graphitti/extraction/chunking.py`](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/extraction/chunking.py) (Sentence Chunking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interfaces"]
  node_streamlit["Streamlit UI<br/>interactive client<br/>[streamlit_app.py]"]
  node_api["FastAPI API<br/>service entry point<br/>[app.py]"]
  node_graph_view["Graph Viewer<br/>static UI<br/>[graph.html]"]
end

subgraph group_ingestion["Ingestion"]
  node_orchestrator{{"Workflow Orchestrator<br/>LangGraph workflow<br/>[orchestrator.py]"}}
  node_crawler["Browser Crawler<br/>BFS Playwright crawler<br/>[crawler.py]"]
  node_chunking["Sentence Chunking<br/>text processing<br/>[chunking.py]"]
  node_triple_extraction["Local Triple Extraction<br/>NLP extraction<br/>[nlp_pipeline.py]"]
  node_triple_rules["Triple Rules<br/>NLP extraction rules"]
  node_schemas["Triple Schemas<br/>typed contracts<br/>[schemas.py]"]
  node_entity_quality["Entity Quality<br/>normalization boundary"]
end

subgraph group_knowledge["Knowledge Store"]
  node_consistency["Conflict Detection<br/>graph validation<br/>[consistency.py]"]
  node_graph_loader["Graph Loader<br/>batch persistence<br/>[loader.py]"]
  node_graph_store[("Graph Store<br/>persistence abstraction<br/>[store.py]")]
  node_neo4j[("Neo4j<br/>external graph database")]
  node_text_index[("Text Index<br/>chunk evidence index<br/>[text_index.py]")]
end

subgraph group_query["Query &amp; Answering"]
  node_query_router{{"Query Router<br/>intent routing<br/>[query_router.py]"}}
  node_routing_chains["Intent Chains<br/>query analysis<br/>[chains.py]"]
  node_retrieval["Evidence Retrieval<br/>strategy registry<br/>[base.py]"]
  node_bm25["BM25 Search<br/>text retrieval<br/>[bm25.py]"]
  node_dense["Dense Search<br/>vector retrieval<br/>[dense.py]"]
  node_graph_retrieval["Graph Traversal<br/>graph retrieval<br/>[graph_retrieval.py]"]
  node_synthesis["Answer Synthesis<br/>provenance answer chain<br/>[synthesis_chain.py]"]
end

node_streamlit -->|"uses"| node_api
node_api -->|"serves"| node_graph_view
node_api -->|"ingest and query"| node_orchestrator
node_orchestrator -->|"crawl"| node_crawler
node_crawler -->|"page text"| node_chunking
node_chunking -->|"chunks"| node_triple_extraction
node_triple_extraction -->|"extracts via"| node_triple_rules
node_triple_rules -->|"typed triples"| node_schemas
node_schemas -->|"normalize and merge"| node_entity_quality
node_entity_quality -->|"validated triples"| node_consistency
node_consistency -->|"loadable graph"| node_graph_loader
node_graph_loader -->|"batch writes"| node_graph_store
node_graph_store -->|"persists"| node_neo4j
node_chunking -->|"raw chunks"| node_text_index
node_orchestrator -->|"questions"| node_query_router
node_query_router -->|"classify and decompose"| node_routing_chains
node_query_router -->|"strategy"| node_retrieval
node_retrieval -->|"text search"| node_bm25
node_retrieval -->|"vector search"| node_dense
node_retrieval -->|"graph search"| node_graph_retrieval
node_bm25 -->|"searches"| node_text_index
node_dense -->|"searches"| node_text_index
node_graph_retrieval -->|"traverses"| node_graph_store
node_retrieval -->|"ranked evidence"| node_synthesis
node_synthesis -->|"answer"| node_api

click node_streamlit "https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/streamlit_app.py"
click node_api "https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/api/app.py"
click node_graph_view "https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/api/static/graph.html"
click node_orchestrator "https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/orchestration/orchestrator.py"
click node_crawler "https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/crawling/crawler.py"
click node_chunking "https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/extraction/chunking.py"
click node_triple_extraction "https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/extraction/nlp_pipeline.py"
click node_triple_rules "https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/extraction/triple_extractor.py"
click node_schemas "https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/extraction/schemas.py"
click node_entity_quality "https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/extraction/entity_resolution.py"
click node_consistency "https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/graph/consistency.py"
click node_graph_loader "https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/graph/loader.py"
click node_graph_store "https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/graph/store.py"
click node_text_index "https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/retrieval/text_index.py"
click node_query_router "https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/routing/query_router.py"
click node_routing_chains "https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/routing/chains.py"
click node_retrieval "https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/retrieval/base.py"
click node_bm25 "https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/retrieval/bm25.py"
click node_dense "https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/retrieval/dense.py"
click node_graph_retrieval "https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/retrieval/graph_retrieval.py"
click node_synthesis "https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/orchestration/synthesis_chain.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_streamlit,node_api,node_graph_view toneBlue
class node_orchestrator,node_crawler,node_chunking,node_triple_extraction,node_triple_rules,node_schemas,node_entity_quality toneAmber
class node_consistency,node_graph_loader,node_graph_store,node_neo4j,node_text_index toneMint
class node_query_router,node_routing_chains,node_retrieval,node_bm25,node_dense,node_graph_retrieval,node_synthesis toneRose
```

## Components

### Interfaces

- [Streamlit UI](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/streamlit_app.py): interactive client · Drives API workflows and graph refreshes. · `graphitti/streamlit_app.py`
- [FastAPI API](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/api/app.py): service entry point · Exposes ingest, query, and graph operations. · `graphitti/api/app.py`
- [Graph Viewer](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/api/static/graph.html): static UI · `graphitti/api/static/graph.html`

### Ingestion

- [Workflow Orchestrator](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/orchestration/orchestrator.py): LangGraph workflow · Coordinates ingestion and routed answer generation. · `graphitti/orchestration/orchestrator.py`
- [Browser Crawler](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/crawling/crawler.py): BFS Playwright crawler · Crawls website pages through Chromium. · `graphitti/crawling/crawler.py`
- [Sentence Chunking](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/extraction/chunking.py): text processing · `graphitti/extraction/chunking.py`
- [Local Triple Extraction](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/extraction/nlp_pipeline.py): NLP extraction · Derives scored entity-relation-entity triples without an LLM. · `graphitti/extraction/nlp_pipeline.py`
- [Triple Rules](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/extraction/triple_extractor.py): NLP extraction rules · Handles SVO, passive voice, and pronoun heuristics. · `graphitti/extraction/triple_extractor.py`
- [Triple Schemas](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/extraction/schemas.py): typed contracts · `graphitti/extraction/schemas.py`
- [Entity Quality](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/extraction/entity_resolution.py): normalization boundary · Normalizes relation direction and merges aliases. · `graphitti/extraction/entity_resolution.py`

### Knowledge Store

- [Conflict Detection](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/graph/consistency.py): graph validation · Marks contested relationships before persistence. · `graphitti/graph/consistency.py`
- [Graph Loader](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/graph/loader.py): batch persistence · Loads nodes and edges with rollback behavior. · `graphitti/graph/loader.py`
- [Graph Store](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/graph/store.py): persistence abstraction · Provides Neo4j and in-memory implementations. · `graphitti/graph/store.py`
- **Neo4j**: external graph database · Material graph persistence dependency.
- [Text Index](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/retrieval/text_index.py): chunk evidence index · Keeps raw chunks addressable for evidence and citations. · `graphitti/retrieval/text_index.py`

### Query & Answering

- [Query Router](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/routing/query_router.py): intent routing · Selects retrieval strategy and falls back to hybrid on low confidence. · `graphitti/routing/query_router.py`
- [Intent Chains](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/routing/chains.py): query analysis · Classifies and decomposes questions. · `graphitti/routing/chains.py`
- [Evidence Retrieval](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/retrieval/base.py): strategy registry · Combines BM25, dense, and graph rankings with reciprocal-rank fusion. · `graphitti/retrieval/base.py`
- [BM25 Search](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/retrieval/bm25.py): text retrieval · `graphitti/retrieval/bm25.py`
- [Dense Search](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/retrieval/dense.py): vector retrieval · Uses Sentence-Transformers or TF-IDF fallback. · `graphitti/retrieval/dense.py`
- [Graph Traversal](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/retrieval/graph_retrieval.py): graph retrieval · Performs entity and multi-hop traversal. · `graphitti/retrieval/graph_retrieval.py`
- [Answer Synthesis](https://github.com/bhavy-ranka/graphitti/blob/main/graphitti/orchestration/synthesis_chain.py): provenance answer chain · Produces answers from graph and text evidence. · `graphitti/orchestration/synthesis_chain.py`

## Connections

- Streamlit UI → FastAPI API: uses
- FastAPI API → Graph Viewer: serves
- FastAPI API → Workflow Orchestrator: ingest and query
- Workflow Orchestrator → Browser Crawler: crawl
- Browser Crawler → Sentence Chunking: page text
- Sentence Chunking → Local Triple Extraction: chunks
- Local Triple Extraction → Triple Rules: extracts via
- Triple Rules → Triple Schemas: typed triples
- Triple Schemas → Entity Quality: normalize and merge
- Entity Quality → Conflict Detection: validated triples
- Conflict Detection → Graph Loader: loadable graph
- Graph Loader → Graph Store: batch writes
- Graph Store → Neo4j: persists
- Sentence Chunking → Text Index: raw chunks
- Workflow Orchestrator → Query Router: questions
- Query Router → Intent Chains: classify and decompose
- Query Router → Evidence Retrieval: strategy
- Evidence Retrieval → BM25 Search: text search
- Evidence Retrieval → Dense Search: vector search
- Evidence Retrieval → Graph Traversal: graph search
- BM25 Search → Text Index: searches
- Dense Search → Text Index: searches
- Graph Traversal → Graph Store: traverses
- Evidence Retrieval → Answer Synthesis: ranked evidence
- Answer Synthesis → FastAPI API: answer