Architecture

VortexDB is a high-performance vector database built in Rust, designed with modularity and flexibility at its core.

Crate Structure

VortexDB is organized as a Rust workspace with the following crates:

Crate	Purpose
`server`	Main entry point, configuration, server startup
`api`	Core database logic and error handling
`grpc`	Protocol Buffers definitions and gRPC service
`http`	REST API handlers using Axum
`index`	Vector indexing algorithms (Flat, KD-Tree, HNSW)
`storage`	Persistence backends (InMemory, RocksDB)
`snapshot`	Point-in-time backup and restore
`defs`	Shared type definitions
`tui`	Terminal user interface

Transport Layers

VortexDB exposes two APIs that share the same underlying database:

gRPC API

The gRPC layer is the primary high-performance interface:

Protocol: HTTP/2 with Protocol Buffers
Port: 50051 (default)
Authentication: API key via authorization header
Use cases: Production workloads, SDKs, high-throughput scenarios

service VectorDB {
  rpc InsertVector(InsertVectorRequest) returns (PointID);
  rpc DeletePoint(PointID) returns (google.protobuf.Empty);
  rpc GetPoint(PointID) returns (Point);
  rpc SearchPoints(SearchRequest) returns (SearchResponse);
}

HTTP API

The HTTP layer provides a RESTful interface:

Protocol: HTTP/1.1 with JSON
Port: 3000 (default)
Authentication: None (designed for internal/trusted networks)
Use cases: Quick testing, curl commands, prototyping

Method	Endpoint	Description
`GET`	`/`	Root endpoint
`GET`	`/health`	Health check
`POST`	`/points`	Insert a point
`GET`	`/points/:id`	Get a point by ID
`DELETE`	`/points/:id`	Delete a point
`POST`	`/points/search`	Search for similar vectors

When to Use Which?

Use gRPC when...
Use HTTP when...

Building production applications
Using the Python SDK (it uses gRPC)
Need authentication
Processing high volumes of requests
Want strongly-typed client libraries

Storage Layer

The storage layer persists vectors and their payloads using a trait-based design:

pub trait StorageEngine: Send + Sync {
    fn insert(&self, vector: DenseVector, payload: Payload) -> Result<PointId>;
    fn get(&self, point_id: PointId) -> Result<Option<Point>>;
    fn delete(&self, point_id: PointId) -> Result<bool>;
    fn checkpoint_at(&self, path: &Path) -> Result<StorageCheckpoint>;
    fn restore_checkpoint(&mut self, checkpoint: &StorageCheckpoint) -> Result<()>;
}

Available Backends

Backend	Description	Use Case
InMemory	Stores data in RAM	Development, testing, ephemeral workloads
RocksDB	LSM-tree persistent storage	Production deployments

Set the backend via the STORAGE_TYPE environment variable:

STORAGE_TYPE=rocksdb  # or 'inmemory'

Index Layer

The index layer provides fast similarity search. See Indexers for details on choosing the right index.

pub trait VectorIndex: Send + Sync {
    fn insert(&mut self, vector: IndexedVector) -> Result<()>;
    fn delete(&mut self, point_id: PointId) -> Result<bool>;
    fn search(&self, query: DenseVector, similarity: Similarity, k: usize) -> Result<Vec<PointId>>;
}

Data Flow

Here’s what happens when you insert a vector:

Client Request

Client sends insert request via gRPC or HTTP

Validation

Server validates vector dimensions match configuration

Storage Write

Vector and payload are persisted to the storage backend

Index Update

Vector is added to the index for fast searching

Response

Server returns the generated point ID to client

Configuration

VortexDB is configured via environment variables:

Variable	Required	Default	Description
`GRPC_ROOT_PASSWORD`	Yes	-	Authentication password for gRPC
`DIMENSION`	Yes	-	Vector dimensionality
`DATA_PATH`	No	system temp dir	Directory for persistent storage
`HTTP_HOST`	No	`127.0.0.1`	HTTP server bind address
`HTTP_PORT`	No	`3000`	HTTP server port
`GRPC_HOST`	No	`127.0.0.1`	gRPC server bind address
`GRPC_PORT`	No	`50051`	gRPC server port
`STORAGE_TYPE`	No	`inmemory`	Storage backend: `inmemory` or `rocksdb`
`INDEX_TYPE`	No	`flat`	Index algorithm: `flat`, `kdtree`, or `hnsw`
`SIMILARITY`	No	`cosine`	Default metric: `cosine`, `euclidean`, `manhattan`, or `hamming`
`LOGGING`	No	`true`	Enable logging
`DISABLE_HTTP`	No	`false`	Run gRPC only
`HNSW_M`	No	`16`	HNSW max connections per layer
`HNSW_M0`	No	`2 * HNSW_M`	HNSW max connections for layer 0
`HNSW_EF_CONSTRUCTION`	No	`200`	HNSW search breadth during construction
`HNSW_EF`	No	`100`	HNSW default search breadth at query time

Thread Safety

VortexDB is designed for concurrent access:

The storage layer uses Arc for thread-safe reference counting
The index layer uses RwLock for concurrent reads with exclusive writes
Both gRPC and HTTP handlers are fully async using Tokio

Next Steps

Indexers

Learn about index algorithms and when to use each

Snapshots

Understand backup and restore mechanisms

Getting Started

Concepts

Architecture

Architecture

Crate Structure

Transport Layers

gRPC API

HTTP API

When to Use Which?

Storage Layer

Available Backends

Index Layer

Data Flow

Configuration

Thread Safety

Next Steps

Indexers

Snapshots

​Architecture

​Crate Structure

​Transport Layers

​gRPC API

​HTTP API

​When to Use Which?

​Storage Layer

​Available Backends

​Index Layer

​Data Flow

​Configuration

​Thread Safety

​Next Steps

Indexers

Snapshots

Architecture

Crate Structure

Transport Layers

gRPC API

HTTP API

When to Use Which?

Storage Layer

Available Backends

Index Layer

Data Flow

Configuration

Thread Safety

Next Steps