# dunh-real/tpv-chatbot-btl architecture

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

- Interactive diagram: https://gitdiagram.com/dunh-real/tpv-chatbot-btl
- Repository: https://github.com/dunh-real/tpv-chatbot-btl

## Overview

TPV Chatbot BTL is an internal enterprise AI server combining conversational RAG, structured-data queries, document ingestion, and document generation. The main workflow accepts a chat request, retrieves relevant vector and MSSQL context, reranks and prompts an LLM, and retains conversation history. Separate branches process uploaded PDFs into indexed chunks, generate department reports and template-based documents, and turn Markdown into PowerPoint. The graph follows shown imports/calls and README capability descriptions; some detailed implementations were not sampled, so uncertain links are omitted.

Main entry points: [`src/core/chat.py`](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/core/chat.py) (Chat session), [`src/api/presentation.py`](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/api/presentation.py) (Presentation endpoint), [`src/core/upload.py`](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/core/upload.py) (PDF processing), [`main.py`](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and orchestration"]
  node_app["FastAPI application<br/>[main.py]"]
  node_chat_api["Chat endpoint<br/>[chat.py]"]
  node_upload_api["Upload endpoint<br/>[upload.py]"]
  node_presentation_api["Presentation endpoint<br/>[presentation.py]"]
end

subgraph group_chat["Chat and retrieval"]
  node_chat_session["Chat session<br/>[chat.py]"]
  node_prompt["Prompt assembly<br/>[prompt_service.py]"]
  node_reranker["Context reranking<br/>[rerank_service.py]"]
  node_llm["Ollama LLM<br/>[llm_service.py]"]
  node_qdrant[("Vector retrieval<br/>[qdrant_service.py]")]
  node_mssql_retrieval["SQL retrieval"]
  node_text2sql["Text-to-SQL"]
  node_memory["Conversation memory<br/>[memory_service.py]"]
  node_report["Department reports<br/>[report_service.py]"]
end

subgraph group_ingestion["Document ingestion"]
  node_pdf_processor["PDF processing<br/>[upload.py]"]
  node_ocr["OCR extraction<br/>[ocr_service.py]"]
  node_chunking["Chunking"]
  node_embedding["Vector embedding"]
  node_storage["Object storage<br/>[storage_service.py]"]
end

subgraph group_generation["Document generation"]
  node_doc_api["Template document API"]
  node_doc_service["Template document creation"]
  node_ppt_planner["Slide planning<br/>[content_planner.py]"]
  node_markdown["Markdown parsing<br/>[markdown_parser.py]"]
  node_ppt_composer["Deck composition<br/>[composer.py]"]
  node_ppt_renderer_client["Renderer client<br/>[renderer_client.py]"]
  node_ppt_renderer["PowerPoint renderer"]
  node_templates["Document templates"]
end

node_backend(("Backend / user"))
node_mssql[("MSSQL database")]
node_ollama_service["Ollama service"]
node_redis[("Redis")]

node_backend -->|"calls API"| node_app
node_app -->|"registers route"| node_chat_api
node_app -->|"registers route"| node_upload_api
node_app -->|"registers route"| node_presentation_api
node_chat_api -->|"handles chat"| node_chat_session
node_chat_session -->|"reads and saves"| node_memory
node_chat_session -->|"retrieves context"| node_qdrant
node_chat_session -->|"retrieves context"| node_mssql_retrieval
node_chat_session -->|"reranks context"| node_reranker
node_chat_session -->|"builds prompt"| node_prompt
node_chat_session -->|"requests answer"| node_llm
node_chat_session -->|"generates report"| node_report
node_mssql_retrieval -->|"creates SQL"| node_text2sql
node_mssql_retrieval -.->|"queries"| node_mssql
node_llm -->|"invokes model"| node_ollama_service
node_qdrant -->|"embeds queries"| node_embedding
node_upload_api -->|"queues processing"| node_pdf_processor
node_pdf_processor -->|"extracts text"| node_ocr
node_pdf_processor -->|"chunks text"| node_chunking
node_chunking -->|"embeds chunks"| node_embedding
node_pdf_processor -->|"indexes chunks"| node_qdrant
node_pdf_processor -->|"stores OCR text"| node_storage
node_doc_api -->|"creates document"| node_doc_service
node_doc_service -->|"generates field text"| node_llm
node_doc_service -->|"uses prompts"| node_prompt
node_doc_service -->|"fills template"| node_templates
node_presentation_api -->|"parses Markdown"| node_markdown
node_presentation_api -->|"plans slides"| node_ppt_planner
node_presentation_api -->|"composes deck"| node_ppt_composer
node_ppt_planner -->|"uses parsed source"| node_markdown
node_presentation_api -->|"renders plan"| node_ppt_renderer_client
node_ppt_renderer_client -.->|"dispatches rendering"| node_ppt_renderer

click node_app "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/main.py"
click node_chat_api "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/api/chat.py"
click node_upload_api "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/api/upload.py"
click node_presentation_api "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/api/presentation.py"
click node_chat_session "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/core/chat.py"
click node_prompt "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/prompt_service.py"
click node_reranker "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/rerank_service.py"
click node_llm "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/llm_service.py"
click node_qdrant "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/qdrant_service.py"
click node_mssql_retrieval "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/mssql_retrieval_service.py"
click node_text2sql "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/text2sql_service.py"
click node_memory "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/memory_service.py"
click node_report "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/report_service.py"
click node_pdf_processor "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/core/upload.py"
click node_ocr "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/ocr_service.py"
click node_chunking "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/chunking_service.py"
click node_embedding "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/embedding_service.py"
click node_storage "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/storage_service.py"
click node_doc_api "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/api/doc_generator_api.py"
click node_doc_service "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/docs_create_service.py"
click node_ppt_planner "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/presentation/content_planner.py"
click node_markdown "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/presentation/markdown_parser.py"
click node_ppt_composer "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/presentation/composer.py"
click node_ppt_renderer_client "https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/presentation/renderer_client.py"
click node_ppt_renderer "https://github.com/dunh-real/tpv-chatbot-btl/tree/main/src/services/presentation/renderer"
click node_templates "https://github.com/dunh-real/tpv-chatbot-btl/tree/main/src/templates"

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_chat_api,node_upload_api,node_presentation_api,node_backend toneBlue
class node_chat_session,node_prompt,node_reranker,node_llm,node_qdrant,node_mssql_retrieval,node_text2sql,node_memory,node_report,node_mssql,node_redis toneAmber
class node_pdf_processor,node_ocr,node_chunking,node_embedding,node_storage toneMint
class node_doc_api,node_doc_service,node_ppt_planner,node_markdown,node_ppt_composer,node_ppt_renderer_client,node_ppt_renderer,node_templates toneRose
class node_ollama_service toneIndigo
```

## Components

### API and orchestration

- [FastAPI application](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/main.py): `main.py`
- [Chat endpoint](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/api/chat.py): `src/api/chat.py`
- [Upload endpoint](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/api/upload.py): `src/api/upload.py`
- [Presentation endpoint](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/api/presentation.py): `src/api/presentation.py`

### Chat and retrieval

- [Chat session](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/core/chat.py): `src/core/chat.py`
- [Prompt assembly](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/prompt_service.py): `src/services/prompt_service.py`
- [Context reranking](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/rerank_service.py): `src/services/rerank_service.py`
- [Ollama LLM](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/llm_service.py): `src/services/llm_service.py`
- [Vector retrieval](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/qdrant_service.py): `src/services/qdrant_service.py`
- [SQL retrieval](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/mssql_retrieval_service.py): `src/services/mssql_retrieval_service.py`
- [Text-to-SQL](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/text2sql_service.py): `src/services/text2sql_service.py`
- [Conversation memory](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/memory_service.py): `src/services/memory_service.py`
- [Department reports](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/report_service.py): `src/services/report_service.py`

### Document ingestion

- [PDF processing](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/core/upload.py): `src/core/upload.py`
- [OCR extraction](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/ocr_service.py): `src/services/ocr_service.py`
- [Chunking](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/chunking_service.py): `src/services/chunking_service.py`
- [Vector embedding](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/embedding_service.py): `src/services/embedding_service.py`
- [Object storage](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/storage_service.py): `src/services/storage_service.py`

### Document generation

- [Template document API](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/api/doc_generator_api.py): `src/api/doc_generator_api.py`
- [Template document creation](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/docs_create_service.py): `src/services/docs_create_service.py`
- [Slide planning](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/presentation/content_planner.py): `src/services/presentation/content_planner.py`
- [Markdown parsing](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/presentation/markdown_parser.py): `src/services/presentation/markdown_parser.py`
- [Deck composition](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/presentation/composer.py): `src/services/presentation/composer.py`
- [Renderer client](https://github.com/dunh-real/tpv-chatbot-btl/blob/main/src/services/presentation/renderer_client.py): `src/services/presentation/renderer_client.py`
- [PowerPoint renderer](https://github.com/dunh-real/tpv-chatbot-btl/tree/main/src/services/presentation/renderer): `src/services/presentation/renderer`
- [Document templates](https://github.com/dunh-real/tpv-chatbot-btl/tree/main/src/templates): `src/templates`

### Other components

- **Backend / user**
- **MSSQL database**
- **Ollama service**
- **Redis**

## Connections

- Backend / user → FastAPI application: calls API (evidence: `README.md`)
- FastAPI application → Chat endpoint: registers route (evidence: `main.py`)
- FastAPI application → Upload endpoint: registers route (evidence: `main.py`)
- FastAPI application → Presentation endpoint: registers route (evidence: `main.py`)
- Chat endpoint → Chat session: handles chat (evidence: `README.md`)
- Chat session → Conversation memory: reads and saves (evidence: `src/core/chat.py`)
- Chat session → Vector retrieval: retrieves context (evidence: `src/core/chat.py`)
- Chat session → SQL retrieval: retrieves context (evidence: `src/core/chat.py`)
- Chat session → Context reranking: reranks context (evidence: `src/core/chat.py`)
- Chat session → Prompt assembly: builds prompt (evidence: `src/core/chat.py`)
- Chat session → Ollama LLM: requests answer (evidence: `src/core/chat.py`)
- Chat session → Department reports: generates report (evidence: `src/core/chat.py`)
- SQL retrieval → Text-to-SQL: creates SQL (evidence: `src/services/mssql_retrieval_service.py`)
- SQL retrieval → MSSQL database: queries (evidence: `README.md`)
- Ollama LLM → Ollama service: invokes model (evidence: `src/services/llm_service.py`)
- Vector retrieval → Vector embedding: embeds queries (evidence: `src/services/qdrant_service.py`)
- Upload endpoint → PDF processing: queues processing (evidence: `src/api/upload.py`)
- PDF processing → OCR extraction: extracts text (evidence: `src/core/upload.py`)
- PDF processing → Chunking: chunks text (evidence: `src/core/upload.py`)
- Chunking → Vector embedding: embeds chunks (evidence: `src/services/chunking_service.py`)
- PDF processing → Vector retrieval: indexes chunks (evidence: `src/core/upload.py`)
- PDF processing → Object storage: stores OCR text (evidence: `src/core/upload.py`)
- Template document API → Template document creation: creates document (evidence: `src/api/doc_generator_api.py`)
- Template document creation → Ollama LLM: generates field text (evidence: `src/services/docs_create_service.py`)
- Template document creation → Prompt assembly: uses prompts (evidence: `src/services/docs_create_service.py`)
- Template document creation → Document templates: fills template (evidence: `README.md`)
- Presentation endpoint → Markdown parsing: parses Markdown (evidence: `src/api/presentation.py`)
- Presentation endpoint → Slide planning: plans slides (evidence: `src/api/presentation.py`)
- Presentation endpoint → Deck composition: composes deck (evidence: `src/api/presentation.py`)
- Slide planning → Markdown parsing: uses parsed source (evidence: `src/services/presentation/content_planner.py`)
- Presentation endpoint → Renderer client: renders plan (evidence: `src/api/presentation.py`)
- Renderer client → PowerPoint renderer: dispatches rendering
