# akash-sharma8/vectorlens-interactive-vector-search-document-q-a architecture

> Architecture diagram of the GitHub repository akash-sharma8/vectorlens-interactive-vector-search-document-q-a, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a
- Repository: https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a

## Overview

This is a full-stack local vector-search and RAG application. Users register or sign in, then search and benchmark a persistent demo vector collection, manage text/PDF documents, retrieve cited passages, and ask Ollama to generate answers. The API coordinates authentication, retrieval, persistence, and AI calls; the shared core provides vector indexes and distance metrics. The graph preserves the documented PCA visualization and separate document-search stage. Some routes and integrations are represented from README or import-index evidence because their source was not excerpted.

Main entry points: [`apps/api/src/app.ts`](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/api/src/app.ts) (API routes), [`packages/core/src/hnsw.ts`](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/packages/core/src/hnsw.ts) (HNSW index), [`apps/web/components/Dashboard.tsx`](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/web/components/Dashboard.tsx) (Dashboard), [`packages/core/src/vector-db.ts`](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/packages/core/src/vector-db.ts) (Demo vector index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_web["Web app<br/>[layout.tsx]"]
  node_authgate["Auth gate<br/>[AuthGate.tsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
  node_chatpanel["Chat panel<br/>[ChatPanel.tsx]"]
  node_scatter["PCA plot<br/>[ScatterPlot.tsx]"]
  node_webapi["API client<br/>[api.ts]"]
end

subgraph group_api["API and identity"]
  node_api["API routes<br/>[app.ts]"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_context["Request context<br/>[request-context.ts]"]
  node_database[("PostgreSQL<br/>[database.ts]")]
  node_vectorrepo["Demo vector storage"]
end

subgraph group_rag["Documents and RAG"]
  node_chats["Chat orchestration<br/>[chats.ts]"]
  node_pdf["PDF extraction<br/>[pdf.ts]"]
  node_chunks["Chunk preparation<br/>[document-chunks.ts]"]
  node_docrepo["Document storage and search"]
  node_ollama["Ollama adapter<br/>[ollama.ts]"]
end

subgraph group_engine["Vector engine"]
  node_vectorengine["Demo vector index<br/>[vector-db.ts]"]
  node_documentdb["Document index<br/>[document-db.ts]"]
  node_hnsw["HNSW index<br/>[hnsw.ts]"]
  node_kdtree["KD-tree index<br/>[kd-tree.ts]"]
  node_bruteforce["Brute-force search<br/>[brute-force.ts]"]
  node_distance["Distance metrics<br/>[distance.ts]"]
  node_heap["Search heap<br/>[heap.ts]"]
  node_pca["PCA projection<br/>[pca.ts]"]
end

node_user(("User"))
node_ollama_service{{"Ollama service"}}

node_user -->|"uses"| node_web
node_web -->|"renders"| node_authgate
node_authgate -->|"requests auth"| node_webapi
node_authgate -->|"renders"| node_dashboard
node_dashboard -->|"requests data"| node_webapi
node_dashboard -->|"renders"| node_chatpanel
node_dashboard -->|"renders"| node_scatter
node_webapi -->|"calls API"| node_api
node_api -->|"installs routes"| node_auth
node_api -->|"installs routes"| node_chats
node_api -->|"sets user scope"| node_context
node_auth -->|"uses"| node_database
node_chats -->|"retrieves passages"| node_docrepo
node_chats -->|"generates answers"| node_ollama
node_api -->|"extracts uploads"| node_pdf
node_api -->|"prepares text"| node_chunks
node_api -->|"stores and searches"| node_docrepo
node_docrepo -->|"reads and writes"| node_database
node_api -->|"embeds and checks"| node_ollama
node_ollama -->|"sends model requests"| node_ollama_service
node_api -->|"loads vectors"| node_vectorrepo
node_vectorrepo -->|"reads and writes"| node_database
node_api -->|"searches and benchmarks"| node_vectorengine
node_api -->|"searches in memory"| node_documentdb
node_vectorengine -->|"dispatches search"| node_hnsw
node_vectorengine -->|"dispatches search"| node_kdtree
node_vectorengine -->|"dispatches search"| node_bruteforce
node_documentdb -->|"uses index"| node_hnsw
node_documentdb -->|"uses index"| node_bruteforce
node_hnsw -->|"measures distance"| node_distance
node_hnsw -->|"uses candidates"| node_heap
node_hnsw -->|"compares neighbors"| node_bruteforce
node_kdtree -->|"measures distance"| node_distance
node_kdtree -->|"uses candidates"| node_heap
node_scatter -->|"projects vectors"| node_pca

click node_web "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/web/app/layout.tsx"
click node_authgate "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/web/components/AuthGate.tsx"
click node_dashboard "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/web/components/Dashboard.tsx"
click node_chatpanel "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/web/components/ChatPanel.tsx"
click node_scatter "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/web/components/ScatterPlot.tsx"
click node_webapi "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/web/components/api.ts"
click node_api "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/api/src/app.ts"
click node_auth "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/api/src/auth.ts"
click node_context "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/api/src/request-context.ts"
click node_chats "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/api/src/chats.ts"
click node_pdf "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/api/src/pdf.ts"
click node_chunks "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/api/src/document-chunks.ts"
click node_docrepo "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/api/src/document-repository.ts"
click node_ollama "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/api/src/ollama.ts"
click node_database "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/api/src/database.ts"
click node_vectorrepo "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/api/src/vector-repository.ts"
click node_vectorengine "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/packages/core/src/vector-db.ts"
click node_documentdb "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/packages/core/src/document-db.ts"
click node_hnsw "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/packages/core/src/hnsw.ts"
click node_kdtree "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/packages/core/src/kd-tree.ts"
click node_bruteforce "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/packages/core/src/brute-force.ts"
click node_distance "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/packages/core/src/distance.ts"
click node_heap "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/packages/core/src/heap.ts"
click node_pca "https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/packages/core/src/pca.ts"

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_web,node_authgate,node_dashboard,node_chatpanel,node_scatter,node_webapi,node_user toneBlue
class node_api,node_auth,node_context,node_database,node_vectorrepo toneAmber
class node_chats,node_pdf,node_chunks,node_docrepo,node_ollama toneMint
class node_vectorengine,node_documentdb,node_hnsw,node_kdtree,node_bruteforce,node_distance,node_heap,node_pca toneRose
class node_ollama_service toneIndigo
```

## Components

### Web interface

- [Web app](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/web/app/layout.tsx): `apps/web/app/layout.tsx`
- [Auth gate](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/web/components/AuthGate.tsx): `apps/web/components/AuthGate.tsx`
- [Dashboard](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/web/components/Dashboard.tsx): `apps/web/components/Dashboard.tsx`
- [Chat panel](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/web/components/ChatPanel.tsx): `apps/web/components/ChatPanel.tsx`
- [PCA plot](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/web/components/ScatterPlot.tsx): `apps/web/components/ScatterPlot.tsx`
- [API client](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/web/components/api.ts): `apps/web/components/api.ts`

### API and identity

- [API routes](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Authentication](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/api/src/auth.ts): `apps/api/src/auth.ts`
- [Request context](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/api/src/request-context.ts): `apps/api/src/request-context.ts`
- [PostgreSQL](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/api/src/database.ts): `apps/api/src/database.ts`
- [Demo vector storage](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/api/src/vector-repository.ts): `apps/api/src/vector-repository.ts`

### Documents and RAG

- [Chat orchestration](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/api/src/chats.ts): `apps/api/src/chats.ts`
- [PDF extraction](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/api/src/pdf.ts): `apps/api/src/pdf.ts`
- [Chunk preparation](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/api/src/document-chunks.ts): `apps/api/src/document-chunks.ts`
- [Document storage and search](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/api/src/document-repository.ts): `apps/api/src/document-repository.ts`
- [Ollama adapter](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/apps/api/src/ollama.ts): `apps/api/src/ollama.ts`

### Vector engine

- [Demo vector index](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/packages/core/src/vector-db.ts): `packages/core/src/vector-db.ts`
- [Document index](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/packages/core/src/document-db.ts): `packages/core/src/document-db.ts`
- [HNSW index](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/packages/core/src/hnsw.ts): `packages/core/src/hnsw.ts`
- [KD-tree index](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/packages/core/src/kd-tree.ts): `packages/core/src/kd-tree.ts`
- [Brute-force search](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/packages/core/src/brute-force.ts): `packages/core/src/brute-force.ts`
- [Distance metrics](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/packages/core/src/distance.ts): `packages/core/src/distance.ts`
- [Search heap](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/packages/core/src/heap.ts): `packages/core/src/heap.ts`
- [PCA projection](https://github.com/akash-sharma8/vectorlens-interactive-vector-search-document-q-a/blob/main/packages/core/src/pca.ts): `packages/core/src/pca.ts`

### Other components

- **User**
- **Ollama service**

## Connections

- User → Web app: uses
- Web app → Auth gate: renders
- Auth gate → API client: requests auth (evidence: `apps/web/components/AuthGate.tsx`)
- Auth gate → Dashboard: renders (evidence: `apps/web/components/AuthGate.tsx`)
- Dashboard → API client: requests data (evidence: `apps/web/components/Dashboard.tsx`)
- Dashboard → Chat panel: renders (evidence: `apps/web/components/Dashboard.tsx`)
- Dashboard → PCA plot: renders (evidence: `apps/web/components/Dashboard.tsx`)
- API client → API routes: calls API
- API routes → Authentication: installs routes (evidence: `apps/api/src/app.ts`)
- API routes → Chat orchestration: installs routes (evidence: `apps/api/src/app.ts`)
- API routes → Request context: sets user scope (evidence: `apps/api/src/app.ts`)
- Authentication → PostgreSQL: uses (evidence: `apps/api/src/auth.ts`)
- Chat orchestration → Document storage and search: retrieves passages (evidence: `apps/api/src/chats.ts`)
- Chat orchestration → Ollama adapter: generates answers (evidence: `apps/api/src/chats.ts`)
- API routes → PDF extraction: extracts uploads (evidence: `apps/api/src/app.ts`)
- API routes → Chunk preparation: prepares text (evidence: `apps/api/src/app.ts`)
- API routes → Document storage and search: stores and searches (evidence: `apps/api/src/app.ts`)
- Document storage and search → PostgreSQL: reads and writes (evidence: `apps/api/src/document-repository.ts`)
- API routes → Ollama adapter: embeds and checks (evidence: `apps/api/src/app.ts`)
- Ollama adapter → Ollama service: sends model requests (evidence: `apps/api/src/ollama.ts`)
- API routes → Demo vector storage: loads vectors (evidence: `apps/api/src/app.ts`)
- Demo vector storage → PostgreSQL: reads and writes (evidence: `apps/api/src/vector-repository.ts`)
- API routes → Demo vector index: searches and benchmarks (evidence: `apps/api/src/app.ts`)
- API routes → Document index: searches in memory (evidence: `apps/api/src/app.ts`)
- Demo vector index → HNSW index: dispatches search (evidence: `packages/core/src/vector-db.ts`)
- Demo vector index → KD-tree index: dispatches search (evidence: `packages/core/src/vector-db.ts`)
- Demo vector index → Brute-force search: dispatches search (evidence: `packages/core/src/vector-db.ts`)
- Document index → HNSW index: uses index (evidence: `packages/core/src/document-db.ts`)
- Document index → Brute-force search: uses index (evidence: `packages/core/src/document-db.ts`)
- HNSW index → Distance metrics: measures distance (evidence: `packages/core/src/hnsw.ts`)
- HNSW index → Search heap: uses candidates (evidence: `packages/core/src/hnsw.ts`)
- HNSW index → Brute-force search: compares neighbors (evidence: `packages/core/src/hnsw.ts`)
- KD-tree index → Distance metrics: measures distance (evidence: `packages/core/src/kd-tree.ts`)
- KD-tree index → Search heap: uses candidates (evidence: `packages/core/src/kd-tree.ts`)
- PCA plot → PCA projection: projects vectors (evidence: `apps/web/components/ScatterPlot.tsx`)
