# unum-cloud/usearch architecture

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

- Interactive diagram: https://gitdiagram.com/unum-cloud/usearch
- Repository: https://github.com/unum-cloud/usearch

## Overview

##### Project type and purpose
- USearch is an open-source, single-file C++11 similarity-search and clustering engine (HNSW) with native bindings in 10+ languages. It’s not a monolithic app but a library/toolkit that exposes a common core to multiple host languages.

##### File structure
- Top-level build & config: CMakeLists.txt, build.rs, build.gradle, binding.gyp, Cargo.toml, pyproject.toml, Dockerfile, GitHub workflows.
- Core C++ engine: include/usearch/index.hpp + lib.cpp under each language folder.
- Language bindings:
- c/ (C99 API)
- cpp/ (C++ examples/tests)
- python/ (CPython extension, setup.py, pyproject.toml, client/server modules)
- javascript/ (node-gyp + TypeScript definitions)
- java/ (JNI wrapper cloud_unum_usearch_Index.cpp + Maven/CMake config)
- csharp/ (P/Invoke via NativeMethods, .NET solution)
- golang/ (cgo wrapper)
- rust/ (build.rs + lib.rs)
- swift/, objc/, wasm/, sqlite/, wolfram/…
- Documentation: docs/ (Sphinx), assets/, language-specific .rst files
- Tests & benchmarks: *test.* files in each language folder + BENCHMARKS.md
- CI/CD & publishing: .github/workflows (release, prerelease), .releaserc, npmignore, MANIFEST.in

##### README for additional insights
- Central “single C++ header” library.
- Unified API (“Index” object, add/search/serialize) across all bindings.
- Advanced features: user-defined metrics via JIT, multi-index lookups, clustering, joins, quantization.
- Integration points: NumPy, Numba, JNI, P/Invoke, cgo, node-gyp, Rust FFI, etc.
- Distribution targets: PyPI, npm, crates.io, NuGet, Maven, homebrew, Docker image.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Components
    subgraph "Core"
        CORE["Core Engine (C++)"]:::core
        SIMD["SIMD Backend (simsimd)"]:::core
    end

    %% Language Bindings
    subgraph "Language Bindings"
        C_BINDING["C Binding (C99 API)"]:::binding
        CPP_BINDING["C++ Examples & Tests"]:::binding
        PY_BINDING["Python Binding"]:::binding
        JS_BINDING["JavaScript Binding"]:::binding
        JAVA_BINDING["Java Binding"]:::binding
        CS_BINDING["C# Binding"]:::binding
        GO_BINDING["Go Binding"]:::binding
        RUST_BINDING["Rust Binding"]:::binding
        SWIFT_BINDING["Swift Binding"]:::binding
        OBJC_BINDING["Objective-C Binding"]:::binding
        SQLITE_BINDING["SQLite Extension"]:::binding
        WASM_BINDING["WebAssembly Binding"]:::binding
        WOLFRAM_BINDING["Wolfram Binding"]:::binding
    end

    %% Build & Toolchain
    subgraph "Build & Toolchain"
        BUILD_SYS["Build System & Toolchain"]:::pipeline
    end

    %% CI/CD
    subgraph "CI/CD Pipelines"
        PRERELEASE["Prerelease Workflow"]:::pipeline
        RELEASE["Release Workflow"]:::pipeline
        RC["Release Config (.releaserc)"]:::pipeline
    end

    %% Documentation
    DOC["Documentation Generator (Sphinx)"]:::external

    %% Registries
    subgraph "Package Registries"
        PYPI["PyPI"]:::external
        NPM["npm"]:::external
        CRATES["crates.io"]:::external
        NUGET["NuGet"]:::external
        MAVEN["Maven Central"]:::external
    end

    %% Examples & Benchmarks
    EB["Examples & Benchmarks"]:::external

    %% Relationships
    PY_BINDING -->|"FFI/API call"| CORE
    JS_BINDING -->|"FFI/API call"| CORE
    JAVA_BINDING -->|"FFI/API call"| CORE
    CS_BINDING -->|"FFI/API call"| CORE
    GO_BINDING -->|"FFI/API call"| CORE
    RUST_BINDING -->|"FFI/API call"| CORE
    SWIFT_BINDING -->|"FFI/API call"| CORE
    OBJC_BINDING -->|"FFI/API call"| CORE
    SQLITE_BINDING -->|"FFI/API call"| CORE
    WASM_BINDING -->|"FFI/API call"| CORE
    WOLFRAM_BINDING -->|"FFI/API call"| CORE
    C_BINDING -->|"FFI/API call"| CORE
    CPP_BINDING -->|"Examples/Test linking"| CORE

    BUILD_SYS -->|"Compiles| Generates artifacts"| CORE
    BUILD_SYS -->|"Prepares| Wrappers"| C_BINDING
    BUILD_SYS -->|"Prepares| Wrappers"| PY_BINDING
    BUILD_SYS -->|"Prepares| Wrappers"| JS_BINDING
    BUILD_SYS -->|"Prepares| Wrappers"| JAVA_BINDING
    BUILD_SYS -->|"Prepares| Wrappers"| CS_BINDING
    BUILD_SYS -->|"Prepares| Wrappers"| GO_BINDING
    BUILD_SYS -->|"Prepares| Wrappers"| RUST_BINDING
    BUILD_SYS -->|"Prepares| Wrappers"| SWIFT_BINDING
    BUILD_SYS -->|"Prepares| Wrappers"| OBJC_BINDING
    BUILD_SYS -->|"Prepares| Wrappers"| SQLITE_BINDING
    BUILD_SYS -->|"Prepares| Wrappers"| WASM_BINDING
    BUILD_SYS -->|"Prepares| Wrappers"| WOLFRAM_BINDING
    BUILD_SYS -->|"Integrates| SIMD"| SIMD

    PRERELEASE -->|"Triggers| Build & Test"| BUILD_SYS
    RELEASE -->|"Triggers| Build & Publish"| BUILD_SYS
    BUILD_SYS -->|"Outputs| Artifacts"| PYPI
    BUILD_SYS -->|"Outputs| Artifacts"| NPM
    BUILD_SYS -->|"Outputs| Artifacts"| CRATES
    BUILD_SYS -->|"Outputs| Artifacts"| NUGET
    BUILD_SYS -->|"Outputs| Artifacts"| MAVEN

    DOC -->|"Reads| docs/ + comments"| CORE
    DOC -->|"Publishes| GitHub Pages"| DOC

    EB -->|"Sources| BENCHMARKS.md & tests"| BUILD_SYS

    %% Click Events
    click CORE "https://github.com/unum-cloud/usearch/blob/main/include/usearch/index.hpp"
    click SIMD "https://github.com/unum-cloud/usearch/tree/main/simsimd/"
    click BUILD_SYS "https://github.com/unum-cloud/usearch/blob/main/CMakeLists.txt"
    click PRERELEASE "https://github.com/unum-cloud/usearch/blob/main/.github/workflows/prerelease.yml"
    click RELEASE "https://github.com/unum-cloud/usearch/blob/main/.github/workflows/release.yml"
    click RC "https://github.com/unum-cloud/usearch/blob/main/.releaserc"
    click DOC "https://github.com/unum-cloud/usearch/tree/main/docs/"
    click C_BINDING "https://github.com/unum-cloud/usearch/blob/main/c/usearch.h"
    click CPP_BINDING "https://github.com/unum-cloud/usearch/blob/main/cpp/bench.cpp"
    click PY_BINDING "https://github.com/unum-cloud/usearch/blob/main/python/lib.cpp"
    click JS_BINDING "https://github.com/unum-cloud/usearch/blob/main/javascript/lib.cpp"
    click JAVA_BINDING "https://github.com/unum-cloud/usearch/blob/main/java/cloud/unum/usearch/Index.java"
    click CS_BINDING "https://github.com/unum-cloud/usearch/blob/main/csharp/src/Cloud.Unum.USearch/NativeMethods.cs"
    click GO_BINDING "https://github.com/unum-cloud/usearch/blob/main/golang/lib.go"
    click RUST_BINDING "https://github.com/unum-cloud/usearch/blob/main/rust/lib.rs"
    click SWIFT_BINDING "https://github.com/unum-cloud/usearch/blob/main/swift/USearchIndex.swift"
    click OBJC_BINDING "https://github.com/unum-cloud/usearch/blob/main/objc/USearchObjective.mm"
    click SQLITE_BINDING "https://github.com/unum-cloud/usearch/blob/main/sqlite/lib.cpp"
    click WASM_BINDING "https://github.com/unum-cloud/usearch/blob/main/wasm/lib.cpp"
    click WOLFRAM_BINDING "https://github.com/unum-cloud/usearch/blob/main/wolfram/lib.cpp"
    click EB "https://github.com/unum-cloud/usearch/blob/main/BENCHMARKS.md"

    %% Styles
    classDef core fill:#cce5ff,stroke:#2b6cb0,color:#1a365d,stroke-width:1px;
    classDef binding fill:#d4edda,stroke:#276749,color:#22543d,stroke-width:1px;
    classDef pipeline fill:#ffe5b4,stroke:#dd6b20,color:#7b341e,stroke-width:1px;
    classDef external fill:#f0f0f0,stroke:#4a5568,color:#2d3748,stroke-width:1px;
```
