A multi-tenant Documentation Chatbot SaaS application. This platform allows software organizations to upload documentation files (.pdf, .md, .zip) and serve a secure, context-aware chatbot widget for their developers or clients.
The system enforces strict data isolation between tenants at the database layer (PostgreSQL Row-Level Security) and the vector store layer (isolated Qdrant collections).
- API Framework: FastAPI with Python 3.12+ (compatible up to Python 3.14).
- Database: PostgreSQL with Row-Level Security (RLS) policies.
- ORM: SQLAlchemy 2.0 (asyncio extension) with asyncpg driver.
- Vector DB: Qdrant (dynamic client utilizing fast dense/sparse hybrid search).
- Reranking: Cohere Rerank (rerank-english-v3.0).
- Generation: DeepSeek Chat (deepseek-chat) LLM completions.
- Task Queue: Celery with Redis for asynchronous file ingestion.
- Observability: OpenTelemetry middleware and Langfuse SDK integration for token tracking, latency, and costs.
- Real-time Guardrails: Confidence Scorer and LLM-as-a-judge Hallucination Guard.
- Core: React 18, TypeScript, and Vite.
- Styling: Vanilla CSS for flexibility and glassmorphic premium UI elements.
- Services: Modular API client (ApiService) decoupled from UI components.
- Services: Managed via Docker Compose (PostgreSQL, Qdrant, Redis, Jaeger).
├── backend/
│ ├── app/
│ │ ├── api/
│ │ │ └── v1/
│ │ │ ├── api.py # Registers the v1 API routes
│ │ │ └── endpoints/
│ │ │ ├── auth.py # Endpoints for user/organization signup and login
│ │ │ ├── chat.py # RAG query, conversation management, and history endpoints
│ │ │ └── documents.py # Document upload, delete, and list endpoints
│ │ ├── core/
│ │ │ ├── config.py # Pydantic settings loading env variables
│ │ │ ├── context.py # Thread-local tenant context
│ │ │ ├── database.py # SQLAlchemy engine, session maker, and RLS initialization
│ │ │ ├── observability.py # OpenTelemetry and Langfuse tracing initialization
│ │ │ └── security.py # JWT, password hashing, and authentication dependencies
│ │ ├── models/
│ │ │ └── models.py # SQLAlchemy Database Models (Organization, User, Document, etc.)
│ │ ├── schemas/
│ │ │ ├── auth.py # Pydantic schemas for authentication
│ │ │ ├── chat.py # Pydantic schemas for chat requests and responses
│ │ │ └── document.py # Pydantic schemas for documents
│ │ ├── services/
│ │ │ ├── ingestion/
│ │ │ │ ├── manager.py # Manages file routing, parsing, and collection ingestion
│ │ │ │ ├── markdown.py # Parses markdown and ZIP files with frontmatter cleaning
│ │ │ │ ├── pdf.py # Extracts text from PDFs using pypdf
│ │ │ │ └── splitter.py # Custom recursive character splitter
│ │ │ ├── reranker.py # Integrates Cohere Rerank API
│ │ │ └── vector_db.py # Manages Qdrant client, isolated collections, and hybrid search
│ │ └── workers/
│ │ ├── celery_app.py # Celery application configuration
│ │ └── tasks.py # Celery background tasks for asynchronous ingestion
│ ├── scripts/
│ │ └── test_rag.py # E2E Smoke testing script
│ └── tests/
│ ├── conftest.py # Pytest fixtures and test database setup (SQLite)
│ ├── eval_dataset.json # 50 QA dataset pairs for RAG quality audit
│ ├── test_api.py # Integrations tests for signup, login, upload, and mock RAG query
│ ├── test_async.py # Asynchronous ingestion testing
│ ├── test_eval.py # RAG Automated Quality Evaluation Suite
│ └── test_rls.py # Tests Row-Level Security tenant context resolution
├── frontend/
│ ├── src/
│ │ ├── components/
│ │ │ ├── ApiKeys/
│ │ │ │ └── ApiKeyManager.tsx # Clipboard copy of organization API keys
│ │ │ ├── Auth/
│ │ │ │ └── AuthCard.tsx # Tabbed authentication layout for login and signup
│ │ │ ├── Chat/
│ │ │ │ └── ChatSandbox.tsx # RAG query testbed highlighting confidence and faithfulness
│ │ │ ├── Dashboard/
│ │ │ │ ├── Sidebar.tsx # Navigation sidebar
│ │ │ │ └── StatsCards.tsx # KPI summaries
│ │ │ └── Documents/
│ │ │ └── DocumentManager.tsx # Drag-and-drop document uploader with ingestion status updates
│ │ ├── services/
│ │ │ └── api.ts # Decoupled api.ts client handling all backend requests
│ │ ├── App.tsx # Root component orchestration tabs and state
│ │ ├── App.css
│ │ ├── index.css # Premium vanilla CSS styling guide
│ │ └── main.tsx
│ └── tsconfig.json
└── docker-compose.yml
The entire platform (Docker infrastructure, backend FastAPI, Celery worker, and Vite React frontend) can be started using a single command:
- Follow the Prerequisites below.
- Create and configure the
backend/.envfile (see configuration details in Step 2 of Manual Setup). - Run the orchestration script from the project root:
Or:
./run.sh
This will automatically spin up the Docker containers, wait for them to be healthy, check/install dependencies, start the backend, worker, and frontend concurrently, and multiplex their logs. Presspython3 run.py
Ctrl+Cto terminate all services cleanly.
- Docker and Docker Compose installed.
- Python 3.12+ installed.
- Node.js 18+ and npm installed.
If you prefer to run or debug services individually, follow these manual steps:
From the project root directory, launch PostgreSQL, Qdrant, Redis, and Jaeger:
docker compose up -d- Navigate to the backend directory:
cd backend - Create a virtual environment and activate it:
python -m venv venv source venv/bin/activate - Install dependencies:
pip install --upgrade pip pip install -r requirements.txt
- Create a
.envfile in thebackend/directory with the following variables (update with your API keys):DATABASE_URL=postgresql+asyncpg://postgres:postgrespassword@localhost:5432/botforweb REDIS_URL=redis://localhost:6379/0 QDRANT_URL=http://localhost:6333 DEEPSEEK_API_KEY=your_deepseek_api_key COHERE_API_KEY=your_cohere_api_key JWT_SECRET_KEY=generate_a_secure_random_key_here # Observability Settings (Optional) ENABLE_OBSERVABILITY=true JAEGER_OTLP_ENDPOINT=http://localhost:4317 LANGFUSE_PUBLIC_KEY=your_langfuse_public_key LANGFUSE_SECRET_KEY=your_langfuse_secret_key LANGFUSE_HOST=https://cloud.langfuse.com
- Apply database table initialization and run FastAPI:
Note: The database tables and Row-Level Security (RLS) policies are automatically initialized during the FastAPI app startup lifecycle hook.
PYTHONPATH=. ./venv/bin/uvicorn app.main:app --port 8000 --reload
Keep the FastAPI server running and open a new terminal window to start the Celery worker process:
cd backend
source venv/bin/activate
PYTHONPATH=. ./venv/bin/celery -A app.workers.celery_app worker --loglevel=info- Navigate to the frontend directory:
cd frontend - Install npm dependencies:
npm install
- Start the Vite React development server:
npm run dev -- --port 3001
- Open your browser and navigate to
http://localhost:3001to access the Admin Console.
When a query is received, the retrieved context chunks are scored by Qdrant and Cohere Rerank. If the maximum similarity/rerank score is below 0.6, a disclaimer is automatically appended to the response: "I am not highly confident in this answer because it's not well-documented."
Before returning the generated answer, an LLM-as-a-judge fact-checker assesses the answer against the retrieved context to calculate a faithfulness score. If the score is below 0.7, a warning is prepended to the answer warning the user that it may contain unsupported details.
- OpenTelemetry: Tracks incoming FastAPI requests and logs spans to a local Jaeger instance (accessible at
http://localhost:16686). - Langfuse: Traces LLM calls, costs, latency, and prompt/generation tokens.
To verify database isolation policies, API controllers, security credentials, and asynchronous tasks, run pytest inside the virtual environment:
cd backend
PYTHONPATH=. ./venv/bin/pytestTo audit RAG accuracy metrics (Faithfulness and Answer Relevance) against a QA dataset of 50 test cases, run:
cd backend
PYTHONPATH=. ./venv/bin/pytest tests/test_eval.py -sIf DeepSeek credentials are not set, it gracefully defaults to mock evaluation scoring.
To verify the complete ingestion queue flow, polling endpoints, and chatbot response citations against a running backend, run:
cd backend
PYTHONPATH=. ./venv/bin/python scripts/test_rag.pyThis script signs up a dummy organization user, uploads a markdown file, waits for Celery task completion, queries the chatbot, verifies sources, and cleans up database/vector points.