# aakriti0805/chatbot-backend architecture

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

- Interactive diagram: https://gitdiagram.com/aakriti0805/chatbot-backend
- Repository: https://github.com/aakriti0805/chatbot-backend

## Overview

This is a railway-maintenance chatbot API with two main workflows: ingest documents and master data for search, and answer questions using document retrieval, master-data SQL, or both. Uploaded and CRIS-sourced files are processed into searchable chunks; master-data synchronization maintains a separate chunk collection. Queries can use conversation history and return source citations. The sampled code confirms the query, retrieval, and CRIS-ingestion paths; some implementation details for chunking, master-data sync, and other routes are inferred only from the tree and route documentation.

Main entry points: [`app/services/query_services.py`](https://github.com/aakriti0805/chatbot-backend/blob/main/app/services/query_services.py) (Query orchestration), [`app/services/document_services.py`](https://github.com/aakriti0805/chatbot-backend/blob/main/app/services/document_services.py) (Document processing), [`app/ingest_cris_pdfs.py`](https://github.com/aakriti0805/chatbot-backend/blob/main/app/ingest_cris_pdfs.py) (CRIS ingestion), [`app/routers/document_routes.py`](https://github.com/aakriti0805/chatbot-backend/blob/main/app/routers/document_routes.py) (Document routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API routes"]
  node_main["FastAPI app<br/>[main.py]"]
  node_doc_routes["Document routes<br/>[document_routes.py]"]
  node_ocr_routes["OCR route<br/>[ocr_routes.py]"]
  node_query_routes["Query routes<br/>[query_routes.py]"]
  node_master_routes["Master-data route"]
end

subgraph group_documents["Document ingestion"]
  node_doc_service["Document processing"]
  node_text_extract["Text extraction"]
  node_chunking["Chunking"]
  node_cris_ingest["CRIS ingestion"]
end

subgraph group_query["Question answering"]
  node_query_service["Query orchestration<br/>[query_services.py]"]
  node_retrieval["Hybrid retrieval"]
  node_sql_query["Text-to-SQL"]
  node_llm["Language model<br/>[llm_service.py]"]
end

subgraph group_data["Data and indexing"]
  node_master_sync["Master-data sync"]
  node_embedding["Embedding model"]
  node_models["Data models<br/>[models.py]"]
  node_database[("Chatbot database<br/>[database.py]")]
end

node_user(("Questioner"))
node_admin(("Administrator"))
node_cris_db[("CRIS source database")]
node_source_db[("Railway master database")]
node_gemini{{"Gemini API"}}
node_files{{"CRIS file hosting"}}

node_user -->|"asks"| node_query_routes
node_admin -->|"uploads or syncs"| node_doc_routes
node_user -->|"requests OCR"| node_ocr_routes
node_main -->|"mounts"| node_doc_routes
node_main -->|"mounts"| node_query_routes
node_main -->|"mounts"| node_ocr_routes
node_main -->|"mounts"| node_master_routes
node_doc_routes -->|"processes upload"| node_doc_service
node_doc_routes -->|"starts ingestion"| node_cris_ingest
node_doc_routes -->|"reads and writes"| node_database
node_cris_ingest -->|"fetches file links"| node_cris_db
node_cris_ingest -->|"downloads files"| node_files
node_cris_ingest -->|"extracts pages"| node_text_extract
node_cris_ingest -->|"processes pages"| node_doc_service
node_ocr_routes -->|"extracts text"| node_text_extract
node_doc_service -->|"extracts text"| node_text_extract
node_doc_service -->|"forms chunks"| node_chunking
node_doc_service -->|"embeds content"| node_embedding
node_doc_service -->|"stores documents and chunks"| node_database
node_master_routes -->|"starts sync"| node_master_sync
node_master_sync -->|"reads master rows"| node_source_db
node_master_sync -->|"embeds rows"| node_embedding
node_master_sync -->|"upserts chunks"| node_database
node_query_routes -->|"answers query"| node_query_service
node_query_service -->|"loads and saves history"| node_database
node_query_service -->|"rewrites and expands"| node_llm
node_query_service -->|"tries master-data SQL"| node_sql_query
node_query_service -->|"searches chunks"| node_retrieval
node_query_service -->|"generates answer"| node_llm
node_retrieval -->|"embeds query"| node_embedding
node_retrieval -->|"searches chunk vectors and keywords"| node_database
node_sql_query -->|"plans and summarizes SQL"| node_llm
node_sql_query -->|"executes SQL"| node_source_db

click node_main "https://github.com/aakriti0805/chatbot-backend/blob/main/app/main.py"
click node_doc_routes "https://github.com/aakriti0805/chatbot-backend/blob/main/app/routers/document_routes.py"
click node_ocr_routes "https://github.com/aakriti0805/chatbot-backend/blob/main/app/routers/ocr_routes.py"
click node_query_routes "https://github.com/aakriti0805/chatbot-backend/blob/main/app/routers/query_routes.py"
click node_master_routes "https://github.com/aakriti0805/chatbot-backend/blob/main/app/routers/master_data_routes.py"
click node_doc_service "https://github.com/aakriti0805/chatbot-backend/blob/main/app/services/document_services.py"
click node_text_extract "https://github.com/aakriti0805/chatbot-backend/blob/main/app/services/textextraction_service.py"
click node_chunking "https://github.com/aakriti0805/chatbot-backend/blob/main/app/services/chunking_services.py"
click node_cris_ingest "https://github.com/aakriti0805/chatbot-backend/blob/main/app/ingest_cris_pdfs.py"
click node_master_sync "https://github.com/aakriti0805/chatbot-backend/blob/main/app/sync_master_data.py"
click node_query_service "https://github.com/aakriti0805/chatbot-backend/blob/main/app/services/query_services.py"
click node_retrieval "https://github.com/aakriti0805/chatbot-backend/blob/main/app/services/retrieval_services.py"
click node_sql_query "https://github.com/aakriti0805/chatbot-backend/blob/main/app/services/sql_query_services.py"
click node_llm "https://github.com/aakriti0805/chatbot-backend/blob/main/app/services/llm_service.py"
click node_embedding "https://github.com/aakriti0805/chatbot-backend/blob/main/app/services/embedding_service.py"
click node_models "https://github.com/aakriti0805/chatbot-backend/blob/main/app/models.py"
click node_database "https://github.com/aakriti0805/chatbot-backend/blob/main/app/database.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_main,node_doc_routes,node_ocr_routes,node_query_routes,node_master_routes toneBlue
class node_doc_service,node_text_extract,node_chunking,node_cris_ingest,node_cris_db,node_source_db toneAmber
class node_query_service,node_retrieval,node_sql_query,node_llm,node_gemini toneMint
class node_master_sync,node_embedding,node_models,node_database toneRose
class node_user,node_admin,node_files toneIndigo
```

## Components

### API routes

- [FastAPI app](https://github.com/aakriti0805/chatbot-backend/blob/main/app/main.py): `app/main.py`
- [Document routes](https://github.com/aakriti0805/chatbot-backend/blob/main/app/routers/document_routes.py): `app/routers/document_routes.py`
- [OCR route](https://github.com/aakriti0805/chatbot-backend/blob/main/app/routers/ocr_routes.py): `app/routers/ocr_routes.py`
- [Query routes](https://github.com/aakriti0805/chatbot-backend/blob/main/app/routers/query_routes.py): `app/routers/query_routes.py`
- [Master-data route](https://github.com/aakriti0805/chatbot-backend/blob/main/app/routers/master_data_routes.py): `app/routers/master_data_routes.py`

### Document ingestion

- [Document processing](https://github.com/aakriti0805/chatbot-backend/blob/main/app/services/document_services.py): `app/services/document_services.py`
- [Text extraction](https://github.com/aakriti0805/chatbot-backend/blob/main/app/services/textextraction_service.py): `app/services/textextraction_service.py`
- [Chunking](https://github.com/aakriti0805/chatbot-backend/blob/main/app/services/chunking_services.py): `app/services/chunking_services.py`
- [CRIS ingestion](https://github.com/aakriti0805/chatbot-backend/blob/main/app/ingest_cris_pdfs.py): `app/ingest_cris_pdfs.py`

### Question answering

- [Query orchestration](https://github.com/aakriti0805/chatbot-backend/blob/main/app/services/query_services.py): `app/services/query_services.py`
- [Hybrid retrieval](https://github.com/aakriti0805/chatbot-backend/blob/main/app/services/retrieval_services.py): `app/services/retrieval_services.py`
- [Text-to-SQL](https://github.com/aakriti0805/chatbot-backend/blob/main/app/services/sql_query_services.py): `app/services/sql_query_services.py`
- [Language model](https://github.com/aakriti0805/chatbot-backend/blob/main/app/services/llm_service.py): `app/services/llm_service.py`

### Data and indexing

- [Master-data sync](https://github.com/aakriti0805/chatbot-backend/blob/main/app/sync_master_data.py): `app/sync_master_data.py`
- [Embedding model](https://github.com/aakriti0805/chatbot-backend/blob/main/app/services/embedding_service.py): `app/services/embedding_service.py`
- [Data models](https://github.com/aakriti0805/chatbot-backend/blob/main/app/models.py): `app/models.py`
- [Chatbot database](https://github.com/aakriti0805/chatbot-backend/blob/main/app/database.py): `app/database.py`

### Other components

- **Questioner**
- **Administrator**
- **CRIS source database**
- **Railway master database**
- **Gemini API**
- **CRIS file hosting**

## Connections

- Questioner → Query routes: asks
- Administrator → Document routes: uploads or syncs
- Questioner → OCR route: requests OCR
- FastAPI app → Document routes: mounts
- FastAPI app → Query routes: mounts
- FastAPI app → OCR route: mounts
- FastAPI app → Master-data route: mounts
- Document routes → Document processing: processes upload
- Document routes → CRIS ingestion: starts ingestion
- Document routes → Chatbot database: reads and writes
- CRIS ingestion → CRIS source database: fetches file links
- CRIS ingestion → CRIS file hosting: downloads files
- CRIS ingestion → Text extraction: extracts pages
- CRIS ingestion → Document processing: processes pages
- OCR route → Text extraction: extracts text
- Document processing → Text extraction: extracts text
- Document processing → Chunking: forms chunks
- Document processing → Embedding model: embeds content
- Document processing → Chatbot database: stores documents and chunks
- Master-data route → Master-data sync: starts sync
- Master-data sync → Railway master database: reads master rows
- Master-data sync → Embedding model: embeds rows
- Master-data sync → Chatbot database: upserts chunks
- Query routes → Query orchestration: answers query
- Query orchestration → Chatbot database: loads and saves history
- Query orchestration → Language model: rewrites and expands
- Query orchestration → Text-to-SQL: tries master-data SQL
- Query orchestration → Hybrid retrieval: searches chunks
- Query orchestration → Language model: generates answer
- Hybrid retrieval → Embedding model: embeds query
- Hybrid retrieval → Chatbot database: searches chunk vectors and keywords
- Text-to-SQL → Language model: plans and summarizes SQL
- Text-to-SQL → Railway master database: executes SQL