# samirchahar/search_engine architecture

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

- Interactive diagram: https://gitdiagram.com/samirchahar/search_engine
- Repository: https://github.com/samirchahar/search_engine

## Overview

Argus is an offline document-search application: users add local files, which are validated and extracted into page/chunk text, indexed for keyword and semantic retrieval, then searched and optionally summarized by a local Ollama model. The CLI and desktop UI are separate entry points; both expose search results, while the CLI also reports session metrics. README and sampled code support the main stages and integrations; some UI indexing/search internals were omitted, so those links reflect documented behavior rather than inspected implementation details.

Main entry points: [`main.py`](https://github.com/samirchahar/search_engine/blob/main/main.py) (CLI workflow), [`src/ui/app.py`](https://github.com/samirchahar/search_engine/blob/main/src/ui/app.py) (Desktop search UI), [`src/search/search_engine.py`](https://github.com/samirchahar/search_engine/blob/main/src/search/search_engine.py) (Search orchestration), [`src/extractor/extractor.py`](https://github.com/samirchahar/search_engine/blob/main/src/extractor/extractor.py) (Text extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI workflow<br/>[main.py]"]
  node_desktop["Desktop search UI<br/>[app.py]"]
  node_results["Ranked results and answer"]
end

subgraph group_ingest["Document ingestion"]
  node_extractor["Text extraction<br/>[extractor.py]"]
  node_validator["Path and type validation<br/>[file_validator.py]"]
end

subgraph group_retrieval["Search and ranking"]
  node_engine["Search orchestration<br/>[search_engine.py]"]
  node_cppindex["Positional keyword index<br/>[indexer.cpp]"]
  node_stopwords["Stopword filtering<br/>[stopwords.py]"]
  node_vectors["Semantic retrieval<br/>[vector_search.py]"]
  node_chroma[("Persistent vector store<br/>[vector_search.py]")]
  node_metrics["Session metrics<br/>[metrics.py]"]
end

subgraph group_answer["Answer and local services"]
  node_answergen["Grounded answer generation<br/>[llm_answer.py]"]
end

node_user(("User"))
node_files["Local documents"]
node_ocr["Tesseract OCR"]
node_embeddings["Sentence transformer"]
node_ollama["Local Ollama model"]

node_user -->|"runs queries"| node_cli
node_user -->|"uses"| node_desktop
node_cli -->|"selects folder"| node_files
node_desktop -->|"selects files"| node_files
node_cli -->|"extracts documents"| node_extractor
node_desktop -->|"extracts documents"| node_extractor
node_extractor -->|"validates paths"| node_validator
node_extractor -.->|"recognizes scanned pages"| node_ocr
node_cli -->|"indexes and searches"| node_engine
node_desktop -->|"indexes and searches"| node_engine
node_cli -->|"records timings"| node_metrics
node_desktop -->|"records timings"| node_metrics
node_engine -->|"filters query terms"| node_stopwords
node_engine -->|"sends index and queries"| node_cppindex
node_engine -->|"indexes and searches"| node_vectors
node_vectors -->|"encodes text"| node_embeddings
node_vectors -->|"stores and queries vectors"| node_chroma
node_engine -->|"provides results"| node_answergen
node_cli -->|"requests answer"| node_answergen
node_desktop -->|"requests optional summary"| node_answergen
node_answergen -->|"sends prompt"| node_ollama
node_cli -->|"prints"| node_results
node_desktop -->|"displays"| node_results

click node_cli "https://github.com/samirchahar/search_engine/blob/main/main.py"
click node_desktop "https://github.com/samirchahar/search_engine/blob/main/src/ui/app.py"
click node_extractor "https://github.com/samirchahar/search_engine/blob/main/src/extractor/extractor.py"
click node_validator "https://github.com/samirchahar/search_engine/blob/main/src/extractor/file_validator.py"
click node_engine "https://github.com/samirchahar/search_engine/blob/main/src/search/search_engine.py"
click node_cppindex "https://github.com/samirchahar/search_engine/blob/main/src/indexer/indexer.cpp"
click node_stopwords "https://github.com/samirchahar/search_engine/blob/main/src/search/stopwords.py"
click node_vectors "https://github.com/samirchahar/search_engine/blob/main/src/search/vector_search.py"
click node_chroma "https://github.com/samirchahar/search_engine/blob/main/src/search/vector_search.py"
click node_metrics "https://github.com/samirchahar/search_engine/blob/main/src/search/metrics.py"
click node_answergen "https://github.com/samirchahar/search_engine/blob/main/src/search/llm_answer.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_cli,node_desktop,node_results,node_user toneBlue
class node_extractor,node_validator toneAmber
class node_engine,node_cppindex,node_stopwords,node_vectors,node_chroma,node_metrics toneMint
class node_answergen toneRose
class node_files,node_ocr,node_embeddings,node_ollama toneIndigo
```

## Components

### User interfaces

- [CLI workflow](https://github.com/samirchahar/search_engine/blob/main/main.py): `main.py`
- [Desktop search UI](https://github.com/samirchahar/search_engine/blob/main/src/ui/app.py): `src/ui/app.py`
- **Ranked results and answer**

### Document ingestion

- [Text extraction](https://github.com/samirchahar/search_engine/blob/main/src/extractor/extractor.py): `src/extractor/extractor.py`
- [Path and type validation](https://github.com/samirchahar/search_engine/blob/main/src/extractor/file_validator.py): `src/extractor/file_validator.py`

### Search and ranking

- [Search orchestration](https://github.com/samirchahar/search_engine/blob/main/src/search/search_engine.py): `src/search/search_engine.py`
- [Positional keyword index](https://github.com/samirchahar/search_engine/blob/main/src/indexer/indexer.cpp): `src/indexer/indexer.cpp`
- [Stopword filtering](https://github.com/samirchahar/search_engine/blob/main/src/search/stopwords.py): `src/search/stopwords.py`
- [Semantic retrieval](https://github.com/samirchahar/search_engine/blob/main/src/search/vector_search.py): `src/search/vector_search.py`
- [Persistent vector store](https://github.com/samirchahar/search_engine/blob/main/src/search/vector_search.py): `src/search/vector_search.py`
- [Session metrics](https://github.com/samirchahar/search_engine/blob/main/src/search/metrics.py): `src/search/metrics.py`

### Answer and local services

- [Grounded answer generation](https://github.com/samirchahar/search_engine/blob/main/src/search/llm_answer.py): `src/search/llm_answer.py`

### Other components

- **User**
- **Local documents**
- **Tesseract OCR**
- **Sentence transformer**
- **Local Ollama model**

## Connections

- User → CLI workflow: runs queries
- User → Desktop search UI: uses
- CLI workflow → Local documents: selects folder
- Desktop search UI → Local documents: selects files
- CLI workflow → Text extraction: extracts documents
- Desktop search UI → Text extraction: extracts documents
- Text extraction → Path and type validation: validates paths
- Text extraction → Tesseract OCR: recognizes scanned pages
- CLI workflow → Search orchestration: indexes and searches
- Desktop search UI → Search orchestration: indexes and searches
- CLI workflow → Session metrics: records timings
- Desktop search UI → Session metrics: records timings
- Search orchestration → Stopword filtering: filters query terms
- Search orchestration → Positional keyword index: sends index and queries
- Search orchestration → Semantic retrieval: indexes and searches
- Semantic retrieval → Sentence transformer: encodes text
- Semantic retrieval → Persistent vector store: stores and queries vectors
- Search orchestration → Grounded answer generation: provides results
- CLI workflow → Grounded answer generation: requests answer
- Desktop search UI → Grounded answer generation: requests optional summary
- Grounded answer generation → Local Ollama model: sends prompt
- CLI workflow → Ranked results and answer: prints
- Desktop search UI → Ranked results and answer: displays