# kwon-evan/mariadb-vector architecture

> Architecture diagram of the GitHub repository kwon-evan/mariadb-vector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kwon-evan/mariadb-vector
- Repository: https://github.com/kwon-evan/mariadb-vector

## Overview

##### Project type and purpose
- This is an open-source Python library (“MariaDB Vector”) that extends SQLAlchemy/SQLModel to support MariaDB’s VECTOR column type and vector‐based operations (distance calculations and searches).
- It acts as a plugin/adapter layer between a user’s Python ORM models and a MariaDB database with vector support.

##### File structure
- Top level: configuration (pyproject.toml, pdm.lock), GitHub workflows, README, license.
- src/mariadb_vector: the library itself, containing:
- functions.py – helpers for building SQL expressions (vec_from_seq, vec_distance, etc.)
- vector.py – a custom SQLAlchemy Column type wrapper around MariaDB’s VECTOR.

##### README for additional insights
- The README shows typical usage:
- A SQLModel table with a VECTOR column via Field(sa_column=Column(Vector(n))).
- Insert records with embedding lists.
- Query by ordering on vec_distance_* functions.
- Dependencies: SQLModel (built on SQLAlchemy), MariaDB connector/engine.

##### Elements
- Clear labels: “User App”, “MariaDB-Vector Library: Vector Type”, “MariaDB-Vector Library: Distance Functions”, “SQLModel/SQLAlchemy”, “MariaDB DB”
– App → Library (import/use)
– App → SQLModel/SQLAlchemy
– SQLModel/SQLAlchemy → MariaDB (SQL execution)
– MariaDB → SQLModel/SQLAlchemy (results) → App
– Rectangles for code components (App, Library modules, ORM)

1. USER LAYER (top)
- Python code: define Item model, call session.add, session.exec
2. ORMs & EXTENSION LAYER (middle)
- SQLModel/SQLAlchemy core
- MariaDB-Vector plugin
– Vector Type (handles Column metadata)
– Vector Functions (expr generators)
3. DATABASE LAYER (bottom)
- MariaDB Server with VECTOR column
- Underlying storage & vector search engine
- PDM/pip (dependency install)
- GitHub Actions (format.yml, release.yml)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User Layer"
        App["User Application (Python code)"]:::python
    end

    subgraph "ORM & Extension Layer"
        ORM["SQLModel / SQLAlchemy"]:::orm
        subgraph "MariaDB-Vector Library"
            LibRoot["MariaDB-Vector Library"]:::library
            LibInit["__init__.py"]:::library
            VecType["Vector Type"]:::library
            VecFuncs["Vector Functions"]:::library
        end
    end

    subgraph "Database Layer"
        DB["MariaDB Database with VECTOR support"]:::db
    end

    subgraph "Build & CI"
        Config1["pyproject.toml"]:::config
        Config2["pdm.lock"]:::config
        WFfmt[".github/workflows/format.yml"]:::config
        WFrelease[".github/workflows/release.yml"]:::config
        Readme["README.md"]:::config
        License["LICENSE"]:::config
    end

    App -->|"imports extension"| LibRoot
    App -->|"executes session operations"| ORM
    LibRoot --> LibInit
    LibRoot --> VecType
    LibRoot --> VecFuncs
    VecType -->|"integrates with ORM"| ORM
    VecFuncs -->|"integrates with ORM"| ORM
    ORM -->|"compiles SQL"| DB
    DB -->|"returns results"| ORM
    ORM -->|"maps to models"| App

    click LibRoot "https://github.com/kwon-evan/mariadb-vector/tree/main/src/mariadb_vector"
    click VecType "https://github.com/kwon-evan/mariadb-vector/blob/main/src/mariadb_vector/vector.py"
    click VecFuncs "https://github.com/kwon-evan/mariadb-vector/blob/main/src/mariadb_vector/functions.py"
    click LibInit "https://github.com/kwon-evan/mariadb-vector/blob/main/src/mariadb_vector/__init__.py"
    click Config1 "https://github.com/kwon-evan/mariadb-vector/blob/main/pyproject.toml"
    click Config2 "https://github.com/kwon-evan/mariadb-vector/blob/main/pdm.lock"
    click WFfmt "https://github.com/kwon-evan/mariadb-vector/blob/main/.github/workflows/format.yml"
    click WFrelease "https://github.com/kwon-evan/mariadb-vector/blob/main/.github/workflows/release.yml"
    click Readme "https://github.com/kwon-evan/mariadb-vector/blob/main/README.md"
    click License "https://github.com/kwon-evan/mariadb-vector/tree/main/LICENSE"

    classDef python fill:#D0E6FB,stroke:#0366D6,color:#0366D6;
    classDef library fill:#E8F4FC,stroke:#1B82D1,color:#1B82D1;
    classDef orm fill:#E6F9E6,stroke:#2C9E2C,color:#2C9E2C;
    classDef db fill:#FFF4E5,stroke:#E69100,color:#E69100;
    classDef config fill:#F0F0F0,stroke:#666666,color:#333333;
```
