Backend API Overview
Relevant source files
The following files were used as context for generating this wiki page:
Archivum's backend is a FastAPI-driven service (running on Python 3.12) that acts as the central orchestrator for the AI-powered knowledge base. It manages the ingestion of raw sources, handles wiki page CRUD operations, coordinates with LLM providers for extraction and synthesis, and maintains derived indexes across vector and graph databases. The API is designed to support a local-first deployment via Docker, ensuring that markdown files remain the canonical source of truth while providing high-performance search and query capabilities.
Sources: archivum-prd-v1.0.md:280, README.md:162, Progress.md:21
Core Architecture and Data Flow
The backend utilizes a multi-layered storage and indexing strategy. While the primary content is stored as Markdown files in a dedicated directory, the API synchronizes this data across SQLite (metadata and FTS), Qdrant (vector embeddings), and Kuzu (graph relationships).
System Components
| Service | Technology | Role |
|---|---|---|
| FastAPI | Python 3.12 | Core REST API for ingestion, search, and CRUD. |
| SQLite | Local DB | Stores users, auth state, page metadata, and ingest logs. |
| Qdrant | Vector DB | High-performance semantic search index. |
| Kuzu | Embedded Graph | Stores entity relationships for multi-hop queries. |
| Wiki Agent | Python / LLM | Extracts structured data and generates wiki content. |
Sources: README.md:162-178, archivum-prd-v1.0.md:283-290
Ingestion Data Flow
When a source (file or URL) is sent to the backend, it passes through an automated pipeline that extracts text, processes it through an LLM, and updates all storage layers.
The ingestion process extracts named entities (people, concepts, orgs) and identifies relationships between them to build the persistent knowledge graph.
Sources: archivum-prd-v1.0.md:73-77, apps/backend/archivum/ingest/agent.py:23-45
API Endpoints
The backend exposes several categories of endpoints to facilitate wiki management and AI interaction.
Wiki Page Management (/api/pages)
The pages API handles the lifecycle of wiki content, including title-to-slug conversion and sanitization.
| Method | Endpoint | Description |
|---|---|---|
GET | /api/pages | Lists summaries of all pages in the wiki. |
POST | /api/pages | Creates a new page, generates a slug, and indexes content. |
GET | /api/pages/{slug} | Retrieves full detail, including sanitized content and metadata. |
PUT | /api/pages/{slug} | Updates page content, title, or tags and re-indexes. |
DELETE | /api/pages/{slug} | Removes markdown file and deletes entries from indexes. |
PATCH | /api/pages/{slug}/move | Renames a page and updates all internal wikilinks. |
Sources: apps/backend/archivum/api/pages.py:214-358, packages/archivum-cli/src/api.js:33-40
Retrieval and AI Intelligence
These endpoints leverage the derived indexes for semantic discovery and synthesis.
- Search (
/api/search): Performs semantic search via Qdrant vector similarity. - Query (
/api/query): Utilizes RAG (Retrieval-Augmented Generation) to answer natural language questions with specific citations to wiki pages. - Graph (
/api/graph/neighbors/{id}): Explores relationships by returning neighbors of a specific entity in the graph database. - Lint (
/api/lint): Scans the wiki for health issues such as broken wikilinks or orphan pages.
Sources: packages/archivum-cli/src/api.js:34-39, archivum-prd-v1.0.md:144-159
LLM Interaction and Extraction
The WikiAgent class serves as the interface between the API and LLM providers. It supports multiple providers including Anthropic, OpenRouter, and local options like Ollama.
The agent enforces strict JSON structures and uses [[wikilink]] syntax to maintain internal page relationships.
Sources: apps/backend/archivum/ingest/agent.py:72-130, apps/backend/archivum/api/pages.py:276-290
Security and Validation
The Backend API implements several security layers to protect the self-hosted environment:
- Markdown Sanitization: All content (User or LLM generated) is sanitized using
sanitize_markdownbefore storage or rendering to prevent XSS. - Slug Validation: Slugs are validated to prevent directory traversal and ensure they follow the
kebab-caseformat. - Authentication: Mutating requests require writer permissions, enforced via JWT cookies and bearer tokens (
MCP_API_KEY). - Data Integrity: The
/rawvolume is ideally mounted as read-only to prevent modification of original source files after ingestion.
Sources: apps/backend/archivum/api/pages.py:44-77, 271, archivum-prd-v1.0.md:329-354, README.md:126-135
Conclusion
The Archivum Backend API provides a robust foundation for a self-maintaining knowledge base. By combining traditional file-based storage with modern vector and graph indexing, it enables complex AI workflows while preserving data ownership. Its modular provider system allows users to choose between high-performance cloud LLMs or fully private local models, making it a versatile tool for personal and technical knowledge management.