# asg017/sqlite-vec architecture

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

- Interactive diagram: https://gitdiagram.com/asg017/sqlite-vec
- Repository: https://github.com/asg017/sqlite-vec

## Overview

##### Project type and purpose
- This is an open-source SQLite extension written in pure C (“sqlite-vec”) that adds vector-search capabilities (virtual table module `vec0`) anywhere SQLite runs.
- It provides language bindings (Go, Python, Rust, Node.js, Ruby, etc.), example apps, benchmarks, tests, and a documentation site.

##### File structure
- Top-level:
- Core C extension sources, `Makefile`, `scripts/`, `sqlite-vec.h.tmpl`, `sqlite-dist.toml`.
- `bindings/`: wrappers for Go, Python, Rust (each with its own build files).
- `examples/`: small sample apps in various languages demonstrating loading the extension.
- `benchmarks/`: scripts and suites to measure performance.
- `tests/`: correctness, fuzzing, unit tests across C, Python, Rust, WASM.
- `site/`: VitePress-based documentation and API reference.
- GitHub workflows under `.github/workflows`: CI for test, release, and site deploy.

##### README for additional insights
- Explains core features (floats, int8, binary vectors in `vec0`) and how to install from Python/Node/Go/Rust/Datasette/rqlite.
- Provides sample SQL usage (loading via `.load ./vec0`, creating virtual tables, KNN queries).

##### Essential details to capture
- The modular plug-in nature of SQLite virtual tables.
- Multi-language binding strategy all pointing at the same shared library.
- The CI pipeline gates that ensure tests and docs are published.
- The examples and benchmarks as consumers of both the bindings and the core.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Applications
    subgraph "Client Applications" 
        Examples["Example Applications (Client Apps)"]:::apps
    end

    %% Language Bindings
    subgraph "Language Bindings"
        GoB["Go Binding"]:::binding
        PyB["Python Binding"]:::binding
        RsB["Rust Binding"]:::binding
    end

    %% Core and Engine
    SQLite["SQLite Engine"]:::core
    VecExt["Vec0 Core Extension (C)"]:::core

    %% Storage
    Storage["Storage Layer (DB files / in-memory)"]:::core

    %% Tools
    subgraph "Tools & Tests"
        Bench["Benchmarks & Performance"]:::tools
        Tests["Test Suites & Fuzzing"]:::tools
    end

    %% Documentation and CI
    Docs["Documentation Site (VitePress)"]:::docs
    CI["CI/CD Workflows (GitHub Actions)"]:::ci

    %% Data Flow
    Examples --> GoB
    Examples --> PyB
    Examples --> RsB

    GoB --> SQLite
    PyB --> SQLite
    RsB --> SQLite

    SQLite --> VecExt
    VecExt --> Storage
    Storage -->|"returns results"| SQLite

    %% Tools interactions
    Bench --> VecExt
    Bench --> SQLite
    Tests --> VecExt
    Tests --> SQLite

    %% CI/CD interactions
    CI --> Tests
    CI --> Bench
    CI --> Docs

    %% Click Events
    click VecExt "https://github.com/asg017/sqlite-vec/blob/main/sqlite-vec.c"
    click GoB "https://github.com/asg017/sqlite-vec/tree/main/bindings/go"
    click PyB "https://github.com/asg017/sqlite-vec/tree/main/bindings/python"
    click RsB "https://github.com/asg017/sqlite-vec/tree/main/bindings/rust"
    click Examples "https://github.com/asg017/sqlite-vec/tree/main/examples/"
    click Bench "https://github.com/asg017/sqlite-vec/tree/main/benchmarks/"
    click Tests "https://github.com/asg017/sqlite-vec/tree/main/tests/"
    click Docs "https://github.com/asg017/sqlite-vec/tree/main/site/"
    click CI "https://github.com/asg017/sqlite-vec/tree/main/.github/workflows/"

    %% Styles
    classDef core fill:#FFA500,stroke:#333,stroke-width:1px
    classDef binding fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef apps fill:#EFEFEF,stroke:#333,stroke-width:1px
    classDef tools fill:#90EE90,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef docs fill:#FFFACD,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
    classDef ci fill:#D3D3D3,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
