# kamalesh346/graph_rag architecture

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

- Interactive diagram: https://gitdiagram.com/kamalesh346/graph_rag
- Repository: https://github.com/kamalesh346/graph_rag

## Overview

This repository is a legal-data preparation and GraphRAG retrieval system focused on Indian statutes and Supreme Court judgments. Its principal user workflow parses a legal query, expands statutory references through a knowledge graph, searches statute and judgment vectors, and reranks results. A separate statute pipeline validates, parses, enriches, chunks, and ingests statute data. The tree also documents judgment extraction and indexing capabilities; their internal wiring is only partly evidenced in the excerpts, so uncertain links are omitted.

Main entry points: [`scripts/retrieval/hybrid_reranker.py`](https://github.com/kamalesh346/graph_rag/blob/main/scripts/retrieval/hybrid_reranker.py) (Hybrid Search), [`scripts/main_statute_pipeline.py`](https://github.com/kamalesh346/graph_rag/blob/main/scripts/main_statute_pipeline.py) (Statute Orchestrator), [`scripts/extract_pdfs.py`](https://github.com/kamalesh346/graph_rag/blob/main/scripts/extract_pdfs.py) (PDF Extraction), [`scripts/statute_ingestion.py`](https://github.com/kamalesh346/graph_rag/blob/main/scripts/statute_ingestion.py) (Statute Ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_case_data["Judgment Data"]
  node_pdf_extract["PDF Extraction<br/>[extract_pdfs.py]"]
  node_case_parser["Judgment Parser"]
  node_case_normalize["Case Normalization"]
  node_case_chunk["Judgment Chunking"]
  node_case_index["Case Vector Index"]
  node_reference_analysis["Reference Analysis"]
  node_case_pdfs["Judgment PDFs"]
  node_extracted_cases["Extracted Cases"]
end

subgraph group_statute_data["Statute Pipeline"]
  node_statute_orchestrator["Statute Orchestrator"]
  node_statute_validation["Statute Validation"]
  node_statute_parser["Statute Parsing<br/>[statute_parser.py]"]
  node_statute_chunker["Statute Chunking<br/>[statute_chunker.py]"]
  node_statute_ingestion["Statute Ingestion"]
  node_normalized_statutes["Normalized Acts"]
end

subgraph group_retrieval["Legal Retrieval"]
  node_query_parser["Query Parsing<br/>[query_parser.py]"]
  node_hybrid_search["Hybrid Search<br/>[hybrid_reranker.py]"]
  node_graph_expansion["Graph Expansion<br/>[graph_retriever.py]"]
  node_retrieval_eval["Retrieval Evaluation"]
end

subgraph group_stores["Search Stores"]
  node_statute_vector[("Statute Vectors")]
  node_judgment_vectors[("Judgment Vectors")]
  node_legal_graph[("Statute Knowledge Graph")]
end

node_user(("Legal User"))
node_legal_researcher(("Legal Researcher"))

node_case_pdfs -->|"reads PDFs"| node_pdf_extract
node_pdf_extract -->|"parses pages"| node_case_parser
node_pdf_extract -->|"writes JSON"| node_extracted_cases
node_statute_orchestrator -->|"validates acts"| node_statute_validation
node_statute_orchestrator -->|"parses acts"| node_statute_parser
node_statute_orchestrator -->|"chunks sections"| node_statute_chunker
node_statute_orchestrator -->|"ingests chunks"| node_statute_ingestion
node_normalized_statutes -->|"reads acts"| node_statute_validation
node_statute_ingestion -->|"writes chunks"| node_statute_vector
node_statute_ingestion -->|"writes graph"| node_legal_graph
node_user -->|"submits query"| node_hybrid_search
node_hybrid_search -->|"parses intent"| node_query_parser
node_hybrid_search -->|"expands sections"| node_graph_expansion
node_graph_expansion -->|"queries graph"| node_legal_graph
node_hybrid_search -->|"searches statutes"| node_statute_vector
node_hybrid_search -->|"searches judgments"| node_judgment_vectors
node_retrieval_eval -->|"benchmarks search"| node_hybrid_search
node_legal_researcher -.->|"requests research"| node_hybrid_search

click node_pdf_extract "https://github.com/kamalesh346/graph_rag/blob/main/scripts/extract_pdfs.py"
click node_case_parser "https://github.com/kamalesh346/graph_rag/blob/main/scripts/parse_legal_sections.py"
click node_case_normalize "https://github.com/kamalesh346/graph_rag/blob/main/scripts/normalize_structured_cases.py"
click node_case_chunk "https://github.com/kamalesh346/graph_rag/blob/main/scripts/chunk_normalized_cases.py"
click node_case_index "https://github.com/kamalesh346/graph_rag/blob/main/scripts/build_chroma_index.py"
click node_reference_analysis "https://github.com/kamalesh346/graph_rag/blob/main/scripts/analyze_legal_references.py"
click node_statute_orchestrator "https://github.com/kamalesh346/graph_rag/blob/main/scripts/main_statute_pipeline.py"
click node_statute_validation "https://github.com/kamalesh346/graph_rag/blob/main/scripts/statute_validator.py"
click node_statute_parser "https://github.com/kamalesh346/graph_rag/blob/main/scripts/statute_parser.py"
click node_statute_chunker "https://github.com/kamalesh346/graph_rag/blob/main/scripts/statute_chunker.py"
click node_statute_ingestion "https://github.com/kamalesh346/graph_rag/blob/main/scripts/statute_ingestion.py"
click node_query_parser "https://github.com/kamalesh346/graph_rag/blob/main/scripts/retrieval/query_parser.py"
click node_hybrid_search "https://github.com/kamalesh346/graph_rag/blob/main/scripts/retrieval/hybrid_reranker.py"
click node_graph_expansion "https://github.com/kamalesh346/graph_rag/blob/main/scripts/retrieval/graph_retriever.py"
click node_retrieval_eval "https://github.com/kamalesh346/graph_rag/blob/main/scripts/retrieval/evaluate_retrieval.py"
click node_statute_vector "https://github.com/kamalesh346/graph_rag/blob/main/scripts/statute_ingestion.py"
click node_judgment_vectors "https://github.com/kamalesh346/graph_rag/blob/main/scripts/build_chroma_index.py"
click node_legal_graph "https://github.com/kamalesh346/graph_rag/blob/main/scripts/statute_ingestion.py"
click node_case_pdfs "https://github.com/kamalesh346/graph_rag/tree/main/data/judgement_pdf"
click node_extracted_cases "https://github.com/kamalesh346/graph_rag/tree/main/data/extracted"
click node_normalized_statutes "https://github.com/kamalesh346/graph_rag/tree/main/data/legal/acts"

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_pdf_extract,node_case_parser,node_case_normalize,node_case_chunk,node_case_index,node_reference_analysis,node_case_pdfs,node_extracted_cases,node_user toneBlue
class node_statute_orchestrator,node_statute_validation,node_statute_parser,node_statute_chunker,node_statute_ingestion,node_normalized_statutes toneAmber
class node_query_parser,node_hybrid_search,node_graph_expansion,node_retrieval_eval toneMint
class node_statute_vector,node_judgment_vectors,node_legal_graph toneRose
class node_legal_researcher toneIndigo
```

## Components

### Judgment Data

- [PDF Extraction](https://github.com/kamalesh346/graph_rag/blob/main/scripts/extract_pdfs.py): `scripts/extract_pdfs.py`
- [Judgment Parser](https://github.com/kamalesh346/graph_rag/blob/main/scripts/parse_legal_sections.py): `scripts/parse_legal_sections.py`
- [Case Normalization](https://github.com/kamalesh346/graph_rag/blob/main/scripts/normalize_structured_cases.py): `scripts/normalize_structured_cases.py`
- [Judgment Chunking](https://github.com/kamalesh346/graph_rag/blob/main/scripts/chunk_normalized_cases.py): `scripts/chunk_normalized_cases.py`
- [Case Vector Index](https://github.com/kamalesh346/graph_rag/blob/main/scripts/build_chroma_index.py): `scripts/build_chroma_index.py`
- [Reference Analysis](https://github.com/kamalesh346/graph_rag/blob/main/scripts/analyze_legal_references.py): `scripts/analyze_legal_references.py`
- [Judgment PDFs](https://github.com/kamalesh346/graph_rag/tree/main/data/judgement_pdf): `data/judgement_pdf`
- [Extracted Cases](https://github.com/kamalesh346/graph_rag/tree/main/data/extracted): `data/extracted`

### Statute Pipeline

- [Statute Orchestrator](https://github.com/kamalesh346/graph_rag/blob/main/scripts/main_statute_pipeline.py): `scripts/main_statute_pipeline.py`
- [Statute Validation](https://github.com/kamalesh346/graph_rag/blob/main/scripts/statute_validator.py): `scripts/statute_validator.py`
- [Statute Parsing](https://github.com/kamalesh346/graph_rag/blob/main/scripts/statute_parser.py): `scripts/statute_parser.py`
- [Statute Chunking](https://github.com/kamalesh346/graph_rag/blob/main/scripts/statute_chunker.py): `scripts/statute_chunker.py`
- [Statute Ingestion](https://github.com/kamalesh346/graph_rag/blob/main/scripts/statute_ingestion.py): `scripts/statute_ingestion.py`
- [Normalized Acts](https://github.com/kamalesh346/graph_rag/tree/main/data/legal/acts): `data/legal/acts`

### Legal Retrieval

- [Query Parsing](https://github.com/kamalesh346/graph_rag/blob/main/scripts/retrieval/query_parser.py): `scripts/retrieval/query_parser.py`
- [Hybrid Search](https://github.com/kamalesh346/graph_rag/blob/main/scripts/retrieval/hybrid_reranker.py): `scripts/retrieval/hybrid_reranker.py`
- [Graph Expansion](https://github.com/kamalesh346/graph_rag/blob/main/scripts/retrieval/graph_retriever.py): `scripts/retrieval/graph_retriever.py`
- [Retrieval Evaluation](https://github.com/kamalesh346/graph_rag/blob/main/scripts/retrieval/evaluate_retrieval.py): `scripts/retrieval/evaluate_retrieval.py`

### Search Stores

- [Statute Vectors](https://github.com/kamalesh346/graph_rag/blob/main/scripts/statute_ingestion.py): `scripts/statute_ingestion.py`
- [Judgment Vectors](https://github.com/kamalesh346/graph_rag/blob/main/scripts/build_chroma_index.py): `scripts/build_chroma_index.py`
- [Statute Knowledge Graph](https://github.com/kamalesh346/graph_rag/blob/main/scripts/statute_ingestion.py): `scripts/statute_ingestion.py`

### Other components

- **Legal User**
- **Legal Researcher**

## Connections

- Judgment PDFs → PDF Extraction: reads PDFs (evidence: `scripts/extract_pdfs.py`)
- PDF Extraction → Judgment Parser: parses pages (evidence: `scripts/extract_pdfs.py`)
- PDF Extraction → Extracted Cases: writes JSON (evidence: `scripts/extract_pdfs.py`)
- Statute Orchestrator → Statute Validation: validates acts (evidence: `scripts/main_statute_pipeline.py`)
- Statute Orchestrator → Statute Parsing: parses acts (evidence: `scripts/main_statute_pipeline.py`)
- Statute Orchestrator → Statute Chunking: chunks sections (evidence: `scripts/main_statute_pipeline.py`)
- Statute Orchestrator → Statute Ingestion: ingests chunks (evidence: `scripts/main_statute_pipeline.py`)
- Normalized Acts → Statute Validation: reads acts (evidence: `scripts/statute_validator.py`)
- Statute Ingestion → Statute Vectors: writes chunks (evidence: `scripts/statute_ingestion.py`)
- Statute Ingestion → Statute Knowledge Graph: writes graph (evidence: `scripts/statute_ingestion.py`)
- Legal User → Hybrid Search: submits query (evidence: `scripts/retrieval/hybrid_reranker.py`)
- Hybrid Search → Query Parsing: parses intent (evidence: `scripts/retrieval/hybrid_reranker.py`)
- Hybrid Search → Graph Expansion: expands sections (evidence: `scripts/retrieval/hybrid_reranker.py`)
- Graph Expansion → Statute Knowledge Graph: queries graph (evidence: `scripts/retrieval/graph_retriever.py`)
- Hybrid Search → Statute Vectors: searches statutes
- Hybrid Search → Judgment Vectors: searches judgments (evidence: `scripts/retrieval/hybrid_reranker.py`)
- Retrieval Evaluation → Hybrid Search: benchmarks search (evidence: `scripts/retrieval/evaluate_retrieval.py`)
- Legal Researcher → Hybrid Search: requests research
