# dileepwick/vector-doc-engine architecture

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

- Interactive diagram: https://gitdiagram.com/dileepwick/vector-doc-engine
- Repository: https://github.com/dileepwick/vector-doc-engine

## Overview

vector-doc-engine is a TypeScript PDF-to-vector-search library and CLI. Users ingest a PDF, which is extracted, recursively chunked, embedded through Gemini with retry handling, and upserted into ChromaDB; they then submit a query, embed it, retrieve candidate chunks, convert distances to similarity scores, and filter results. The graph includes the public exports and major domain stages. Relationships are based on the sampled source and README; ChromaDB and Gemini are external services.

Main entry points: [`src/ingest.ts`](https://github.com/dileepwick/vector-doc-engine/blob/main/src/ingest.ts) (Ingest orchestration), [`src/ask.ts`](https://github.com/dileepwick/vector-doc-engine/blob/main/src/ask.ts) (Search orchestration), [`src/index.ts`](https://github.com/dileepwick/vector-doc-engine/blob/main/src/index.ts) (Public exports), [`src/embedder.ts`](https://github.com/dileepwick/vector-doc-engine/blob/main/src/embedder.ts) (Embedding with retries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Library API"]
  node_public_api["Public exports<br/>[index.ts]"]
end

subgraph group_ingestion["PDF Ingestion"]
  node_pdf_input["PDF input<br/>[ingest.ts]"]
  node_pdf_extract["PDF text extraction<br/>[ingest.ts]"]
  node_chunking["Recursive chunking<br/>[chunker.ts]"]
  node_ingest_flow["Ingest orchestration<br/>[ingest.ts]"]
end

subgraph group_search["Semantic Search"]
  node_query_input["Search query<br/>[ask.ts]"]
  node_search_flow["Search orchestration<br/>[ask.ts]"]
  node_similarity["Similarity scoring and filtering<br/>[ask.ts]"]
  node_matches["Ranked excerpt matches<br/>[ask.ts]"]
end

subgraph group_integrations["External Services"]
  node_embedding["Embedding with retries<br/>[embedder.ts]"]
  node_vector_store[("ChromaDB collection")]
  node_gemini{{"Google Gemini API"}}
end

node_user(("Library user / CLI user"))

node_user -->|"uses exports"| node_public_api
node_user -->|"ingests PDF"| node_ingest_flow
node_user -->|"queries documents"| node_search_flow
node_public_api -->|"exports"| node_chunking
node_public_api -->|"exports"| node_embedding
node_public_api -->|"exports"| node_ingest_flow
node_public_api -->|"exports"| node_search_flow
node_ingest_flow -->|"resolves and reads"| node_pdf_input
node_ingest_flow -->|"extracts text"| node_pdf_extract
node_ingest_flow -->|"chunks text"| node_chunking
node_ingest_flow -->|"embeds batches"| node_embedding
node_embedding -->|"requests vectors"| node_gemini
node_ingest_flow -->|"upserts vectors"| node_vector_store
node_search_flow -->|"accepts query"| node_query_input
node_search_flow -->|"embeds query"| node_embedding
node_search_flow -->|"queries vectors"| node_vector_store
node_search_flow -->|"scores and filters"| node_similarity
node_similarity -->|"returns matches"| node_matches
node_search_flow -.->|"configures API client"| node_gemini

click node_public_api "https://github.com/dileepwick/vector-doc-engine/blob/main/src/index.ts"
click node_pdf_input "https://github.com/dileepwick/vector-doc-engine/blob/main/src/ingest.ts"
click node_pdf_extract "https://github.com/dileepwick/vector-doc-engine/blob/main/src/ingest.ts"
click node_chunking "https://github.com/dileepwick/vector-doc-engine/blob/main/src/chunker.ts"
click node_ingest_flow "https://github.com/dileepwick/vector-doc-engine/blob/main/src/ingest.ts"
click node_embedding "https://github.com/dileepwick/vector-doc-engine/blob/main/src/embedder.ts"
click node_query_input "https://github.com/dileepwick/vector-doc-engine/blob/main/src/ask.ts"
click node_search_flow "https://github.com/dileepwick/vector-doc-engine/blob/main/src/ask.ts"
click node_similarity "https://github.com/dileepwick/vector-doc-engine/blob/main/src/ask.ts"
click node_matches "https://github.com/dileepwick/vector-doc-engine/blob/main/src/ask.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_public_api,node_user toneBlue
class node_pdf_input,node_pdf_extract,node_chunking,node_ingest_flow toneAmber
class node_query_input,node_search_flow,node_similarity,node_matches toneMint
class node_embedding,node_vector_store,node_gemini toneRose
```

## Components

### Library API

- [Public exports](https://github.com/dileepwick/vector-doc-engine/blob/main/src/index.ts): `src/index.ts`

### PDF Ingestion

- [PDF input](https://github.com/dileepwick/vector-doc-engine/blob/main/src/ingest.ts): `src/ingest.ts`
- [PDF text extraction](https://github.com/dileepwick/vector-doc-engine/blob/main/src/ingest.ts): `src/ingest.ts`
- [Recursive chunking](https://github.com/dileepwick/vector-doc-engine/blob/main/src/chunker.ts): `src/chunker.ts`
- [Ingest orchestration](https://github.com/dileepwick/vector-doc-engine/blob/main/src/ingest.ts): `src/ingest.ts`

### Semantic Search

- [Search query](https://github.com/dileepwick/vector-doc-engine/blob/main/src/ask.ts): `src/ask.ts`
- [Search orchestration](https://github.com/dileepwick/vector-doc-engine/blob/main/src/ask.ts): `src/ask.ts`
- [Similarity scoring and filtering](https://github.com/dileepwick/vector-doc-engine/blob/main/src/ask.ts): `src/ask.ts`
- [Ranked excerpt matches](https://github.com/dileepwick/vector-doc-engine/blob/main/src/ask.ts): `src/ask.ts`

### External Services

- [Embedding with retries](https://github.com/dileepwick/vector-doc-engine/blob/main/src/embedder.ts): `src/embedder.ts`
- **ChromaDB collection**
- **Google Gemini API**

### Other components

- **Library user / CLI user**

## Connections

- Library user / CLI user → Public exports: uses exports (evidence: `README.md`)
- Library user / CLI user → Ingest orchestration: ingests PDF (evidence: `README.md`)
- Library user / CLI user → Search orchestration: queries documents (evidence: `README.md`)
- Public exports → Recursive chunking: exports (evidence: `src/index.ts`)
- Public exports → Embedding with retries: exports (evidence: `src/index.ts`)
- Public exports → Ingest orchestration: exports (evidence: `src/index.ts`)
- Public exports → Search orchestration: exports (evidence: `src/index.ts`)
- Ingest orchestration → PDF input: resolves and reads (evidence: `src/ingest.ts`)
- Ingest orchestration → PDF text extraction: extracts text (evidence: `src/ingest.ts`)
- Ingest orchestration → Recursive chunking: chunks text (evidence: `src/ingest.ts`)
- Ingest orchestration → Embedding with retries: embeds batches (evidence: `src/ingest.ts`)
- Embedding with retries → Google Gemini API: requests vectors (evidence: `src/embedder.ts`)
- Ingest orchestration → ChromaDB collection: upserts vectors (evidence: `src/ingest.ts`)
- Search orchestration → Search query: accepts query (evidence: `src/ask.ts`)
- Search orchestration → Embedding with retries: embeds query (evidence: `src/ask.ts`)
- Search orchestration → ChromaDB collection: queries vectors (evidence: `src/ask.ts`)
- Search orchestration → Similarity scoring and filtering: scores and filters (evidence: `src/ask.ts`)
- Similarity scoring and filtering → Ranked excerpt matches: returns matches (evidence: `src/ask.ts`)
- Search orchestration → Google Gemini API: configures API client (evidence: `src/ask.ts`)
