# olehdatsyk/pdf-chat architecture

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

- Interactive diagram: https://gitdiagram.com/olehdatsyk/pdf-chat
- Repository: https://github.com/olehdatsyk/pdf-chat

## Overview

PDF Chat lets users upload PDFs, ask grounded questions with page citations, manage conversations and documents, and request structured summaries. Upload handlers validate and save files, extract and chunk text, then add chunks to persistent FAISS storage. Chat handlers manage SQLite-backed history and invoke retrieval-augmented generation, whose responses include cited sources and can stream. The graph separates API orchestration, ingestion, retrieval/generation, persistence, and browser interface. Relationships are limited to README statements and the shown source/index references; unsampled implementations are represented only where the tree and documentation support them.

Main entry points: [`main.py`](https://github.com/olehdatsyk/pdf-chat/blob/main/main.py) (FastAPI app), [`routers/upload.py`](https://github.com/olehdatsyk/pdf-chat/blob/main/routers/upload.py) (Upload API), [`routers/chat.py`](https://github.com/olehdatsyk/pdf-chat/blob/main/routers/chat.py) (Chat API), [`services/rag_service.py`](https://github.com/olehdatsyk/pdf-chat/blob/main/services/rag_service.py) (RAG answers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and orchestration"]
  node_app["FastAPI app<br/>[main.py]"]
  node_upload_api["Upload API<br/>[upload.py]"]
  node_documents_api["Documents API<br/>[documents.py]"]
  node_chat_api["Chat API<br/>[chat.py]"]
  node_health_api["Health API<br/>[health.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
  node_settings["Application settings<br/>[config.py]"]
end

subgraph group_ingest["PDF ingestion"]
  node_pdf_loader["PDF extraction<br/>[pdf_loader.py]"]
  node_chunking["Text chunking"]
end

subgraph group_rag["Retrieval and generation"]
  node_embeddings["Embedding client"]
  node_retriever["Chunk retrieval<br/>[retriever.py]"]
  node_rag_service["RAG answers<br/>[rag_service.py]"]
  node_prompts["Prompt templates"]
end

subgraph group_state["Persistent state"]
  node_conversation_memory["Conversation memory"]
  node_sqlite[("SQLite database<br/>[database.py]")]
  node_models["Stored records<br/>[models.py]"]
  node_vector_store[("FAISS vector store<br/>[vector_store.py]")]
end

subgraph group_web["Browser interface"]
  node_web_ui["Web interface"]
  node_browser_js["Browser interactions<br/>[chat.js]"]
end

node_user(("PDF user"))
node_openai["OpenAI API"]

node_user -->|"uses"| node_app
node_app -->|"registers"| node_upload_api
node_app -->|"registers"| node_documents_api
node_app -->|"registers"| node_chat_api
node_app -->|"registers"| node_health_api
node_app -->|"renders"| node_web_ui
node_app -->|"configures"| node_settings
node_upload_api -->|"extracts text"| node_pdf_loader
node_upload_api -->|"chunks text"| node_chunking
node_upload_api -->|"adds chunks"| node_vector_store
node_upload_api -->|"records document"| node_models
node_documents_api -->|"deletes chunks"| node_vector_store
node_documents_api -->|"requests summary"| node_rag_service
node_chat_api -->|"loads and saves"| node_conversation_memory
node_chat_api -->|"requests answer"| node_rag_service
node_chat_api -->|"reads conversations"| node_models
node_chat_api -->|"validates payloads"| node_schemas
node_conversation_memory -->|"uses records"| node_models
node_models -->|"declares tables"| node_sqlite
node_rag_service -->|"retrieves context"| node_retriever
node_rag_service -->|"builds prompts"| node_prompts
node_retriever -->|"searches chunks"| node_vector_store
node_vector_store -->|"embeds chunks"| node_embeddings
node_embeddings -->|"creates vectors"| node_openai
node_rag_service -->|"generates answers"| node_openai
node_user -->|"asks questions"| node_browser_js
node_browser_js -.->|"calls API"| node_app

click node_app "https://github.com/olehdatsyk/pdf-chat/blob/main/main.py"
click node_upload_api "https://github.com/olehdatsyk/pdf-chat/blob/main/routers/upload.py"
click node_documents_api "https://github.com/olehdatsyk/pdf-chat/blob/main/routers/documents.py"
click node_chat_api "https://github.com/olehdatsyk/pdf-chat/blob/main/routers/chat.py"
click node_health_api "https://github.com/olehdatsyk/pdf-chat/blob/main/routers/health.py"
click node_schemas "https://github.com/olehdatsyk/pdf-chat/blob/main/schemas.py"
click node_settings "https://github.com/olehdatsyk/pdf-chat/blob/main/config.py"
click node_pdf_loader "https://github.com/olehdatsyk/pdf-chat/blob/main/services/pdf_loader.py"
click node_chunking "https://github.com/olehdatsyk/pdf-chat/blob/main/services/chunking_service.py"
click node_conversation_memory "https://github.com/olehdatsyk/pdf-chat/blob/main/services/conversation_memory.py"
click node_sqlite "https://github.com/olehdatsyk/pdf-chat/blob/main/database.py"
click node_models "https://github.com/olehdatsyk/pdf-chat/blob/main/models.py"
click node_vector_store "https://github.com/olehdatsyk/pdf-chat/blob/main/services/vector_store.py"
click node_embeddings "https://github.com/olehdatsyk/pdf-chat/blob/main/services/embedding_service.py"
click node_retriever "https://github.com/olehdatsyk/pdf-chat/blob/main/services/retriever.py"
click node_rag_service "https://github.com/olehdatsyk/pdf-chat/blob/main/services/rag_service.py"
click node_prompts "https://github.com/olehdatsyk/pdf-chat/blob/main/services/prompt_templates.py"
click node_web_ui "https://github.com/olehdatsyk/pdf-chat/tree/main/templates"
click node_browser_js "https://github.com/olehdatsyk/pdf-chat/blob/main/static/js/chat.js"

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_app,node_upload_api,node_documents_api,node_chat_api,node_health_api,node_schemas,node_settings,node_user toneBlue
class node_pdf_loader,node_chunking toneAmber
class node_embeddings,node_retriever,node_rag_service,node_prompts,node_openai toneMint
class node_conversation_memory,node_sqlite,node_models,node_vector_store toneRose
class node_web_ui,node_browser_js toneIndigo
```

## Components

### API and orchestration

- [FastAPI app](https://github.com/olehdatsyk/pdf-chat/blob/main/main.py): `main.py`
- [Upload API](https://github.com/olehdatsyk/pdf-chat/blob/main/routers/upload.py): `routers/upload.py`
- [Documents API](https://github.com/olehdatsyk/pdf-chat/blob/main/routers/documents.py): `routers/documents.py`
- [Chat API](https://github.com/olehdatsyk/pdf-chat/blob/main/routers/chat.py): `routers/chat.py`
- [Health API](https://github.com/olehdatsyk/pdf-chat/blob/main/routers/health.py): `routers/health.py`
- [API schemas](https://github.com/olehdatsyk/pdf-chat/blob/main/schemas.py): `schemas.py`
- [Application settings](https://github.com/olehdatsyk/pdf-chat/blob/main/config.py): `config.py`

### PDF ingestion

- [PDF extraction](https://github.com/olehdatsyk/pdf-chat/blob/main/services/pdf_loader.py): `services/pdf_loader.py`
- [Text chunking](https://github.com/olehdatsyk/pdf-chat/blob/main/services/chunking_service.py): `services/chunking_service.py`

### Retrieval and generation

- [Embedding client](https://github.com/olehdatsyk/pdf-chat/blob/main/services/embedding_service.py): `services/embedding_service.py`
- [Chunk retrieval](https://github.com/olehdatsyk/pdf-chat/blob/main/services/retriever.py): `services/retriever.py`
- [RAG answers](https://github.com/olehdatsyk/pdf-chat/blob/main/services/rag_service.py): `services/rag_service.py`
- [Prompt templates](https://github.com/olehdatsyk/pdf-chat/blob/main/services/prompt_templates.py): `services/prompt_templates.py`

### Persistent state

- [Conversation memory](https://github.com/olehdatsyk/pdf-chat/blob/main/services/conversation_memory.py): `services/conversation_memory.py`
- [SQLite database](https://github.com/olehdatsyk/pdf-chat/blob/main/database.py): `database.py`
- [Stored records](https://github.com/olehdatsyk/pdf-chat/blob/main/models.py): `models.py`
- [FAISS vector store](https://github.com/olehdatsyk/pdf-chat/blob/main/services/vector_store.py): `services/vector_store.py`

### Browser interface

- [Web interface](https://github.com/olehdatsyk/pdf-chat/tree/main/templates): `templates`
- [Browser interactions](https://github.com/olehdatsyk/pdf-chat/blob/main/static/js/chat.js): `static/js/chat.js`

### Other components

- **PDF user**
- **OpenAI API**

## Connections

- PDF user → FastAPI app: uses (evidence: `README.md`)
- FastAPI app → Upload API: registers (evidence: `main.py`)
- FastAPI app → Documents API: registers (evidence: `main.py`)
- FastAPI app → Chat API: registers (evidence: `main.py`)
- FastAPI app → Health API: registers (evidence: `main.py`)
- FastAPI app → Web interface: renders (evidence: `main.py`)
- FastAPI app → Application settings: configures (evidence: `main.py`)
- Upload API → PDF extraction: extracts text (evidence: `routers/upload.py`)
- Upload API → Text chunking: chunks text (evidence: `routers/upload.py`)
- Upload API → FAISS vector store: adds chunks (evidence: `routers/upload.py`)
- Upload API → Stored records: records document (evidence: `routers/upload.py`)
- Documents API → FAISS vector store: deletes chunks (evidence: `routers/documents.py`)
- Documents API → RAG answers: requests summary (evidence: `routers/documents.py`)
- Chat API → Conversation memory: loads and saves (evidence: `routers/chat.py`)
- Chat API → RAG answers: requests answer (evidence: `routers/chat.py`)
- Chat API → Stored records: reads conversations (evidence: `routers/chat.py`)
- Chat API → API schemas: validates payloads (evidence: `routers/chat.py`)
- Conversation memory → Stored records: uses records (evidence: `services/conversation_memory.py`)
- Stored records → SQLite database: declares tables (evidence: `models.py`)
- RAG answers → Chunk retrieval: retrieves context (evidence: `services/rag_service.py`)
- RAG answers → Prompt templates: builds prompts (evidence: `services/rag_service.py`)
- Chunk retrieval → FAISS vector store: searches chunks (evidence: `services/retriever.py`)
- FAISS vector store → Embedding client: embeds chunks (evidence: `services/vector_store.py`)
- Embedding client → OpenAI API: creates vectors (evidence: `README.md`)
- RAG answers → OpenAI API: generates answers (evidence: `README.md`)
- PDF user → Browser interactions: asks questions (evidence: `README.md`)
- Browser interactions → FastAPI app: calls API
