Architecture

NotebookTG is a layered system with Telegram bot + FastAPI backend sharing services.

Runtime Layers

→

Bot

→

Services

→

DB + Vector

→

LLM

User-facing entry points

notebooktg/app/botTelegram Botaiogram handlers, commands, callbacks

notebooktg/app/apiFastAPIHTTP routes for notebooks, uploads, Q&A

Business logic and workflows

notebooktg/app/servicesServicesNotebook, upload, note, sharing, answer, generation

Data processing pipeline

notebooktg/app/ingestionIngestionPDF, TXT, DOCX, MD, CSV, EPUB extraction

notebooktg/app/retrievalRetrievalChunking, vector search, citation mapping

Core utilities and storage

notebooktg/app/dbDatabaseAsync SQLAlchemy, Alembic migrations

notebooktg/app/llmLLMProvider abstraction for chat and embeddings

notebooktg/app/coreCoreSettings, prompts, logging, validation

Backend

Python, FastAPI, aiogram

Database

PostgreSQL + Alembic

Vector Store

Qdrant (or memory)

LLM

OpenAI-compatible

• Source grounding is notebook-scoped by default — retrieval searches within the selected notebook
• Citations map to persisted chunks and are never fabricated
• Notebooks carry persona, style, and answer-length preferences
• Prompts layer protection against prompt injection — uploaded text treated as untrusted
• Fallback behavior is explicit when evidence is missing