# yichuan-w/leann architecture

> Architecture diagram of the GitHub repository yichuan-w/leann, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yichuan-w/leann
- Repository: https://github.com/yichuan-w/leann

## Overview

##### Project type and purpose
- LEANN is a full‐stack, open-source vector database and RAG (Retrieval-Augmented Generation) toolkit written in Python with C++/CMake backends.
- Purpose: Provide a lightweight, on-device vector index (HNSW, DiskANN) that stores only a pruned graph and recomputes embeddings on-demand, enabling semantic search and chat over personal data (files, emails, browser history, code, WeChat, etc.) with minimal storage.

##### File structure
Top-level directories:
- apps/ – Sample RAG applications (document_rag, email_rag, browser_rag, wechat_rag, code_rag)
- packages/
– leann-core/ Core Python library: API (Builder, Searcher, Chat), CLI entry point, registry, metadata filter
– leann-backend-hnsw/ HNSW graph backend (C++ code, embedding server, CSR conversion)
– leann-backend-diskann/ DiskANN backend (third-party DiskANN integration, embedding server)
– leann-mcp/ MCP glue for Claude Code integration
– wechat-exporter/ Helper for exporting WeChat histories
- scripts/ CI & release scripts
- benchmarks/ Performance & storage comparison scripts
- docs/ Guides, architecture overview, configuration
- tests/ Unit & integration tests
Other: README.md, pyproject.toml, .github/workflows for CI.

##### README for additional insights
- Architecture section describes:
- Graph-based selective recomputation
- High-degree preserving pruning
- Two-level search, dynamic batching
- Technology stack: Python 3.9–3.13, ZeroMQ/Protobuf servers, optional MKL/OpenBLAS, uv CLI, LLM providers (OpenAI, Ollama, HuggingFace).

a. Main components
1. Frontend/CLI & Sample Apps
- CLI (`leann` command)
- apps/*.py scripts for different data sources
2. Core Library (leann-core)
- LeannBuilder, LeannSearcher, LeannChat
- Registry & plugin loader for backends
- Metadata filter, interface definitions
3. Backends (HNSW, DiskANN)
- Embedding servers (ZeroMQ gRPC, Protobuf)
- Graph storage (CSR files, pruned graph)
- Search algorithms (two-level traversal)
4. Storage
- Index files (.leann/indexes/…)
- Pruned graph + metadata JSON
5. External Services
- Embedding providers (OpenAI API, Ollama, HuggingFace)
- LLM for chat (same providers)
- Data exporters (Apple Mail, Chrome profile, WeChatTweak)
b. Relationships & data flows
- CLI / apps invoke Core API →
- Core API calls Builder/Searcher →
- Builder loads data (documents, emails, browser history, etc.) → chunking & metadata →
- Calls embedding server or remote embedding provider →
- Builds pruned graph → writes index files
- Searcher: loads graph → on query, traverses graph → fetches missing embeddings via recomputation →
- Returns nearest neighbors → Chat wraps results + sends to LLM provider → returns response
c. Architectural patterns & principles
- Plugin architecture for backends (searcher_base, registry)
- Separation of concerns:
– Data ingestion (apps)
– Index building & searching (core)
– Storage (files)
– Compute (local embedding server vs external API)
- Resource efficiency: graph recomputation, CSR storage
d. Key technologies & libraries
- Python packages: leann-core, click (CLI), ZeroMQ, Protobuf
- C++/CMake backends: DiskANN, HNSW implementations
- LLM/embedding: OpenAI, HuggingFace, Ollama
- Build tooling: uv, pyproject.toml

##### Essential details
- Plugin registry, metadata filtering, AST chunking component in code_rag
- Optional paths (HNSW vs DiskANN) side by side
- How MCP integration plugs into Claude Code via `leann-mcp`

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-facing Layer
    subgraph "User-facing Layer"
        direction TB
        CLI["CLI (leann)"]:::frontend
        DocApp["Document RAG App"]:::frontend
        EmailApp["Email RAG App"]:::frontend
        BrowserApp["Browser History RAG App"]:::frontend
        CodeApp["Code RAG App"]:::frontend
        ChunkUtil["AST Chunking Util"]:::frontend
        WeChatApp["WeChat RAG App"]:::frontend
        WeChatHist["WeChat History Export"]:::frontend
    end

    %% Core Library
    subgraph "Core Library"
        direction TB
        Api["API (Builder/Searcher/Chat)"]:::core
        Chat["Chat Wrapper"]:::core
        EmbComp["Embedding Compute Orchestration"]:::core
        ServerMgr["Embedding Server Manager"]:::core
        Registry["Plugin Registry & Loader"]:::core
        Metadata["Metadata Filter"]:::core
        Interface["Interface Definitions"]:::core
        SearcherBase["Searcher Base Interface"]:::core
        MCP["MCP Integration (Claude Code)"]:::core
    end

    %% Backend Compute Layer
    subgraph "Backend Compute Layer"
        direction TB
        HNSWServer["HNSW Embedding Server"]:::backend
        HNSWCore["HNSW Backend Core Logic"]:::backend
        HNSWCsr["CSR Conversion"]:::backend
        DiskServer["DiskANN Embedding Server"]:::backend
        DiskCore["DiskANN Backend Core Logic"]:::backend
        DiskProto["DiskANN Protobuf Definitions"]:::backend
        GraphPart["DiskANN Graph Partitioning"]:::backend
    end

    %% Storage Layer
    subgraph "Storage Layer"
        direction TB
        IndexStorage["Index Files (.leann/indexes)"]:::storage
        MetaStorage["Pruned Graph + Metadata JSON"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        EmbProviders["Embedding Providers (OpenAI/Ollama/HF)"]:::external
        LLM["LLM Providers (OpenAI/Ollama/HF)"]:::external
        DataExporters["Data Exporters (WeChat, Mail, Browser)"]:::external
    end

    %% Data Flows
    CLI -->|"invoke"| Api
    DocApp -->|invoke| Api
    EmailApp -->|invoke| Api
    BrowserApp -->|invoke| Api
    CodeApp -->|invoke| Api
    WeChatApp -->|invoke| Api
    WeChatHist -->|export data| Api

    Api -->|"load plugins"| Registry
    Api -->|"build/search/chat"| Chat
    Api -->|"call builder/searcher"| EmbComp
    EmbComp -->|"manage servers"| ServerMgr
    ServerMgr -->|"ZeroMQ/gRPC"| HNSWServer
    ServerMgr -->|"ZeroMQ/gRPC"| DiskServer

    HNSWServer -->|use| HNSWCore
    HNSWCore -->|convert to CSR| HNSWCsr
    HNSWCsr -->|write| IndexStorage

    DiskServer -->|use| DiskCore
    DiskCore -->|partition graph| GraphPart
    DiskCore -->|use proto| DiskProto
    GraphPart -->|write| IndexStorage

    IndexStorage -->|load index| EmbComp
    EmbComp -->|fetch missing embeddings| ServerMgr

    %% Search & Chat Flow
    Api -->|search query| ServerMgr
    ServerMgr -->|traverse graph| IndexStorage
    ServerMgr -->|recompute embeddings| ServerMgr
    ServerMgr -->|results| Chat
    Chat -->|format prompt| LLM
    LLM -->|response| Chat
    Chat -->|return| CLI

    %% External interactions
    EmbComp -->|fallback| EmbProviders
    Chat -->|use| LLM
    Api -->|data ingestion| DataExporters

    %% Click Events
    click CLI "https://github.com/yichuan-w/leann/blob/main/packages/leann-core/src/leann/cli.py"
    click DocApp "https://github.com/yichuan-w/leann/blob/main/apps/document_rag.py"
    click EmailApp "https://github.com/yichuan-w/leann/blob/main/apps/email_rag.py"
    click BrowserApp "https://github.com/yichuan-w/leann/blob/main/apps/browser_rag.py"
    click CodeApp "https://github.com/yichuan-w/leann/blob/main/apps/code_rag.py"
    click ChunkUtil "https://github.com/yichuan-w/leann/blob/main/apps/chunking/utils.py"
    click WeChatApp "https://github.com/yichuan-w/leann/blob/main/apps/wechat_rag.py"
    click WeChatHist "https://github.com/yichuan-w/leann/blob/main/apps/history_data/wechat_history.py"
    click Api "https://github.com/yichuan-w/leann/blob/main/packages/leann-core/src/leann/api.py"
    click Chat "https://github.com/yichuan-w/leann/blob/main/packages/leann-core/src/leann/chat.py"
    click EmbComp "https://github.com/yichuan-w/leann/blob/main/packages/leann-core/src/leann/embedding_compute.py"
    click ServerMgr "https://github.com/yichuan-w/leann/blob/main/packages/leann-core/src/leann/embedding_server_manager.py"
    click Registry "https://github.com/yichuan-w/leann/blob/main/packages/leann-core/src/leann/registry.py"
    click Metadata "https://github.com/yichuan-w/leann/blob/main/packages/leann-core/src/leann/metadata_filter.py"
    click Interface "https://github.com/yichuan-w/leann/blob/main/packages/leann-core/src/leann/interface.py"
    click SearcherBase "https://github.com/yichuan-w/leann/blob/main/searcher_base.py"
    click MCP "https://github.com/yichuan-w/leann/blob/main/packages/leann-core/src/leann/mcp.py"
    click HNSWServer "https://github.com/yichuan-w/leann/blob/main/packages/leann-backend-hnsw/leann_backend_hnsw/hnsw_embedding_server.py"
    click HNSWCore "https://github.com/yichuan-w/leann/blob/main/packages/leann-backend-hnsw/leann_backend_hnsw/hnsw_backend.py"
    click HNSWCsr "https://github.com/yichuan-w/leann/blob/main/packages/leann-backend-hnsw/leann_backend_hnsw/convert_to_csr.py"
    click DiskServer "https://github.com/yichuan-w/leann/blob/main/packages/leann-backend-diskann/leann_backend_diskann/diskann_embedding_server.py"
    click DiskCore "https://github.com/yichuan-w/leann/blob/main/packages/leann-backend-diskann/leann_backend_diskann/diskann_backend.py"
    click DiskProto "https://github.com/yichuan-w/leann/blob/main/packages/leann-backend-diskann/leann_backend_diskann/embedding_pb2.py"
    click GraphPart "https://github.com/yichuan-w/leann/blob/main/packages/leann-backend-diskann/leann_backend_diskann/graph_partition.py"
    click DataExporters "https://github.com/yichuan-w/leann/blob/main/packages/wechat-exporter/main.py"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef core fill:#E2F0D9,stroke:#1C5E20,color:#1C5E20
    classDef backend fill:#FFE8CC,stroke:#D9822B,color:#D9822B
    classDef storage fill:#F0F0F0,stroke:#6A6A6A,color:#6A6A6A
    classDef external fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A
```
