# omerfeyzioglu/glider architecture

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

- Interactive diagram: https://gitdiagram.com/omerfeyzioglu/glider
- Repository: https://github.com/omerfeyzioglu/glider

## Overview

Glider is a single-node vector database whose acknowledged writes are durable in object storage. The principal workflow is: an API client creates a collection, writes vectors and metadata, then queries nearest neighbors with optional filters; the server routes work through admission to the segmented engine, which publishes durable state and serves results from stored blocks. Distinct capabilities include collection management, optional text embedding, clustered ANN maintenance, crash recovery, and agent memory. Relationships use README statements and visible imports; unsampled implementations are represented only where their subsystem is documented.

Main entry points: [`src/segmented.rs`](https://github.com/omerfeyzioglu/glider/blob/main/src/segmented.rs) (Segmented database), [`src/server/http.rs`](https://github.com/omerfeyzioglu/glider/blob/main/src/server/http.rs) (HTTP API), [`src/store.rs`](https://github.com/omerfeyzioglu/glider/blob/main/src/store.rs) (Object store interface), [`src/admission.rs`](https://github.com/omerfeyzioglu/glider/blob/main/src/admission.rs) (Write admission)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and clients"]
  node_python["Python client<br/>[client.py]"]
  node_mcp["MCP memory server<br/>[mcp_server.py]"]
end

subgraph group_service["Server services"]
  node_http["HTTP API<br/>[http.rs]"]
  node_catalog["Collection catalog<br/>[catalog.rs]"]
  node_multi["Multi-collection service<br/>[multi.rs]"]
  node_embedding["Text embedding<br/>[embedding.rs]"]
end

subgraph group_engine["Vector engine"]
  node_admission["Write admission<br/>[admission.rs]"]
  node_segmented["Segmented database<br/>[segmented.rs]"]
  node_filters["Metadata filters<br/>[filter.rs]"]
  node_cluster["Clustered ANN<br/>[clustered.rs]"]
  node_convert["Cluster conversion<br/>[convert.rs]"]
  node_sketch["Block routing sketches<br/>[sketch.rs]"]
  node_serving["Segment serving<br/>[serving.rs]"]
  node_cache["SSD block cache<br/>[cache.rs]"]
end

subgraph group_durability["Durability and storage"]
  node_retry["Retry outcomes<br/>[retry.rs]"]
  node_lease["Writer lease<br/>[lease.rs]"]
  node_recovery["Recovery<br/>[recovery.rs]"]
  node_store["Object store interface<br/>[store.rs]"]
  node_s3["S3-compatible store<br/>[s3.rs]"]
end

subgraph group_operations["Operations"]
  node_admin["Backup and restore CLI<br/>[glider-admin.rs]"]
end

node_user(("API user"))
node_objects[("S3-compatible storage")]
node_provider(("Embedding provider"))
node_agent(("AI agent"))

node_user -->|"uses client"| node_python
node_user -->|"calls API"| node_http
node_python -->|"sends requests"| node_http
node_agent -->|"invokes tools"| node_mcp
node_mcp -->|"uses client"| node_python
node_http -->|"serves collections"| node_catalog
node_http -->|"routes embedding"| node_embedding
node_provider -.->|"provides vectors"| node_embedding
node_http -->|"submits work"| node_admission
node_catalog -->|"opens collections"| node_segmented
node_multi -.->|"manages collections"| node_segmented
node_admission -->|"commits writes"| node_segmented
node_admission -->|"tracks outcomes"| node_retry
node_segmented -->|"records outcomes"| node_retry
node_segmented -->|"reads and publishes"| node_store
node_segmented -.->|"applies filters"| node_filters
node_segmented -.->|"routes queries"| node_cluster
node_segmented -->|"starts conversion"| node_convert
node_segmented -->|"routes blocks"| node_sketch
node_segmented -.->|"serves queries"| node_serving
node_serving -.->|"uses cache"| node_cache
node_segmented -->|"coordinates takeover"| node_lease
node_lease -->|"fences writer"| node_store
node_recovery -.->|"replays state"| node_store
node_store -->|"implemented by"| node_s3
node_s3 -->|"reads and writes"| node_objects
node_admin -.->|"backs up and restores"| node_store

click node_python "https://github.com/omerfeyzioglu/glider/blob/main/clients/python/glider_client/client.py"
click node_mcp "https://github.com/omerfeyzioglu/glider/blob/main/clients/python/glider_client/mcp_server.py"
click node_http "https://github.com/omerfeyzioglu/glider/blob/main/src/server/http.rs"
click node_catalog "https://github.com/omerfeyzioglu/glider/blob/main/src/server/catalog.rs"
click node_multi "https://github.com/omerfeyzioglu/glider/blob/main/src/server/multi.rs"
click node_embedding "https://github.com/omerfeyzioglu/glider/blob/main/src/server/embedding.rs"
click node_admission "https://github.com/omerfeyzioglu/glider/blob/main/src/admission.rs"
click node_segmented "https://github.com/omerfeyzioglu/glider/blob/main/src/segmented.rs"
click node_filters "https://github.com/omerfeyzioglu/glider/blob/main/src/filter.rs"
click node_cluster "https://github.com/omerfeyzioglu/glider/blob/main/src/segmented/clustered.rs"
click node_convert "https://github.com/omerfeyzioglu/glider/blob/main/src/segmented/convert.rs"
click node_sketch "https://github.com/omerfeyzioglu/glider/blob/main/src/segmented/sketch.rs"
click node_serving "https://github.com/omerfeyzioglu/glider/blob/main/src/segmented/serving.rs"
click node_cache "https://github.com/omerfeyzioglu/glider/blob/main/src/segmented/cache.rs"
click node_retry "https://github.com/omerfeyzioglu/glider/blob/main/src/retry.rs"
click node_lease "https://github.com/omerfeyzioglu/glider/blob/main/src/lease.rs"
click node_recovery "https://github.com/omerfeyzioglu/glider/blob/main/src/recovery.rs"
click node_store "https://github.com/omerfeyzioglu/glider/blob/main/src/store.rs"
click node_s3 "https://github.com/omerfeyzioglu/glider/blob/main/src/store/s3.rs"
click node_admin "https://github.com/omerfeyzioglu/glider/blob/main/src/bin/glider-admin.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_python,node_mcp,node_user toneBlue
class node_http,node_catalog,node_multi,node_embedding,node_objects toneAmber
class node_admission,node_segmented,node_filters,node_cluster,node_convert,node_sketch,node_serving,node_cache toneMint
class node_retry,node_lease,node_recovery,node_store,node_s3 toneRose
class node_admin,node_provider,node_agent toneIndigo
```

## Components

### API and clients

- [Python client](https://github.com/omerfeyzioglu/glider/blob/main/clients/python/glider_client/client.py): `clients/python/glider_client/client.py`
- [MCP memory server](https://github.com/omerfeyzioglu/glider/blob/main/clients/python/glider_client/mcp_server.py): `clients/python/glider_client/mcp_server.py`

### Server services

- [HTTP API](https://github.com/omerfeyzioglu/glider/blob/main/src/server/http.rs): `src/server/http.rs`
- [Collection catalog](https://github.com/omerfeyzioglu/glider/blob/main/src/server/catalog.rs): `src/server/catalog.rs`
- [Multi-collection service](https://github.com/omerfeyzioglu/glider/blob/main/src/server/multi.rs): `src/server/multi.rs`
- [Text embedding](https://github.com/omerfeyzioglu/glider/blob/main/src/server/embedding.rs): `src/server/embedding.rs`

### Vector engine

- [Write admission](https://github.com/omerfeyzioglu/glider/blob/main/src/admission.rs): `src/admission.rs`
- [Segmented database](https://github.com/omerfeyzioglu/glider/blob/main/src/segmented.rs): `src/segmented.rs`
- [Metadata filters](https://github.com/omerfeyzioglu/glider/blob/main/src/filter.rs): `src/filter.rs`
- [Clustered ANN](https://github.com/omerfeyzioglu/glider/blob/main/src/segmented/clustered.rs): `src/segmented/clustered.rs`
- [Cluster conversion](https://github.com/omerfeyzioglu/glider/blob/main/src/segmented/convert.rs): `src/segmented/convert.rs`
- [Block routing sketches](https://github.com/omerfeyzioglu/glider/blob/main/src/segmented/sketch.rs): `src/segmented/sketch.rs`
- [Segment serving](https://github.com/omerfeyzioglu/glider/blob/main/src/segmented/serving.rs): `src/segmented/serving.rs`
- [SSD block cache](https://github.com/omerfeyzioglu/glider/blob/main/src/segmented/cache.rs): `src/segmented/cache.rs`

### Durability and storage

- [Retry outcomes](https://github.com/omerfeyzioglu/glider/blob/main/src/retry.rs): `src/retry.rs`
- [Writer lease](https://github.com/omerfeyzioglu/glider/blob/main/src/lease.rs): `src/lease.rs`
- [Recovery](https://github.com/omerfeyzioglu/glider/blob/main/src/recovery.rs): `src/recovery.rs`
- [Object store interface](https://github.com/omerfeyzioglu/glider/blob/main/src/store.rs): `src/store.rs`
- [S3-compatible store](https://github.com/omerfeyzioglu/glider/blob/main/src/store/s3.rs): `src/store/s3.rs`

### Operations

- [Backup and restore CLI](https://github.com/omerfeyzioglu/glider/blob/main/src/bin/glider-admin.rs): `src/bin/glider-admin.rs`

### Other components

- **API user**
- **S3-compatible storage**
- **Embedding provider**
- **AI agent**

## Connections

- API user → Python client: uses client (evidence: `README.md`)
- API user → HTTP API: calls API (evidence: `README.md`)
- Python client → HTTP API: sends requests (evidence: `README.md`)
- AI agent → MCP memory server: invokes tools (evidence: `README.md`)
- MCP memory server → Python client: uses client (evidence: `clients/python/glider_client/mcp_server.py`)
- HTTP API → Collection catalog: serves collections (evidence: `src/server/mod.rs`)
- HTTP API → Text embedding: routes embedding (evidence: `src/server/http.rs`)
- Embedding provider → Text embedding: provides vectors (evidence: `README.md`)
- HTTP API → Write admission: submits work
- Collection catalog → Segmented database: opens collections (evidence: `src/server/catalog.rs`)
- Multi-collection service → Segmented database: manages collections
- Write admission → Segmented database: commits writes (evidence: `src/admission.rs`)
- Write admission → Retry outcomes: tracks outcomes (evidence: `src/admission.rs`)
- Segmented database → Retry outcomes: records outcomes (evidence: `src/segmented.rs`)
- Segmented database → Object store interface: reads and publishes (evidence: `src/segmented.rs`)
- Segmented database → Metadata filters: applies filters
- Segmented database → Clustered ANN: routes queries (evidence: `src/segmented.rs`)
- Segmented database → Cluster conversion: starts conversion (evidence: `src/segmented/convert.rs`)
- Segmented database → Block routing sketches: routes blocks (evidence: `src/segmented/sketch.rs`)
- Segmented database → Segment serving: serves queries (evidence: `src/segmented.rs`)
- Segment serving → SSD block cache: uses cache
- Segmented database → Writer lease: coordinates takeover (evidence: `src/segmented.rs`)
- Writer lease → Object store interface: fences writer (evidence: `src/lease.rs`)
- Recovery → Object store interface: replays state
- Object store interface → S3-compatible store: implemented by (evidence: `src/store.rs`)
- S3-compatible store → S3-compatible storage: reads and writes (evidence: `src/store/s3.rs`)
- Backup and restore CLI → Object store interface: backs up and restores (evidence: `README.md`)
