# dblalock/bolt architecture

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

- Interactive diagram: https://gitdiagram.com/dblalock/bolt
- Repository: https://github.com/dblalock/bolt

## Overview

Step 2. Identify files and enumerate functions.

Step 4. Use proper visual cues.

Step 5. Tools and automation.
- For C++, Doxygen (with “EXTRACT_ALL” enabled and “CALL_GRAPH” set to YES in the configuration) along with Graphviz will emit call graphs showing which functions call which.
- For Python, specialized tools (such as pycallgraph) can help generate similar function–level call graphs.
- Combining these tools with manual annotation ensures you capture both automated dependency information and any design decisions that you want to emphasize.

A sample (simplified) textual sketch would be:

┌────────────────────────────────────────────┐
│       bolt_api.py (Python wrapper)         │
│--------------------------------------------  │
│ + __init__()                               │
│ + fit()                                    │
│ + transform()  ────► calls bolt_native()     │
│ + knn()      ────► calls transform()         │
└────────────────────────────────────────────┘
│           ▲
│           │ (SWIG)
▼           │
┌─────────────────────────────┐      ┌─────────────────────────────┐
│   bolt_native.cpp (C++)     │─────►│  quantize/mithral.cpp       │
│-----------------------------│      │-----------------------------│
│ BoltEncoder::BoltEncoder()  │      │ + encode()                  │
│ BoltEncoder::fit()          │      │ + transform_block()         │
│ BoltEncoder::nativeCall()   │      │  ...                      │
└─────────────────────────────┘      └─────────────────────────────┘

- Of functions within each file

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Python Wrapper API (bolt_api.py)
    subgraph "Python Wrapper API"
        p1["__init__()"]
        p2["fit()"]
        p3["transform()"]
        p4["knn()"]
    end
    click p1 "https://github.com/dblalock/bolt/blob/master/python/bolt/bolt_api.py"

    %% C++ Bolt Quantization (bolt.cpp and bolt.hpp)
    subgraph "C++ Bolt Quantization"
        b1["BoltEncoder::BoltEncoder()"]
        b2["BoltEncoder::fit()"]
        b3["BoltEncoder::nativeCall()"]
        bh["Bolt Header"]
    end
    click b1 "https://github.com/dblalock/bolt/blob/master/cpp/src/quantize/bolt.cpp"
    click bh "https://github.com/dblalock/bolt/blob/master/cpp/src/quantize/bolt.hpp"

    %% C++ Mithral Quantization (mithral.cpp, mithral.hpp, mithral_v1.hpp)
    subgraph "C++ Mithral Quantization"
        c1["encode()"]
        c2["transform_block()"]
        ch["Mithral Header"]
        ch_v1["Mithral Header v1"]
    end
    click c1 "https://github.com/dblalock/bolt/blob/master/cpp/src/quantize/mithral.cpp"
    click ch "https://github.com/dblalock/bolt/blob/master/cpp/src/quantize/mithral.hpp"
    click ch_v1 "https://github.com/dblalock/bolt/blob/master/cpp/src/quantize/mithral_v1.hpp"

    %% Additional Quantization Components
    subgraph "Additional Quantization Components"
        d1["Multi-Codebook Quantizer"]
        d2["Product Quantizer"]
    end
    click d1 "https://github.com/dblalock/bolt/blob/master/cpp/src/quantize/multi_codebook.hpp"
    click d2 "https://github.com/dblalock/bolt/blob/master/cpp/src/quantize/product_quantize.hpp"

    %% Supporting Utilities
    subgraph "Supporting Utilities"
        u1["Eigen Utils"]
        u2["NN Utils"]
        u3["Timing Utils"]
    end
    click u1 "https://github.com/dblalock/bolt/blob/master/cpp/src/utils/eigen_utils.hpp"
    click u2 "https://github.com/dblalock/bolt/blob/master/cpp/src/utils/nn_utils.hpp"
    click u3 "https://github.com/dblalock/bolt/blob/master/cpp/src/utils/timing_utils.hpp"

    %% C++ Testing
    subgraph "C++ Testing"
        t1["C++ Tests"]
    end
    click t1 "https://github.com/dblalock/bolt/tree/master/cpp/test/"

    %% Python Testing
    subgraph "Python Testing"
        t2["Python Tests"]
    end
    click t2 "https://github.com/dblalock/bolt/tree/master/tests/"

    %% Dependencies between functions
    p3 -->|"calls"| b3
    p4 -->|"calls"| p3

    b3 -->|"calls"| c1
    b3 -->|"calls"| c2
    b3 -->|"calls"| d1
    b3 -->|"calls"| d2
    b3 -->|"calls"| u3

    t1 -->|"tests"| b2
    t2 -->|"tests"| p3

    %% Styles
    classDef python fill:#cce5ff,stroke:#0056b3,stroke-width:2px
    class p1,p2,p3,p4 python

    classDef cpp fill:#f8d7da,stroke:#a71d2a,stroke-width:2px
    class b1,b2,b3,bh,c1,c2,ch,ch_v1 cpp

    classDef quant fill:#fff3cd,stroke:#856404,stroke-width:2px
    class d1,d2 quant

    classDef utils fill:#d4edda,stroke:#155724,stroke-width:2px
    class u1,u2,u3 utils

    classDef test fill:#e2e3e5,stroke:#6c757d,stroke-width:2px
    class t1,t2 test
```
