Backend Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
KnowledgeVault's backend is a high-performance Retrieval-Augmented Generation (RAG) service built with Python 3.11 and the FastAPI framework. It serves as the orchestration layer between the React-based frontend and various data storage systems, including SQLite for relational data and LanceDB for vector embeddings. The architecture is designed to handle multi-format document ingestion, semantic search, and persistent memory across user chat sessions.
The backend manages the entire RAG pipeline—from document parsing and chunking to query classification and LLM response generation. It integrates with external services like Ollama for local LLM inference and Harrier TEI for dense vector embedding generation.
Sources: README.md:1-20, CONTRIBUTING.md:10-15, INSTALLATION.md:5-15
System Overview
The backend operates as a central hub connecting the user interface to specialized data stores and AI services.
The diagram shows the interaction between the FastAPI orchestration layer, the dual-database storage strategy, and external AI providers.
Sources: README.md:38-60, specs/wire-wiki-chat/SPEC.md:120-135
Core Backend Components
1. RAG Engine Orchestration
The RAGEngine is the primary orchestrator for chat interactions. It utilizes a QueryClassifier to determine if a query is entity-heavy, which guides the retrieval strategy. It sequences retrieval from multiple namespaces to provide the LLM with comprehensive context.
- Retrieval Priority: The engine employs a "Wiki-first" ranking, followed by Knowledge Management System (KMS) entries, then raw document retrieval.
- Citation Namespaces: Evidence is tagged with specific prefixes for the LLM and Frontend:
[S#]: Document sources (RAG retrieval)[M#]: Memory records (User context)[W#]: Wiki claims (Compiled knowledge)[K#]: KMS entries (Curated documentation)
Sources: specs/wire-wiki-chat/SPEC.md:138-145, specs/kms-content-search-rag/SPEC.md:120-130, README.md:105-115
2. Specialized Retrieval Services
The backend implements dedicated services to query structured and semi-structured knowledge:
| Service | Focus | Retrieval Method |
|---|---|---|
| WikiRetrievalService | Domain-specific claims | Full-Text Search (FTS) + Relation lookup |
| KMSRetrievalService | Curated documentation | FTS5 JOIN on entries with status filters |
| DocumentRetrieval | Raw document chunks | Vector similarity (LanceDB) + Reranking |
| MemoryStore | User-specific context | SQLite FTS5-backed retrieval |
Sources: specs/wire-wiki-chat/SPEC.md:40-55, specs/kms-content-search-rag/SPEC.md:105-115, README.md:100-110
Data Layer Architecture
Relational and Search Storage (SQLite)
SQLite serves as the primary relational database for metadata, chat sessions, and user management. It extensively uses the FTS5 extension for high-performance text searching.
- Wiki Tables: Store claims, entities, and relationships.
- KMS Tables: Store curated entries with tags and status (draft/published).
- FTS Indices:
files_content_fts: Indexes document body text via external-content triggers.wiki_claims_fts: Indexes claims for entity-based retrieval.kms_entries_fts: Indexes titles and summaries for KMS search.
Sources: specs/kms-content-search-rag/SPEC.md:95-103, backend/app/api/routes/wiki.py:10-50, README.md:118-125
Vector Storage (LanceDB)
LanceDB handles high-dimensional vector embeddings generated by the Harrier TEI service. It supports:
- Semantic Search: Cosine similarity for document chunk retrieval.
- Hybrid Search: Combining vector results with keyword-based scores.
- Multi-Scale Indexing: Indexing different chunk sizes (e.g., 768 and 1536 characters) to improve recall.
Sources: README.md:140-150, INSTALLATION.md:240-250
API and Routing Structure
The API is organized into functional modules within backend/app/api/routes/. Access is governed by JWT Authentication and Role-Based Access Control (RBAC).
Wiki Subsystem API
The Wiki API manages the lifecycle of compiled knowledge. It is gated by a require_wiki_enabled dependency that returns HTTP 503 if the subsystem is toggled off in settings.
@router.get("/wiki/pages")
async def list_wiki_pages(
vault_id: int = Query(..., description="Vault ID"),
page_type: Optional[str] = Query(None),
status: Optional[str] = Query(None),
search: Optional[str] = Query(None),
page: int = Query(1, ge=1),
per_page: int = Query(50, ge=1, le=200),
db: sqlite3.Connection = Depends(get_db),
user: dict = Depends(get_current_active_user),
):
await _require_vault_read(user, vault_id)
store = WikiStore(db)
pages = store.list_pages(vault_id, page_type=page_type, status=status, search=search, page=page, per_page=per_page)
return {"pages": [_as_dict(p) for p in pages], "page": page, "per_page": per_page}
Example showing vault-scoped policy enforcement and store-based retrieval.
Sources: backend/app/api/routes/wiki.py:32-38, backend/app/api/routes/wiki.py:100-112
API Route Categories
| Namespace | Responsibility |
|---|---|
/chat | SSE streaming, session management, and history persistence |
/documents | File uploads, status tracking, and directory scanning |
/wiki | Claim/Page management, linting, and memory promotion |
/memories | User-defined fact storage and semantic memory search |
/vaults | Multi-tenant logical isolation of data |
/auth | JWT issuance, registration, and session revocation |
Sources: README.md:210-310, backend/app/api/routes/wiki.py:1-20
RAG Data Flow
The sequence of operations during a user query demonstrates the interaction between the backend services.
This flow ensures that structured wiki knowledge is prioritized while falling back to raw document search for exhaustive coverage.
Sources: specs/wire-wiki-chat/SPEC.md:120-135, specs/kms-content-search-rag/SPEC.md:110-125
Conclusion
The backend architecture of KnowledgeVault is optimized for local, self-hosted deployment while maintaining high engineering standards for data retrieval and AI integration. By combining a flexible FastAPI service layer with robust search capabilities in SQLite and LanceDB, it provides a performant and extensible foundation for technical document interaction.
Sources: README.md:1-10, CONTRIBUTING.md:5-15