# tylerpuig/tinyvec architecture

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

- Interactive diagram: https://gitdiagram.com/tylerpuig/tinyvec
- Repository: https://github.com/tylerpuig/tinyvec

## Overview

##### Main System Components
- Core Engine (C Core): This is in the “src/core” directory and also found (as a duplicated version) in the bindings directories; it includes modules like cJSON, db, distance, file, and minheap. This engine encapsulates the primary vector storage, similarity computation, and file I/O for persistence.
- Language Bindings:
– Node.js/JavaScript Binding: Found under “bindings/nodejs”. This layer adapts the C core for use in JavaScript, featuring a native addon (C++ wrapper) and associated TypeScript definitions and tests.
– Python Binding: Found under “bindings/python”. This binding similarly wraps the C core and provides a Pythonic API for connecting, inserting, searching, and obtaining statistics.
- Client Applications: Where user code integrates TinyVecDB via one of the bindings. The README examples (both for TypeScript/JavaScript and Python) illustrate how client code interacts with the bindings.
- Database Storage Layer: Although not a dedicated module, it is important to note that TinyVecDB works “embedded” – storing its data files on the filesystem, which the core engine manages (see the “automatic file creation” note).

##### Out Relationships and Interactions
- Client Applications at the top, with separate branches for Node.js and Python clients.
- Link the C core engine with the Database Storage (file system), explaining how it reads/writes the vector data and configuration files.
- Optionally, include components for testing (unit tests and benchmarks) as supporting elements that interact with both the bindings and core.

##### Important Architectural Patterns and Design Principles
- Embedded System: Emphasize that the system is self-contained—no separate server processes are involved.
- Layered Architecture: Illustrate a clear separation between the C core (business logic) and the language-specific bindings (API adapters).
- Modularity: Within the C core, identify key modules (like file I/O, distance calculations, and memory management via minheap) that are independently maintained.
- Cross-Platform Capability: Indicate support for multiple environments (Windows, macOS, Linux) through lightweight and portable design.
- Performance and Efficiency: Annotate that the C core engine is optimized for speed and minimal memory footprint, which is critical for serving embedded vector search operations.

##### Incorporate Relevant Technologies and Frameworks
- C Programming Language and associated libraries (cJSON, etc.) for the Core Engine.
- Node.js, TypeScript/JavaScript, and their native addon system (binding.gyp, etc.) for the Node.js Binding.
- Python along with setuptools/pyproject for the Python Binding.
- Testing tools (Jest for Node.js, pytest or custom tests in Python) and benchmarking scripts found in the “benchmarks” directories.

- Components: Client Application, Language Bindings (Node.js and Python), C Core Engine, and Database Storage.
- Labels and Notes: Use labels next to each module that indicate cross-platform support, embedded operation, or performance optimizations.

Happy designing!

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Applications"
        JSClient["JavaScript/TypeScript Client"]:::client
        PythonClient["Python Client"]:::client
    end

    subgraph "Language Bindings"
        NodeBinding["Node.js/JavaScript Binding"]:::binding
        PythonBinding["Python Binding"]:::binding
    end

    CCore["C Core Engine<br/>(cJSON, db, distance, file, minheap)"]:::core

    Storage["Database Storage (File I/O)"]:::storage

    JSClient -->|"calls"| NodeBinding
    PythonClient -->|"calls"| PythonBinding

    NodeBinding -->|"invokes"| CCore
    PythonBinding -->|"invokes"| CCore

    CCore -->|"reads/writes"| Storage

    click CCore "https://github.com/tylerpuig/tinyvec/tree/main/src/core"
    click NodeBinding "https://github.com/tylerpuig/tinyvec/tree/main/bindings/nodejs"
    click PythonBinding "https://github.com/tylerpuig/tinyvec/tree/main/bindings/python"
    click Storage "https://github.com/tylerpuig/tinyvec/blob/main/src/core/src/file.c"

    classDef client fill:#D9EAD3,stroke:#6AA84F,stroke-width:2px;
    classDef binding fill:#CFE2F3,stroke:#3C78D8,stroke-width:2px;
    classDef core fill:#FFF2CC,stroke:#E69138,stroke-width:2px;
    classDef storage fill:#F4CCCC,stroke:#CC0000,stroke-width:2px;
```
