# centamiv/vektor architecture

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

- Interactive diagram: https://gitdiagram.com/centamiv/vektor
- Repository: https://github.com/centamiv/vektor

## Overview

Vektor is an embedded PHP vector database with an optional HTTP API. In the main workflow, a client submits a vector to the API controller, which dispatches inserts to the Indexer or searches to the Searcher; the HNSW layer navigates graph connections using cosine similarity, and binary files hold vectors, graph links, ID mappings, and metadata. Delete, statistics, and vacuum optimization are separate capabilities. The README documents health and info endpoints; source excerpts show info but not health handling. Relationships shown are limited to excerpts and explicit README statements; unsampled modules are represented only where documented.

Main entry points: [`src/Services/Indexer.php`](https://github.com/centamiv/vektor/blob/develop/src/Services/Indexer.php) (Indexer), [`src/Services/Searcher.php`](https://github.com/centamiv/vektor/blob/develop/src/Services/Searcher.php) (Searcher), [`src/Services/Optimizer.php`](https://github.com/centamiv/vektor/blob/develop/src/Services/Optimizer.php) (Optimizer), [`src/Core/HnswLogic.php`](https://github.com/centamiv/vektor/blob/develop/src/Core/HnswLogic.php) (HNSW logic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_entry["HTTP entry<br/>[index.php]"]
  node_controller["API controller<br/>[Controller.php]"]
end

subgraph group_services["Database services"]
  node_indexer["Indexer<br/>[Indexer.php]"]
  node_searcher["Searcher<br/>[Searcher.php]"]
  node_optimizer["Optimizer<br/>[Optimizer.php]"]
end

subgraph group_algorithm["Search and indexing"]
  node_hnsw["HNSW logic<br/>[HnswLogic.php]"]
  node_math["Cosine math<br/>[Math.php]"]
end

subgraph group_storage["Binary storage"]
  node_vectors[("Vector file<br/>[VectorFile.php]")]
  node_graph[("Graph file<br/>[GraphFile.php]")]
  node_metadata[("Metadata index<br/>[MetaFile.php]")]
  node_payload[("Payload file<br/>[PayloadFile.php]")]
end

subgraph group_config["Configuration"]
  node_config["Config<br/>[Config.php]"]
end

node_client(("Client"))

node_client -->|"sends HTTP"| node_entry
node_entry -->|"dispatches to"| node_controller
node_controller -->|"handles writes"| node_indexer
node_controller -->|"handles search"| node_searcher
node_controller -->|"triggers vacuum"| node_optimizer
node_indexer -->|"builds links"| node_hnsw
node_searcher -->|"searches via"| node_hnsw
node_hnsw -->|"reads links"| node_graph
node_hnsw -->|"reads vectors"| node_vectors
node_hnsw -->|"scores vectors"| node_math
node_indexer -->|"appends vectors"| node_vectors
node_indexer -->|"updates graph"| node_graph
node_indexer -->|"maps IDs"| node_metadata
node_indexer -->|"stores metadata"| node_payload
node_searcher -->|"hydrates results"| node_vectors
node_searcher -->|"finds metadata"| node_metadata
node_searcher -->|"reads metadata"| node_payload
node_optimizer -->|"rebuilds records"| node_indexer
node_optimizer -->|"scans records"| node_vectors
node_optimizer -->|"replaces files"| node_graph
node_optimizer -->|"replaces files"| node_metadata
node_optimizer -->|"replaces files"| node_payload
node_indexer -->|"reads settings"| node_config
node_searcher -->|"reads settings"| node_config

click node_entry "https://github.com/centamiv/vektor/blob/develop/public/index.php"
click node_controller "https://github.com/centamiv/vektor/blob/develop/src/Api/Controller.php"
click node_config "https://github.com/centamiv/vektor/blob/develop/src/Core/Config.php"
click node_indexer "https://github.com/centamiv/vektor/blob/develop/src/Services/Indexer.php"
click node_searcher "https://github.com/centamiv/vektor/blob/develop/src/Services/Searcher.php"
click node_optimizer "https://github.com/centamiv/vektor/blob/develop/src/Services/Optimizer.php"
click node_hnsw "https://github.com/centamiv/vektor/blob/develop/src/Core/HnswLogic.php"
click node_math "https://github.com/centamiv/vektor/blob/develop/src/Core/Math.php"
click node_vectors "https://github.com/centamiv/vektor/blob/develop/src/Storage/Binary/VectorFile.php"
click node_graph "https://github.com/centamiv/vektor/blob/develop/src/Storage/Binary/GraphFile.php"
click node_metadata "https://github.com/centamiv/vektor/blob/develop/src/Storage/Binary/MetaFile.php"
click node_payload "https://github.com/centamiv/vektor/blob/develop/src/Storage/Binary/PayloadFile.php"

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_entry,node_controller,node_client toneBlue
class node_indexer,node_searcher,node_optimizer toneAmber
class node_hnsw,node_math toneMint
class node_vectors,node_graph,node_metadata,node_payload toneRose
class node_config toneIndigo
```

## Components

### HTTP API

- [HTTP entry](https://github.com/centamiv/vektor/blob/develop/public/index.php): `public/index.php`
- [API controller](https://github.com/centamiv/vektor/blob/develop/src/Api/Controller.php): `src/Api/Controller.php`

### Database services

- [Indexer](https://github.com/centamiv/vektor/blob/develop/src/Services/Indexer.php): `src/Services/Indexer.php`
- [Searcher](https://github.com/centamiv/vektor/blob/develop/src/Services/Searcher.php): `src/Services/Searcher.php`
- [Optimizer](https://github.com/centamiv/vektor/blob/develop/src/Services/Optimizer.php): `src/Services/Optimizer.php`

### Search and indexing

- [HNSW logic](https://github.com/centamiv/vektor/blob/develop/src/Core/HnswLogic.php): `src/Core/HnswLogic.php`
- [Cosine math](https://github.com/centamiv/vektor/blob/develop/src/Core/Math.php): `src/Core/Math.php`

### Binary storage

- [Vector file](https://github.com/centamiv/vektor/blob/develop/src/Storage/Binary/VectorFile.php): `src/Storage/Binary/VectorFile.php`
- [Graph file](https://github.com/centamiv/vektor/blob/develop/src/Storage/Binary/GraphFile.php): `src/Storage/Binary/GraphFile.php`
- [Metadata index](https://github.com/centamiv/vektor/blob/develop/src/Storage/Binary/MetaFile.php): `src/Storage/Binary/MetaFile.php`
- [Payload file](https://github.com/centamiv/vektor/blob/develop/src/Storage/Binary/PayloadFile.php): `src/Storage/Binary/PayloadFile.php`

### Configuration

- [Config](https://github.com/centamiv/vektor/blob/develop/src/Core/Config.php): `src/Core/Config.php`

### Other components

- **Client**

## Connections

- Client → HTTP entry: sends HTTP (evidence: `README.md`)
- HTTP entry → API controller: dispatches to (evidence: `public/index.php`)
- API controller → Indexer: handles writes (evidence: `src/Api/Controller.php`)
- API controller → Searcher: handles search (evidence: `src/Api/Controller.php`)
- API controller → Optimizer: triggers vacuum (evidence: `src/Api/Controller.php`)
- Indexer → HNSW logic: builds links (evidence: `src/Services/Indexer.php`)
- Searcher → HNSW logic: searches via (evidence: `src/Services/Searcher.php`)
- HNSW logic → Graph file: reads links (evidence: `src/Core/HnswLogic.php`)
- HNSW logic → Vector file: reads vectors (evidence: `src/Core/HnswLogic.php`)
- HNSW logic → Cosine math: scores vectors (evidence: `src/Core/HnswLogic.php`)
- Indexer → Vector file: appends vectors (evidence: `src/Services/Indexer.php`)
- Indexer → Graph file: updates graph (evidence: `src/Services/Indexer.php`)
- Indexer → Metadata index: maps IDs (evidence: `src/Services/Indexer.php`)
- Indexer → Payload file: stores metadata (evidence: `src/Services/Indexer.php`)
- Searcher → Vector file: hydrates results (evidence: `src/Services/Searcher.php`)
- Searcher → Metadata index: finds metadata (evidence: `src/Services/Searcher.php`)
- Searcher → Payload file: reads metadata (evidence: `src/Services/Searcher.php`)
- Optimizer → Indexer: rebuilds records (evidence: `src/Services/Optimizer.php`)
- Optimizer → Vector file: scans records (evidence: `src/Services/Optimizer.php`)
- Optimizer → Graph file: replaces files (evidence: `src/Services/Optimizer.php`)
- Optimizer → Metadata index: replaces files (evidence: `src/Services/Optimizer.php`)
- Optimizer → Payload file: replaces files (evidence: `src/Services/Optimizer.php`)
- Indexer → Config: reads settings (evidence: `src/Services/Indexer.php`)
- Searcher → Config: reads settings (evidence: `src/Services/Searcher.php`)
