# temurjonm/ai-search-rag architecture

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

- Interactive diagram: https://gitdiagram.com/temurjonm/ai-search-rag
- Repository: https://github.com/temurjonm/ai-search-rag

## Overview

This is a FastAPI RAG search service: users upload tenant-scoped PDFs or text files, then ask questions and receive source-cited answers. Upload processing extracts text (with OCR fallback), chunks and embeds it, and persists document/chunk records; search embeds the question, fuses vector and keyword candidates, and generates an answer from retrieved sources. The README also documents a browser UI with SSE progress and defensive upload handling. Relationships below are based on the supplied excerpts and README; unsampled UI behavior is documented, not source-inspected.

Main entry points: [`src/ai_search/main.py`](https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/main.py) (HTTP routes), [`src/ai_search/ingestion.py`](https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/ingestion.py) (Upload processing), [`src/ai_search/retrieval.py`](https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/retrieval.py) (Hybrid retrieval), [`src/ai_search/db.py`](https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/db.py) (Database sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and UI"]
  node_browser["Web UI<br/>[index.html]"]
  node_api_routes["HTTP routes<br/>[main.py]"]
  node_api_schemas["API schemas<br/>[schemas.py]"]
end

subgraph group_ingest["Document ingestion"]
  node_ingestion["Upload processing<br/>[ingestion.py]"]
  node_loader["Text extraction OCR<br/>[document_loader.py]"]
  node_chunker["Text chunking<br/>[chunking.py]"]
  node_file_storage["Uploaded files"]
end

subgraph group_search["Retrieval and answers"]
  node_embedding["Embedding client<br/>[openai_client.py]"]
  node_retrieval["Hybrid retrieval<br/>[retrieval.py]"]
  node_answering["Answer generation<br/>[openai_client.py]"]
end

subgraph group_infra["Data and configuration"]
  node_db_session["Database sessions<br/>[db.py]"]
  node_models["Document and chunk models<br/>[models.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

node_user(("User"))
node_openai{{"OpenAI API"}}
node_postgres[("PostgreSQL pgvector")]

node_user -.->|"uses"| node_browser
node_browser -.->|"uploads and searches"| node_api_routes
node_user -.->|"calls API"| node_api_routes
node_api_routes -->|"dispatches uploads"| node_ingestion
node_api_routes -->|"embeds query"| node_embedding
node_api_routes -->|"runs search"| node_retrieval
node_api_routes -->|"generates answer"| node_answering
node_api_routes -->|"initializes database"| node_db_session
node_ingestion -->|"extracts text"| node_loader
node_ingestion -->|"chunks text"| node_chunker
node_ingestion -->|"embeds chunks"| node_embedding
node_ingestion -->|"writes uploads"| node_file_storage
node_ingestion -->|"creates records"| node_models
node_ingestion -->|"reads chunk settings"| node_settings
node_embedding -->|"requests embeddings"| node_openai
node_answering -->|"requests completion"| node_openai
node_retrieval -->|"queries records"| node_models
node_retrieval -->|"builds sources"| node_api_schemas
node_api_routes -->|"validates and returns"| node_api_schemas
node_db_session -->|"reads database URL"| node_settings
node_db_session -->|"creates schema"| node_models
node_db_session -->|"opens sessions"| node_postgres
node_models -.->|"maps tables"| node_postgres
node_retrieval -->|"runs ranked queries"| node_postgres

click node_browser "https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/static/index.html"
click node_api_routes "https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/main.py"
click node_api_schemas "https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/schemas.py"
click node_ingestion "https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/ingestion.py"
click node_loader "https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/document_loader.py"
click node_chunker "https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/chunking.py"
click node_file_storage "https://github.com/temurjonm/ai-search-rag/tree/main/storage"
click node_embedding "https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/openai_client.py"
click node_retrieval "https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/retrieval.py"
click node_answering "https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/openai_client.py"
click node_db_session "https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/db.py"
click node_models "https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/models.py"
click node_settings "https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/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_browser,node_api_routes,node_api_schemas,node_user toneBlue
class node_ingestion,node_loader,node_chunker,node_file_storage,node_postgres toneAmber
class node_embedding,node_retrieval,node_answering,node_openai toneMint
class node_db_session,node_models,node_settings toneRose
```

## Components

### API and UI

- [Web UI](https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/static/index.html): `src/ai_search/static/index.html`
- [HTTP routes](https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/main.py): `src/ai_search/main.py`
- [API schemas](https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/schemas.py): `src/ai_search/schemas.py`

### Document ingestion

- [Upload processing](https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/ingestion.py): `src/ai_search/ingestion.py`
- [Text extraction OCR](https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/document_loader.py): `src/ai_search/document_loader.py`
- [Text chunking](https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/chunking.py): `src/ai_search/chunking.py`
- [Uploaded files](https://github.com/temurjonm/ai-search-rag/tree/main/storage): `storage`

### Retrieval and answers

- [Embedding client](https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/openai_client.py): `src/ai_search/openai_client.py`
- [Hybrid retrieval](https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/retrieval.py): `src/ai_search/retrieval.py`
- [Answer generation](https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/openai_client.py): `src/ai_search/openai_client.py`

### Data and configuration

- [Database sessions](https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/db.py): `src/ai_search/db.py`
- [Document and chunk models](https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/models.py): `src/ai_search/models.py`
- [Runtime settings](https://github.com/temurjonm/ai-search-rag/blob/main/src/ai_search/config.py): `src/ai_search/config.py`

### Other components

- **User**
- **OpenAI API**
- **PostgreSQL pgvector**

## Connections

- User → Web UI: uses (evidence: `README.md`)
- Web UI → HTTP routes: uploads and searches (evidence: `README.md`)
- User → HTTP routes: calls API (evidence: `README.md`)
- HTTP routes → Upload processing: dispatches uploads (evidence: `src/ai_search/main.py`)
- HTTP routes → Embedding client: embeds query (evidence: `src/ai_search/main.py`)
- HTTP routes → Hybrid retrieval: runs search (evidence: `src/ai_search/main.py`)
- HTTP routes → Answer generation: generates answer (evidence: `src/ai_search/main.py`)
- HTTP routes → Database sessions: initializes database (evidence: `src/ai_search/main.py`)
- Upload processing → Text extraction OCR: extracts text (evidence: `src/ai_search/ingestion.py`)
- Upload processing → Text chunking: chunks text (evidence: `src/ai_search/ingestion.py`)
- Upload processing → Embedding client: embeds chunks (evidence: `src/ai_search/ingestion.py`)
- Upload processing → Uploaded files: writes uploads (evidence: `src/ai_search/ingestion.py`)
- Upload processing → Document and chunk models: creates records (evidence: `src/ai_search/ingestion.py`)
- Upload processing → Runtime settings: reads chunk settings (evidence: `src/ai_search/ingestion.py`)
- Embedding client → OpenAI API: requests embeddings (evidence: `src/ai_search/openai_client.py`)
- Answer generation → OpenAI API: requests completion (evidence: `src/ai_search/openai_client.py`)
- Hybrid retrieval → Document and chunk models: queries records (evidence: `src/ai_search/retrieval.py`)
- Hybrid retrieval → API schemas: builds sources (evidence: `src/ai_search/retrieval.py`)
- HTTP routes → API schemas: validates and returns (evidence: `src/ai_search/main.py`)
- Database sessions → Runtime settings: reads database URL (evidence: `src/ai_search/db.py`)
- Database sessions → Document and chunk models: creates schema (evidence: `src/ai_search/db.py`)
- Database sessions → PostgreSQL pgvector: opens sessions (evidence: `src/ai_search/db.py`)
- Document and chunk models → PostgreSQL pgvector: maps tables (evidence: `README.md`)
- Hybrid retrieval → PostgreSQL pgvector: runs ranked queries (evidence: `src/ai_search/retrieval.py`)