# ishandikshit/sniprag architecture

> Architecture diagram of the GitHub repository ishandikshit/sniprag, 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/ishandikshit/sniprag
- Repository: https://github.com/ishandikshit/sniprag

## Overview

SnipRAG turns PDFs into searchable text chunks linked to page coordinates and rendered images, then returns semantic matches with visual snippets. The main workflow is engine selection, local or S3 document ingestion, strategy-specific text extraction, embedding and indexing, followed by filtered search and snippet delivery. The semantic and OCR strategies are distinct extraction paths; both share the base engine’s indexing and search behavior. README capabilities guide the map where excerpts are incomplete, so uncertain internal wiring is omitted.

Main entry points: [`sniprag/core/base_engine.py`](https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/base_engine.py) (Base Engine), [`sniprag/core/ocr_engine.py`](https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/ocr_engine.py) (OCR Strategy), [`sniprag/core/semantic_engine.py`](https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/semantic_engine.py) (Semantic Strategy), [`sniprag/core/__init__.py`](https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/__init__.py) (Strategy Factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Engine API"]
  node_factory["Strategy Factory<br/>[__init__.py]"]
  node_base["Base Engine<br/>[base_engine.py]"]
end

subgraph group_ingestion["PDF Ingestion"]
  node_semantic["Semantic Strategy<br/>[semantic_engine.py]"]
  node_ocr["OCR Strategy<br/>[ocr_engine.py]"]
end

subgraph group_retrieval["Search And Snippets"]
  node_embedding["Text Embeddings<br/>[base_engine.py]"]
  node_search["Semantic Search<br/>[base_engine.py]"]
  node_snippet["Snippet Extraction<br/>[base_engine.py]"]
  node_results["Text And Image Results<br/>[base_engine.py]"]
end

subgraph group_state["Index And Assets"]
  node_vector[("FAISS Index<br/>[base_engine.py]")]
  node_metadata[("Chunk Metadata<br/>[base_engine.py]")]
  node_images[("Page And Slice Images<br/>[base_engine.py]")]
end

node_user(("Application User"))
node_pdf["PDF Documents"]
node_s3[("Amazon S3")]
node_pymupdf["PyMuPDF"]
node_tesseract["Tesseract OCR"]

node_user -->|"selects strategy"| node_factory
node_factory -->|"creates semantic"| node_semantic
node_factory -->|"creates OCR"| node_ocr
node_user -->|"submits PDF and query"| node_base
node_base -.->|"downloads PDF"| node_s3
node_base -->|"dispatches extraction"| node_semantic
node_base -->|"dispatches extraction"| node_ocr
node_semantic -->|"reads PDF"| node_pdf
node_ocr -->|"reads PDF"| node_pdf
node_semantic -->|"extracts text and renders"| node_pymupdf
node_ocr -->|"renders pages"| node_pymupdf
node_ocr -->|"recognizes slice text"| node_tesseract
node_semantic -->|"stores page images"| node_images
node_ocr -->|"stores page and slice images"| node_images
node_semantic -->|"returns text chunks"| node_base
node_ocr -->|"returns text chunks"| node_base
node_base -->|"embeds chunks and queries"| node_embedding
node_base -->|"adds and searches vectors"| node_vector
node_base -->|"stores chunks and coordinates"| node_metadata
node_user -->|"requests filtered search"| node_search
node_search -->|"embeds query"| node_embedding
node_search -->|"retrieves matches"| node_vector
node_search -->|"filters and reads matches"| node_metadata
node_search -->|"requests snippets"| node_snippet
node_snippet -->|"reads coordinates"| node_metadata
node_snippet -->|"crops visual context"| node_images
node_snippet -->|"adds image snippet"| node_results
node_search -->|"returns text and scores"| node_results
node_results -->|"delivers matches"| node_user

click node_factory "https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/__init__.py"
click node_base "https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/base_engine.py"
click node_semantic "https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/semantic_engine.py"
click node_ocr "https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/ocr_engine.py"
click node_embedding "https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/base_engine.py"
click node_vector "https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/base_engine.py"
click node_metadata "https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/base_engine.py"
click node_images "https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/base_engine.py"
click node_search "https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/base_engine.py"
click node_snippet "https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/base_engine.py"
click node_results "https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/base_engine.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_factory,node_base,node_user toneBlue
class node_semantic,node_ocr,node_s3 toneAmber
class node_embedding,node_search,node_snippet,node_results toneMint
class node_vector,node_metadata,node_images toneRose
class node_pdf,node_pymupdf,node_tesseract toneIndigo
```

## Components

### Engine API

- [Strategy Factory](https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/__init__.py): `sniprag/core/__init__.py`
- [Base Engine](https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/base_engine.py): `sniprag/core/base_engine.py`

### PDF Ingestion

- [Semantic Strategy](https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/semantic_engine.py): `sniprag/core/semantic_engine.py`
- [OCR Strategy](https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/ocr_engine.py): `sniprag/core/ocr_engine.py`

### Search And Snippets

- [Text Embeddings](https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/base_engine.py): `sniprag/core/base_engine.py`
- [Semantic Search](https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/base_engine.py): `sniprag/core/base_engine.py`
- [Snippet Extraction](https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/base_engine.py): `sniprag/core/base_engine.py`
- [Text And Image Results](https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/base_engine.py): `sniprag/core/base_engine.py`

### Index And Assets

- [FAISS Index](https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/base_engine.py): `sniprag/core/base_engine.py`
- [Chunk Metadata](https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/base_engine.py): `sniprag/core/base_engine.py`
- [Page And Slice Images](https://github.com/ishandikshit/sniprag/blob/main/sniprag/core/base_engine.py): `sniprag/core/base_engine.py`

### Other components

- **Application User**
- **PDF Documents**
- **Amazon S3**
- **PyMuPDF**
- **Tesseract OCR**

## Connections

- Application User → Strategy Factory: selects strategy
- Strategy Factory → Semantic Strategy: creates semantic
- Strategy Factory → OCR Strategy: creates OCR
- Application User → Base Engine: submits PDF and query
- Base Engine → Amazon S3: downloads PDF
- Base Engine → Semantic Strategy: dispatches extraction
- Base Engine → OCR Strategy: dispatches extraction
- Semantic Strategy → PDF Documents: reads PDF
- OCR Strategy → PDF Documents: reads PDF
- Semantic Strategy → PyMuPDF: extracts text and renders
- OCR Strategy → PyMuPDF: renders pages
- OCR Strategy → Tesseract OCR: recognizes slice text
- Semantic Strategy → Page And Slice Images: stores page images
- OCR Strategy → Page And Slice Images: stores page and slice images
- Semantic Strategy → Base Engine: returns text chunks
- OCR Strategy → Base Engine: returns text chunks
- Base Engine → Text Embeddings: embeds chunks and queries
- Base Engine → FAISS Index: adds and searches vectors
- Base Engine → Chunk Metadata: stores chunks and coordinates
- Application User → Semantic Search: requests filtered search
- Semantic Search → Text Embeddings: embeds query
- Semantic Search → FAISS Index: retrieves matches
- Semantic Search → Chunk Metadata: filters and reads matches
- Semantic Search → Snippet Extraction: requests snippets
- Snippet Extraction → Chunk Metadata: reads coordinates
- Snippet Extraction → Page And Slice Images: crops visual context
- Snippet Extraction → Text And Image Results: adds image snippet
- Semantic Search → Text And Image Results: returns text and scores
- Text And Image Results → Application User: delivers matches