# lanterndata/lantern architecture

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

- Interactive diagram: https://gitdiagram.com/lanterndata/lantern
- Repository: https://github.com/lanterndata/lantern

## Overview

##### Project Type and Purpose
- Lantern is primarily a database-centric system:
- A PostgreSQL extension (“lantern_hnsw”) written in C/C++ (via CMake) to provide a high-performance HNSW index on vector columns.
- A Rust-based command-line tool and background daemon (“lantern_cli”) to manage jobs (index building, embeddings, autotuning) and optionally expose a REST API.
- An auxiliary Rust Postgres extension (“lantern_extras”) offering extra search and embedding helper functions (BM25, bloom filters, stemmers, etc.).
- Purpose: let users store vectors in PostgreSQL, generate embeddings (local or via external API), build/serve HNSW indexes (inside or outside the DB), and run nearest-neighbor searches.

##### File Structure Analysis
- Top-level directories:
- .github, ci, docker: CI/CD, build scripts, Docker-based packaging.
- lantern_hnsw: C library & SQL for the PG extension (usearch integration, HNSW code, SQL update scripts).
- lantern_cli: Rust CLI + daemon + HTTP server + embedding runtimes + client code for external index builder.
- lantern_extras: Rust PGRX extension with helper functions and SQL artifacts.
- Patterns:
- Polyglot codebase (C/C++ for performance, Rust for orchestration and safety).
- Modular design: core indexer (C), CLI/daemon (Rust), extras extension (Rust/PGRX).
- Deployment support: Dockerfiles for CLI, extension, CI workflows, packaging scripts.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    User["User/Application"]:::ext

    %% CLI/Daemon Layer
    subgraph "lantern_cli (Rust)" 
        CLIEntrypoint["CLI Entry (main)"]:::rust
        CLIFrontend["CLI Front-end"]:::rust
        Daemon["Daemon"]:::rust
        HTTPServer["HTTP Server"]:::rust
        subgraph "Embedding Runtime"
            RuntimeIF["Runtime Interface"]:::rust
            OpenAI["OpenAI Runtime"]:::rust
            Cohere["Cohere Runtime"]:::rust
            HTTPPR["HTTP Runtime"]:::rust
            ONNXPR["ONNX Runtime"]:::rust
            Utils["Utils"]:::rust
        end
        subgraph "External Index Builder"
            EIBServer["Server"]:::rust
            EIBCLI["CLI Interface"]:::rust
        end
        PQ["Product Quantization (PQ)"]:::rust
        Autotune["Index Autotuner CLI"]:::rust
    end

    %% Database Layer
    subgraph "PostgreSQL"
        PG["Postgres"]:::db
        HNSW["lantern_hnsw (C)"]:::c
        EXTRAS["lantern_extras (Rust/PGRX)"]:::rust
    end

    %% External Services
    OpenAIAPI["OpenAI API"]:::ext
    CohereAPI["Cohere API"]:::ext
    ONNXLocal["ONNX Runtime (local)"]:::ext
    OtherAI["Other AI APIs"]:::ext

    %% Deployment & CI
    DockerPG["Dockerized Postgres"]:::ext
    DockerCLI["Docker CLI Image"]:::ext
    CI["CI/CD & Docker Build"]:::ext

    %% Relationships
    User --> CLIEntrypoint
    CLIEntrypoint --> CLIFrontend
    CLIFrontend --> PG
    CLIFrontend --> Daemon
    CLIFrontend --> HTTPServer
    CLIFrontend --> PQ
    CLIFrontend --> Autotune

    Daemon --> RuntimeIF
    RuntimeIF --> OpenAI
    RuntimeIF --> Cohere
    RuntimeIF --> HTTPPR
    RuntimeIF --> ONNXPR
    RuntimeIF --> Utils

    OpenAI --> OpenAIAPI
    Cohere --> CohereAPI
    HTTPPR --> OtherAI
    ONNXPR --> ONNXLocal

    Daemon --> EIBServer
    Daemon --> EIBCLI
    EIBServer --> PG

    HTTPServer --> PG

    PG --> HNSW
    PG --> EXTRAS

    DockerPG --> PG
    DockerCLI --> CLIEntrypoint
    CI --> DockerPG
    CI --> DockerCLI

    %% Click Events
    click CLIEntrypoint "https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/main.rs"
    click CLIFrontend "https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/cli.rs"
    click Daemon "https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/daemon/mod.rs"
    click HTTPServer "https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/http_server/mod.ts"
    click RuntimeIF "https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/embeddings/core/runtime.rs"
    click OpenAI "https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/embeddings/core/openai_runtime.rs"
    click Cohere "https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/embeddings/core/cohere_runtime.rs"
    click HTTPPR "https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/embeddings/core/http_runtime.rs"
    click ONNXPR "https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/embeddings/core/ort_runtime.rs"
    click Utils "https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/embeddings/core/utils.rs"
    click EIBServer "https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/external_index/server.rs"
    click EIBCLI "https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/external_index/cli.rs"
    click PQ "https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/pq/mod.rs"
    click Autotune "https://github.com/lanterndata/lantern/blob/main/lantern_cli/src/index_autotune/mod.rs"
    click HNSW "https://github.com/lanterndata/lantern/blob/main/lantern_hnsw/CMakeLists.txt"
    click EXTRAS "https://github.com/lanterndata/lantern/blob/main/lantern_extras/lantern_extras.control"
    click DockerPG "https://github.com/lanterndata/lantern/blob/main/docker/Dockerfile.pg"
    click DockerCLI "https://github.com/lanterndata/lantern/blob/main/docker/Dockerfile.cli"
    click CI "https://github.com/lanterndata/lantern/tree/main/.github/workflows/"

    %% Styles
    classDef db fill:#bbf,stroke:#333
    classDef rust fill:#bef,stroke:#333
    classDef c fill:#fbb,stroke:#333
    classDef ext fill:#fbc,stroke:#333
```
