# sinapars9/doclens architecture

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

- Interactive diagram: https://gitdiagram.com/sinapars9/doclens
- Repository: https://github.com/sinapars9/doclens

## Overview

DocLens is a Streamlit PDF question-answering assistant. Users upload and select documents, the system parses and indexes them, then resolves the question, retrieves and reranks evidence, streams an answer, and verifies its claims. The graph preserves documented multi-document scope, parent-child retrieval, caching, and human feedback. The pipeline excerpt omits some orchestration calls, so documented links use the README; unsampled implementation details are not inferred.

Main entry points: [`pipeline.py`](https://github.com/sinapars9/doclens/blob/main/pipeline.py) (RAG orchestrator), [`chunk_pdf.py`](https://github.com/sinapars9/doclens/blob/main/chunk_pdf.py) (Semantic chunks), [`vector_store.py`](https://github.com/sinapars9/doclens/blob/main/vector_store.py) (Vector store), [`query_rewriter.py`](https://github.com/sinapars9/doclens/blob/main/query_rewriter.py) (Query resolution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["PDF ingestion"]
  node_pdf["PDF extraction<br/>[inspect_pdf.py]"]
  node_chunks["Semantic chunks<br/>[chunk_pdf.py]"]
  node_embedding["ONNX embeddings<br/>[embedding.py]"]
  node_context["Chunk context<br/>[contextualizer.py]"]
  node_settings["Model settings<br/>[config.py]"]
end

subgraph group_search["Search and context"]
  node_store[("Vector store<br/>[vector_store.py]")]
  node_retriever["Hybrid retrieval<br/>[retriever.py]"]
  node_rewriter["Query resolution<br/>[query_rewriter.py]"]
  node_reranker["Cross-encoder reranking<br/>[reranker.py]"]
  node_semantic[("Semantic cache<br/>[semantic_cache.py]")]
end

subgraph group_answer["Answer and verification"]
  node_pipeline["RAG orchestrator<br/>[pipeline.py]"]
  node_generator["Streaming generation<br/>[generate.py]"]
  node_verifier["Answer verifier<br/>[verifier.py]"]
end

subgraph group_interface["User interface"]
  node_app["Streamlit interface<br/>[app.py]"]
  node_feedback["Feedback log<br/>[app.py]"]
end

node_user(("Document user"))
node_llm{{"LLM service"}}
node_diskcache[("Disk cache")]

node_user -->|"uploads and asks"| node_app
node_app -->|"submits questions"| node_pipeline
node_app -->|"logs feedback"| node_feedback
node_pipeline -->|"builds document index"| node_chunks
node_chunks -->|"loads PDF content"| node_pdf
node_chunks -->|"embeds semantic windows"| node_embedding
node_chunks -->|"contextualizes chunks"| node_context
node_chunks -->|"stores indexed chunks"| node_store
node_store -->|"builds from chunks"| node_chunks
node_store -->|"embeds stored text"| node_embedding
node_pipeline -->|"resolves query"| node_rewriter
node_rewriter -->|"requests query expansion"| node_llm
node_rewriter -->|"reads and writes"| node_diskcache
node_pipeline -->|"checks semantic cache"| node_semantic
node_pipeline -->|"retrieves candidates"| node_retriever
node_retriever -->|"searches vectors"| node_store
node_pipeline -->|"reranks candidates"| node_reranker
node_pipeline -->|"streams answer"| node_generator
node_generator -->|"requests completion"| node_llm
node_generator -->|"reads and writes"| node_diskcache
node_pipeline -->|"verifies answer"| node_verifier
node_embedding -->|"loads model path"| node_settings

click node_app "https://github.com/sinapars9/doclens/blob/main/app.py"
click node_feedback "https://github.com/sinapars9/doclens/blob/main/app.py"
click node_pipeline "https://github.com/sinapars9/doclens/blob/main/pipeline.py"
click node_pdf "https://github.com/sinapars9/doclens/blob/main/inspect_pdf.py"
click node_chunks "https://github.com/sinapars9/doclens/blob/main/chunk_pdf.py"
click node_embedding "https://github.com/sinapars9/doclens/blob/main/embedding.py"
click node_context "https://github.com/sinapars9/doclens/blob/main/contextualizer.py"
click node_store "https://github.com/sinapars9/doclens/blob/main/vector_store.py"
click node_retriever "https://github.com/sinapars9/doclens/blob/main/retriever.py"
click node_rewriter "https://github.com/sinapars9/doclens/blob/main/query_rewriter.py"
click node_reranker "https://github.com/sinapars9/doclens/blob/main/reranker.py"
click node_semantic "https://github.com/sinapars9/doclens/blob/main/semantic_cache.py"
click node_generator "https://github.com/sinapars9/doclens/blob/main/generate.py"
click node_verifier "https://github.com/sinapars9/doclens/blob/main/verifier.py"
click node_settings "https://github.com/sinapars9/doclens/blob/main/config.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_pdf,node_chunks,node_embedding,node_context,node_settings,node_user toneBlue
class node_store,node_retriever,node_rewriter,node_reranker,node_semantic,node_diskcache toneAmber
class node_pipeline,node_generator,node_verifier toneMint
class node_app,node_feedback toneRose
class node_llm toneIndigo
```

## Components

### PDF ingestion

- [PDF extraction](https://github.com/sinapars9/doclens/blob/main/inspect_pdf.py): `inspect_pdf.py`
- [Semantic chunks](https://github.com/sinapars9/doclens/blob/main/chunk_pdf.py): `chunk_pdf.py`
- [ONNX embeddings](https://github.com/sinapars9/doclens/blob/main/embedding.py): `embedding.py`
- [Chunk context](https://github.com/sinapars9/doclens/blob/main/contextualizer.py): `contextualizer.py`
- [Model settings](https://github.com/sinapars9/doclens/blob/main/config.py): `config.py`

### Search and context

- [Vector store](https://github.com/sinapars9/doclens/blob/main/vector_store.py): `vector_store.py`
- [Hybrid retrieval](https://github.com/sinapars9/doclens/blob/main/retriever.py): `retriever.py`
- [Query resolution](https://github.com/sinapars9/doclens/blob/main/query_rewriter.py): `query_rewriter.py`
- [Cross-encoder reranking](https://github.com/sinapars9/doclens/blob/main/reranker.py): `reranker.py`
- [Semantic cache](https://github.com/sinapars9/doclens/blob/main/semantic_cache.py): `semantic_cache.py`

### Answer and verification

- [RAG orchestrator](https://github.com/sinapars9/doclens/blob/main/pipeline.py): `pipeline.py`
- [Streaming generation](https://github.com/sinapars9/doclens/blob/main/generate.py): `generate.py`
- [Answer verifier](https://github.com/sinapars9/doclens/blob/main/verifier.py): `verifier.py`

### User interface

- [Streamlit interface](https://github.com/sinapars9/doclens/blob/main/app.py): `app.py`
- [Feedback log](https://github.com/sinapars9/doclens/blob/main/app.py): `app.py`

### Other components

- **Document user**
- **LLM service**
- **Disk cache**

## Connections

- Document user → Streamlit interface: uploads and asks (evidence: `README.md`)
- Streamlit interface → RAG orchestrator: submits questions (evidence: `README.md`)
- Streamlit interface → Feedback log: logs feedback (evidence: `app.py`)
- RAG orchestrator → Semantic chunks: builds document index (evidence: `README.md`)
- Semantic chunks → PDF extraction: loads PDF content (evidence: `chunk_pdf.py`)
- Semantic chunks → ONNX embeddings: embeds semantic windows (evidence: `chunk_pdf.py`)
- Semantic chunks → Chunk context: contextualizes chunks (evidence: `chunk_pdf.py`)
- Semantic chunks → Vector store: stores indexed chunks (evidence: `README.md`)
- Vector store → Semantic chunks: builds from chunks (evidence: `vector_store.py`)
- Vector store → ONNX embeddings: embeds stored text (evidence: `vector_store.py`)
- RAG orchestrator → Query resolution: resolves query (evidence: `pipeline.py`)
- Query resolution → LLM service: requests query expansion (evidence: `query_rewriter.py`)
- Query resolution → Disk cache: reads and writes (evidence: `query_rewriter.py`)
- RAG orchestrator → Semantic cache: checks semantic cache (evidence: `pipeline.py`)
- RAG orchestrator → Hybrid retrieval: retrieves candidates (evidence: `README.md`)
- Hybrid retrieval → Vector store: searches vectors (evidence: `retriever.py`)
- RAG orchestrator → Cross-encoder reranking: reranks candidates (evidence: `pipeline.py`)
- RAG orchestrator → Streaming generation: streams answer (evidence: `README.md`)
- Streaming generation → LLM service: requests completion (evidence: `generate.py`)
- Streaming generation → Disk cache: reads and writes (evidence: `generate.py`)
- RAG orchestrator → Answer verifier: verifies answer (evidence: `README.md`)
- ONNX embeddings → Model settings: loads model path (evidence: `embedding.py`)