# greenbinjack/rabitq-library architecture

> Architecture diagram of the GitHub repository greenbinjack/rabitq-library, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/greenbinjack/rabitq-library
- Repository: https://github.com/greenbinjack/rabitq-library

## Overview

RaBitQ Library is a C++17 vector-quantization and approximate-nearest-neighbor search library with Python bindings. The documented user workflow accepts vectors and queries, builds or loads an index, and returns nearest-neighbor IDs and distances. The main branches are IVF, HNSW, and SymphonyQG; quantization, distance estimation, FastScan, and runtime SIMD dispatch provide shared internals. The README establishes the product capabilities; source-index references and excerpts support the more specific module relationships. Some implementation details and Python binding routes were not sampled, so uncertain connections are omitted.

Main entry points: [`include/rabitqlib/index/ivf/ivf.hpp`](https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/index/ivf/ivf.hpp) (IVF index), [`include/rabitqlib/index/hnsw/hnsw.hpp`](https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/index/hnsw/hnsw.hpp) (HNSW index), [`include/rabitqlib/index/symqg/qg.hpp`](https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/index/symqg/qg.hpp) (SymphonyQG index), [`include/rabitqlib/quantization/rabitq.hpp`](https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/quantization/rabitq.hpp) (RaBitQ quantizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Python API"]
  node_common_bindings["Binding helpers"]
  node_ivf_binding["IVF binding<br/>[ivf_bindings.cpp]"]
  node_hnsw_binding["HNSW binding<br/>[hnsw_bindings.cpp]"]
  node_symqg_binding["SymphonyQG binding<br/>[symqg_bindings.cpp]"]
end

subgraph group_indexes["ANN Indexes"]
  node_ivf["IVF index<br/>[ivf.hpp]"]
  node_initializer["Index initializer<br/>[initializer.hpp]"]
  node_hnsw["HNSW index<br/>[hnsw.hpp]"]
  node_hnsw_kernels["HNSW kernels"]
  node_symqg["SymphonyQG index<br/>[qg.hpp]"]
  node_symqg_builder["Graph builder<br/>[qg_builder.hpp]"]
end

subgraph group_quant["Quantization Search"]
  node_quantizer["RaBitQ quantizer<br/>[rabitq.hpp]"]
  node_quant_impl["Quantizer implementation<br/>[rabitq_impl.hpp]"]
  node_layout["Code layout<br/>[data_layout.hpp]"]
  node_query["Query models<br/>[query.hpp]"]
  node_estimator["Distance estimator<br/>[estimator.hpp]"]
  node_lut["Lookup tables<br/>[lut.hpp]"]
  node_fastscan["FastScan<br/>[fastscan.hpp]"]
end

subgraph group_runtime["SIMD Runtime"]
  node_simd_dispatch["SIMD dispatch<br/>[dispatch.cpp]"]
  node_cpu_features["CPU detection<br/>[cpu_features.cpp]"]
  node_space["Vector operations<br/>[space.hpp]"]
  node_space_kernels["SIMD distance kernels"]
end

node_user(("Python user"))

node_user -->|"builds or searches"| node_ivf_binding
node_user -->|"builds or searches"| node_hnsw_binding
node_user -->|"builds or searches"| node_symqg_binding
node_ivf_binding -->|"uses helpers"| node_common_bindings
node_hnsw_binding -->|"uses helpers"| node_common_bindings
node_symqg_binding -->|"uses helpers"| node_common_bindings
node_ivf_binding -->|"exposes"| node_ivf
node_hnsw_binding -->|"exposes"| node_hnsw
node_symqg_binding -->|"exposes"| node_symqg
node_symqg_binding -->|"exposes builder"| node_symqg_builder
node_symqg_builder -->|"builds graph"| node_symqg
node_ivf -->|"uses initialization"| node_initializer
node_hnsw -->|"uses initialization"| node_initializer
node_ivf -->|"quantizes vectors"| node_quantizer
node_hnsw -->|"quantizes vectors"| node_quantizer
node_symqg -->|"stores codes"| node_quantizer
node_quantizer -->|"delegates"| node_quant_impl
node_quantizer -->|"uses layouts"| node_layout
node_ivf -->|"estimates distances"| node_estimator
node_symqg -->|"estimates distances"| node_estimator
node_hnsw -->|"estimates distances"| node_estimator
node_estimator -->|"uses query models"| node_query
node_query -->|"builds lookup tables"| node_lut
node_lut -->|"uses scan layout"| node_fastscan
node_ivf -->|"scans batches"| node_fastscan
node_symqg -->|"scans neighbors"| node_fastscan
node_fastscan -.->|"selects kernels"| node_simd_dispatch
node_simd_dispatch -->|"checks features"| node_cpu_features
node_space -->|"dispatches operations"| node_simd_dispatch
node_simd_dispatch -->|"routes to kernels"| node_space_kernels
node_hnsw -.->|"uses search kernels"| node_hnsw_kernels

click node_common_bindings "https://github.com/greenbinjack/rabitq-library/blob/main/python_bindings/bindings_common.hpp"
click node_ivf_binding "https://github.com/greenbinjack/rabitq-library/blob/main/python_bindings/ivf_bindings.cpp"
click node_hnsw_binding "https://github.com/greenbinjack/rabitq-library/blob/main/python_bindings/hnsw_bindings.cpp"
click node_symqg_binding "https://github.com/greenbinjack/rabitq-library/blob/main/python_bindings/symqg_bindings.cpp"
click node_ivf "https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/index/ivf/ivf.hpp"
click node_initializer "https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/index/ivf/initializer.hpp"
click node_hnsw "https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/index/hnsw/hnsw.hpp"
click node_hnsw_kernels "https://github.com/greenbinjack/rabitq-library/blob/main/src/index/hnsw_search_avx2_kernels.hpp"
click node_symqg "https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/index/symqg/qg.hpp"
click node_symqg_builder "https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/index/symqg/qg_builder.hpp"
click node_quantizer "https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/quantization/rabitq.hpp"
click node_quant_impl "https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/quantization/rabitq_impl.hpp"
click node_layout "https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/quantization/data_layout.hpp"
click node_query "https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/index/query.hpp"
click node_estimator "https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/index/estimator.hpp"
click node_lut "https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/index/lut.hpp"
click node_fastscan "https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/fastscan/fastscan.hpp"
click node_simd_dispatch "https://github.com/greenbinjack/rabitq-library/blob/main/src/simd/dispatch.cpp"
click node_cpu_features "https://github.com/greenbinjack/rabitq-library/blob/main/src/utils/cpu_features.cpp"
click node_space "https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/utils/space.hpp"
click node_space_kernels "https://github.com/greenbinjack/rabitq-library/blob/main/src/simd/space_excode_avx2.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_common_bindings,node_ivf_binding,node_hnsw_binding,node_symqg_binding,node_user toneBlue
class node_ivf,node_initializer,node_hnsw,node_hnsw_kernels,node_symqg,node_symqg_builder toneAmber
class node_quantizer,node_quant_impl,node_layout,node_query,node_estimator,node_lut,node_fastscan toneMint
class node_simd_dispatch,node_cpu_features,node_space,node_space_kernels toneRose
```

## Components

### Python API

- [Binding helpers](https://github.com/greenbinjack/rabitq-library/blob/main/python_bindings/bindings_common.hpp): `python_bindings/bindings_common.hpp`
- [IVF binding](https://github.com/greenbinjack/rabitq-library/blob/main/python_bindings/ivf_bindings.cpp): `python_bindings/ivf_bindings.cpp`
- [HNSW binding](https://github.com/greenbinjack/rabitq-library/blob/main/python_bindings/hnsw_bindings.cpp): `python_bindings/hnsw_bindings.cpp`
- [SymphonyQG binding](https://github.com/greenbinjack/rabitq-library/blob/main/python_bindings/symqg_bindings.cpp): `python_bindings/symqg_bindings.cpp`

### ANN Indexes

- [IVF index](https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/index/ivf/ivf.hpp): `include/rabitqlib/index/ivf/ivf.hpp`
- [Index initializer](https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/index/ivf/initializer.hpp): `include/rabitqlib/index/ivf/initializer.hpp`
- [HNSW index](https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/index/hnsw/hnsw.hpp): `include/rabitqlib/index/hnsw/hnsw.hpp`
- [HNSW kernels](https://github.com/greenbinjack/rabitq-library/blob/main/src/index/hnsw_search_avx2_kernels.hpp): `src/index/hnsw_search_avx2_kernels.hpp`
- [SymphonyQG index](https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/index/symqg/qg.hpp): `include/rabitqlib/index/symqg/qg.hpp`
- [Graph builder](https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/index/symqg/qg_builder.hpp): `include/rabitqlib/index/symqg/qg_builder.hpp`

### Quantization Search

- [RaBitQ quantizer](https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/quantization/rabitq.hpp): `include/rabitqlib/quantization/rabitq.hpp`
- [Quantizer implementation](https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/quantization/rabitq_impl.hpp): `include/rabitqlib/quantization/rabitq_impl.hpp`
- [Code layout](https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/quantization/data_layout.hpp): `include/rabitqlib/quantization/data_layout.hpp`
- [Query models](https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/index/query.hpp): `include/rabitqlib/index/query.hpp`
- [Distance estimator](https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/index/estimator.hpp): `include/rabitqlib/index/estimator.hpp`
- [Lookup tables](https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/index/lut.hpp): `include/rabitqlib/index/lut.hpp`
- [FastScan](https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/fastscan/fastscan.hpp): `include/rabitqlib/fastscan/fastscan.hpp`

### SIMD Runtime

- [SIMD dispatch](https://github.com/greenbinjack/rabitq-library/blob/main/src/simd/dispatch.cpp): `src/simd/dispatch.cpp`
- [CPU detection](https://github.com/greenbinjack/rabitq-library/blob/main/src/utils/cpu_features.cpp): `src/utils/cpu_features.cpp`
- [Vector operations](https://github.com/greenbinjack/rabitq-library/blob/main/include/rabitqlib/utils/space.hpp): `include/rabitqlib/utils/space.hpp`
- [SIMD distance kernels](https://github.com/greenbinjack/rabitq-library/blob/main/src/simd/space_excode_avx2.cpp): `src/simd/space_excode_avx2.cpp`

### Other components

- **Python user**

## Connections

- Python user → IVF binding: builds or searches (evidence: `README.md`)
- Python user → HNSW binding: builds or searches (evidence: `README.md`)
- Python user → SymphonyQG binding: builds or searches (evidence: `README.md`)
- IVF binding → Binding helpers: uses helpers (evidence: `python_bindings/ivf_bindings.cpp`)
- HNSW binding → Binding helpers: uses helpers (evidence: `python_bindings/hnsw_bindings.cpp`)
- SymphonyQG binding → Binding helpers: uses helpers (evidence: `python_bindings/symqg_bindings.cpp`)
- IVF binding → IVF index: exposes (evidence: `python_bindings/ivf_bindings.cpp`)
- HNSW binding → HNSW index: exposes (evidence: `python_bindings/hnsw_bindings.cpp`)
- SymphonyQG binding → SymphonyQG index: exposes (evidence: `python_bindings/symqg_bindings.cpp`)
- SymphonyQG binding → Graph builder: exposes builder (evidence: `python_bindings/symqg_bindings.cpp`)
- Graph builder → SymphonyQG index: builds graph (evidence: `include/rabitqlib/index/symqg/qg_builder.hpp`)
- IVF index → Index initializer: uses initialization (evidence: `include/rabitqlib/index/ivf/ivf.hpp`)
- HNSW index → Index initializer: uses initialization (evidence: `include/rabitqlib/index/hnsw/hnsw.hpp`)
- IVF index → RaBitQ quantizer: quantizes vectors (evidence: `include/rabitqlib/index/ivf/ivf.hpp`)
- HNSW index → RaBitQ quantizer: quantizes vectors (evidence: `include/rabitqlib/index/hnsw/hnsw.hpp`)
- SymphonyQG index → RaBitQ quantizer: stores codes (evidence: `include/rabitqlib/index/symqg/qg.hpp`)
- RaBitQ quantizer → Quantizer implementation: delegates (evidence: `include/rabitqlib/quantization/rabitq.hpp`)
- RaBitQ quantizer → Code layout: uses layouts (evidence: `include/rabitqlib/quantization/rabitq.hpp`)
- IVF index → Distance estimator: estimates distances (evidence: `include/rabitqlib/index/ivf/ivf.hpp`)
- SymphonyQG index → Distance estimator: estimates distances (evidence: `include/rabitqlib/index/symqg/qg.hpp`)
- HNSW index → Distance estimator: estimates distances (evidence: `include/rabitqlib/index/hnsw/hnsw.hpp`)
- Distance estimator → Query models: uses query models (evidence: `include/rabitqlib/index/estimator.hpp`)
- Query models → Lookup tables: builds lookup tables (evidence: `include/rabitqlib/index/query.hpp`)
- Lookup tables → FastScan: uses scan layout (evidence: `include/rabitqlib/index/lut.hpp`)
- IVF index → FastScan: scans batches (evidence: `include/rabitqlib/index/ivf/ivf.hpp`)
- SymphonyQG index → FastScan: scans neighbors (evidence: `include/rabitqlib/index/symqg/qg.hpp`)
- FastScan → SIMD dispatch: selects kernels
- SIMD dispatch → CPU detection: checks features (evidence: `src/simd/dispatch.cpp`)
- Vector operations → SIMD dispatch: dispatches operations (evidence: `include/rabitqlib/utils/space.hpp`)
- SIMD dispatch → SIMD distance kernels: routes to kernels (evidence: `src/simd/dispatch.cpp`)
- HNSW index → HNSW kernels: uses search kernels
