# shankarbkori/vectordb architecture

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

- Interactive diagram: https://gitdiagram.com/shankarbkori/vectordb
- Repository: https://github.com/shankarbkori/vectordb

## Overview

VectorDB is an in-memory vector search service with two user-facing paths: direct vector operations and document-based retrieval-augmented generation (RAG). Document ingestion chunks text, obtains embeddings from local Ollama, and stores chunks for retrieval; question answering embeds a query, retrieves relevant chunks, and uses Ollama generation. Direct vector requests use a unified database that maintains multiple search indexes. The README also documents HNSW, KD-tree, brute-force search, distance metrics, and benchmark capabilities. Relationships for unsampled source are included only where the README or source index supports them.

Main entry points: [`vectordb/src/main/java/com/vectordb/db/VectorDB.java`](https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/db/VectorDB.java) (Vector Store), [`vectordb/src/main/java/com/vectordb/db/DocumentDB.java`](https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/db/DocumentDB.java) (Document Store), [`vectordb/src/main/java/com/vectordb/api/DocumentController.java`](https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/api/DocumentController.java) (Document API), [`vectordb/src/main/java/com/vectordb/distance/DistanceFunctions.java`](https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/distance/DistanceFunctions.java) (Distance Metrics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST API"]
  node_demo_api["Vector API"]
  node_document_api["Document API"]
  node_app["Application Startup"]
end

subgraph group_rag["Document RAG"]
  node_chunker["Text Chunker<br/>[TextChunker.java]"]
  node_ollama_client["Ollama Client<br/>[OllamaClient.java]"]
end

subgraph group_storage["Vector Storage"]
  node_document_db[("Document Store<br/>[DocumentDB.java]")]
  node_vector_db[("Vector Store<br/>[VectorDB.java]")]
  node_demo_loader["Demo Loader<br/>[DemoLoader.java]"]
end

subgraph group_search["Search Engines"]
  node_hnsw["HNSW Index<br/>[HNSW.java]"]
  node_kdtree["KD-Tree Index<br/>[KDTree.java]"]
  node_bruteforce["Brute-Force Index<br/>[BruteForce.java]"]
end

subgraph group_core["Shared Core"]
  node_distance["Distance Metrics"]
  node_vector_item["Vector Record<br/>[VectorItem.java]"]
  node_doc_item["Document Chunk<br/>[DocItem.java]"]
  node_search_result["Search Result<br/>[SearchResult.java]"]
end

node_client(("API Client"))
node_ollama_service["Ollama Service"]

node_client -->|"calls endpoints"| node_demo_api
node_client -->|"calls endpoints"| node_document_api
node_document_api -->|"chunks text"| node_chunker
node_document_api -->|"requests embeddings"| node_ollama_client
node_document_api -->|"requests generation"| node_ollama_client
node_document_api -->|"stores and searches"| node_document_db
node_document_api -->|"reads demo status"| node_vector_db
node_ollama_client -->|"sends HTTP requests"| node_ollama_service
node_demo_api -->|"inserts and searches"| node_vector_db
node_app -->|"loads demo data"| node_demo_loader
node_demo_loader -->|"populates vectors"| node_vector_db
node_document_db -->|"indexes chunks"| node_hnsw
node_document_db -->|"indexes chunks"| node_bruteforce
node_document_db -->|"scores queries"| node_distance
node_document_db -->|"stores chunks"| node_doc_item
node_document_db -->|"creates index records"| node_vector_item
node_document_db -->|"maps search hits"| node_search_result
node_vector_db -->|"maintains and queries"| node_bruteforce
node_vector_db -->|"maintains and queries"| node_kdtree
node_vector_db -->|"maintains and queries"| node_hnsw
node_vector_db -->|"selects metric"| node_distance
node_vector_db -->|"stores records"| node_vector_item
node_vector_db -->|"maps index hits"| node_search_result
node_bruteforce -->|"computes distances"| node_distance
node_bruteforce -->|"returns ranked hits"| node_search_result
node_hnsw -->|"computes distances"| node_distance
node_hnsw -->|"returns ranked hits"| node_search_result
node_kdtree -->|"computes distances"| node_distance
node_kdtree -->|"returns ranked hits"| node_search_result

click node_demo_api "https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/api/DemoVectorController.java"
click node_document_api "https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/api/DocumentController.java"
click node_app "https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/VectorDbApplication.java"
click node_chunker "https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/util/TextChunker.java"
click node_ollama_client "https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/ollama/OllamaClient.java"
click node_document_db "https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/db/DocumentDB.java"
click node_vector_db "https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/db/VectorDB.java"
click node_demo_loader "https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/util/DemoLoader.java"
click node_hnsw "https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/search/HNSW.java"
click node_kdtree "https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/search/KDTree.java"
click node_bruteforce "https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/search/BruteForce.java"
click node_distance "https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/distance/DistanceFunctions.java"
click node_vector_item "https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/model/VectorItem.java"
click node_doc_item "https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/model/DocItem.java"
click node_search_result "https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/search/SearchResult.java"

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_demo_api,node_document_api,node_app,node_client toneBlue
class node_chunker,node_ollama_client toneAmber
class node_document_db,node_vector_db,node_demo_loader toneMint
class node_hnsw,node_kdtree,node_bruteforce toneRose
class node_distance,node_vector_item,node_doc_item,node_search_result,node_ollama_service toneIndigo
```

## Components

### REST API

- [Vector API](https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/api/DemoVectorController.java): `vectordb/src/main/java/com/vectordb/api/DemoVectorController.java`
- [Document API](https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/api/DocumentController.java): `vectordb/src/main/java/com/vectordb/api/DocumentController.java`
- [Application Startup](https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/VectorDbApplication.java): `vectordb/src/main/java/com/vectordb/VectorDbApplication.java`

### Document RAG

- [Text Chunker](https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/util/TextChunker.java): `vectordb/src/main/java/com/vectordb/util/TextChunker.java`
- [Ollama Client](https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/ollama/OllamaClient.java): `vectordb/src/main/java/com/vectordb/ollama/OllamaClient.java`

### Vector Storage

- [Document Store](https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/db/DocumentDB.java): `vectordb/src/main/java/com/vectordb/db/DocumentDB.java`
- [Vector Store](https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/db/VectorDB.java): `vectordb/src/main/java/com/vectordb/db/VectorDB.java`
- [Demo Loader](https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/util/DemoLoader.java): `vectordb/src/main/java/com/vectordb/util/DemoLoader.java`

### Search Engines

- [HNSW Index](https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/search/HNSW.java): `vectordb/src/main/java/com/vectordb/search/HNSW.java`
- [KD-Tree Index](https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/search/KDTree.java): `vectordb/src/main/java/com/vectordb/search/KDTree.java`
- [Brute-Force Index](https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/search/BruteForce.java): `vectordb/src/main/java/com/vectordb/search/BruteForce.java`

### Shared Core

- [Distance Metrics](https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/distance/DistanceFunctions.java): `vectordb/src/main/java/com/vectordb/distance/DistanceFunctions.java`
- [Vector Record](https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/model/VectorItem.java): `vectordb/src/main/java/com/vectordb/model/VectorItem.java`
- [Document Chunk](https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/model/DocItem.java): `vectordb/src/main/java/com/vectordb/model/DocItem.java`
- [Search Result](https://github.com/shankarbkori/vectordb/blob/main/vectordb/src/main/java/com/vectordb/search/SearchResult.java): `vectordb/src/main/java/com/vectordb/search/SearchResult.java`

### Other components

- **API Client**
- **Ollama Service**

## Connections

- API Client → Vector API: calls endpoints (evidence: `README.md`)
- API Client → Document API: calls endpoints (evidence: `README.md`)
- Document API → Text Chunker: chunks text (evidence: `vectordb/src/main/java/com/vectordb/api/DocumentController.java`)
- Document API → Ollama Client: requests embeddings (evidence: `vectordb/src/main/java/com/vectordb/api/DocumentController.java`)
- Document API → Ollama Client: requests generation (evidence: `vectordb/src/main/java/com/vectordb/api/DocumentController.java`)
- Document API → Document Store: stores and searches (evidence: `vectordb/src/main/java/com/vectordb/api/DocumentController.java`)
- Document API → Vector Store: reads demo status (evidence: `vectordb/src/main/java/com/vectordb/api/DocumentController.java`)
- Ollama Client → Ollama Service: sends HTTP requests (evidence: `vectordb/src/main/java/com/vectordb/ollama/OllamaClient.java`)
- Vector API → Vector Store: inserts and searches (evidence: `vectordb/src/main/java/com/vectordb/api/DemoVectorController.java`)
- Application Startup → Demo Loader: loads demo data (evidence: `vectordb/src/main/java/com/vectordb/VectorDbApplication.java`)
- Demo Loader → Vector Store: populates vectors (evidence: `vectordb/src/main/java/com/vectordb/util/DemoLoader.java`)
- Document Store → HNSW Index: indexes chunks (evidence: `vectordb/src/main/java/com/vectordb/db/DocumentDB.java`)
- Document Store → Brute-Force Index: indexes chunks (evidence: `vectordb/src/main/java/com/vectordb/db/DocumentDB.java`)
- Document Store → Distance Metrics: scores queries (evidence: `vectordb/src/main/java/com/vectordb/db/DocumentDB.java`)
- Document Store → Document Chunk: stores chunks (evidence: `vectordb/src/main/java/com/vectordb/db/DocumentDB.java`)
- Document Store → Vector Record: creates index records (evidence: `vectordb/src/main/java/com/vectordb/db/DocumentDB.java`)
- Document Store → Search Result: maps search hits (evidence: `vectordb/src/main/java/com/vectordb/db/DocumentDB.java`)
- Vector Store → Brute-Force Index: maintains and queries (evidence: `vectordb/src/main/java/com/vectordb/db/VectorDB.java`)
- Vector Store → KD-Tree Index: maintains and queries (evidence: `vectordb/src/main/java/com/vectordb/db/VectorDB.java`)
- Vector Store → HNSW Index: maintains and queries (evidence: `vectordb/src/main/java/com/vectordb/db/VectorDB.java`)
- Vector Store → Distance Metrics: selects metric (evidence: `vectordb/src/main/java/com/vectordb/db/VectorDB.java`)
- Vector Store → Vector Record: stores records (evidence: `vectordb/src/main/java/com/vectordb/db/VectorDB.java`)
- Vector Store → Search Result: maps index hits (evidence: `vectordb/src/main/java/com/vectordb/db/VectorDB.java`)
- Brute-Force Index → Distance Metrics: computes distances (evidence: `vectordb/src/main/java/com/vectordb/search/BruteForce.java`)
- Brute-Force Index → Search Result: returns ranked hits (evidence: `vectordb/src/main/java/com/vectordb/search/BruteForce.java`)
- HNSW Index → Distance Metrics: computes distances (evidence: `vectordb/src/main/java/com/vectordb/search/HNSW.java`)
- HNSW Index → Search Result: returns ranked hits (evidence: `vectordb/src/main/java/com/vectordb/search/HNSW.java`)
- KD-Tree Index → Distance Metrics: computes distances (evidence: `vectordb/src/main/java/com/vectordb/search/KDTree.java`)
- KD-Tree Index → Search Result: returns ranked hits (evidence: `vectordb/src/main/java/com/vectordb/search/KDTree.java`)
