# abiramr12317-png/hnsw-vault architecture

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

- Interactive diagram: https://gitdiagram.com/abiramr12317-png/hnsw-vault
- Repository: https://github.com/abiramr12317-png/hnsw-vault

## Overview

HNSW Vault lets users bulk-upload event photos, then search with a face photo to retrieve matching originals and thumbnails. Uploads are stored, face embeddings are generated and indexed, and metadata links index IDs back to images. Searches embed the query, traverse the HNSW index, filter candidates by distance, resolve image metadata, and lazily create thumbnails. The README documents these capabilities; the shown source establishes the main API-owned calls and persistence steps.

Main entry points: [`app/main.py`](https://github.com/abiramr12317-png/hnsw-vault/blob/main/app/main.py) (FastAPI endpoints), [`app/pipeline.py`](https://github.com/abiramr12317-png/hnsw-vault/blob/main/app/pipeline.py) (Image ingestion), [`app/db.py`](https://github.com/abiramr12317-png/hnsw-vault/blob/main/app/db.py) (Metadata helpers), [`frontend/script.js`](https://github.com/abiramr12317-png/hnsw-vault/blob/main/frontend/script.js) (Browser UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_frontend["Browser UI<br/>[script.js]"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

subgraph group_ingestion["Photo ingestion"]
  node_ingest["Image ingestion<br/>[pipeline.py]"]
  node_embeddings["Face embeddings<br/>[embeddings.py]"]
end

subgraph group_search["Face search"]
  node_hnsw["HNSW index<br/>[hnsw.py]"]
  node_thumbnails["Thumbnail generation<br/>[thumbnails.py]"]
end

subgraph group_persistence["Storage and metadata"]
  node_originals[("Original images")]
  node_indexfile[("Persisted index")]
  node_metadata["Metadata helpers<br/>[db.py]"]
  node_metadb[("Metadata database")]
  node_thumbfiles[("Cached thumbnails")]
end

node_user(("User"))

node_user -->|"uses"| node_frontend
node_frontend -->|"calls API"| node_api
node_api -->|"reads settings"| node_config
node_api -->|"dispatches upload"| node_ingest
node_ingest -->|"copies images"| node_originals
node_ingest -->|"extracts faces"| node_embeddings
node_ingest -->|"inserts vectors"| node_hnsw
node_ingest -->|"records image and faces"| node_metadata
node_api -->|"loads, searches, saves"| node_hnsw
node_api -->|"embeds query"| node_embeddings
node_api -->|"looks up matches"| node_metadata
node_api -->|"requests thumbnails"| node_thumbnails
node_api -->|"loads and saves index"| node_indexfile
node_metadata -->|"reads and writes"| node_metadb
node_thumbnails -->|"creates and caches"| node_thumbfiles
node_api -->|"serves images"| node_originals
node_api -->|"serves thumbnails"| node_thumbfiles

click node_frontend "https://github.com/abiramr12317-png/hnsw-vault/blob/main/frontend/script.js"
click node_api "https://github.com/abiramr12317-png/hnsw-vault/blob/main/app/main.py"
click node_config "https://github.com/abiramr12317-png/hnsw-vault/blob/main/app/config.py"
click node_ingest "https://github.com/abiramr12317-png/hnsw-vault/blob/main/app/pipeline.py"
click node_embeddings "https://github.com/abiramr12317-png/hnsw-vault/blob/main/app/embeddings.py"
click node_originals "https://github.com/abiramr12317-png/hnsw-vault/tree/main/storage/originals"
click node_hnsw "https://github.com/abiramr12317-png/hnsw-vault/blob/main/app/hnsw.py"
click node_indexfile "https://github.com/abiramr12317-png/hnsw-vault/tree/main/storage/index_data"
click node_metadata "https://github.com/abiramr12317-png/hnsw-vault/blob/main/app/db.py"
click node_metadb "https://github.com/abiramr12317-png/hnsw-vault/tree/main/storage"
click node_thumbnails "https://github.com/abiramr12317-png/hnsw-vault/blob/main/app/thumbnails.py"
click node_thumbfiles "https://github.com/abiramr12317-png/hnsw-vault/tree/main/storage/thumbnails"

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_frontend,node_api,node_config,node_user toneBlue
class node_ingest,node_embeddings toneAmber
class node_hnsw,node_thumbnails toneMint
class node_originals,node_indexfile,node_metadata,node_metadb,node_thumbfiles toneRose
```

## Components

### User interface

- [Browser UI](https://github.com/abiramr12317-png/hnsw-vault/blob/main/frontend/script.js): `frontend/script.js`
- [FastAPI endpoints](https://github.com/abiramr12317-png/hnsw-vault/blob/main/app/main.py): `app/main.py`
- [Runtime configuration](https://github.com/abiramr12317-png/hnsw-vault/blob/main/app/config.py): `app/config.py`

### Photo ingestion

- [Image ingestion](https://github.com/abiramr12317-png/hnsw-vault/blob/main/app/pipeline.py): `app/pipeline.py`
- [Face embeddings](https://github.com/abiramr12317-png/hnsw-vault/blob/main/app/embeddings.py): `app/embeddings.py`

### Face search

- [HNSW index](https://github.com/abiramr12317-png/hnsw-vault/blob/main/app/hnsw.py): `app/hnsw.py`
- [Thumbnail generation](https://github.com/abiramr12317-png/hnsw-vault/blob/main/app/thumbnails.py): `app/thumbnails.py`

### Storage and metadata

- [Original images](https://github.com/abiramr12317-png/hnsw-vault/tree/main/storage/originals): `storage/originals`
- [Persisted index](https://github.com/abiramr12317-png/hnsw-vault/tree/main/storage/index_data): `storage/index_data`
- [Metadata helpers](https://github.com/abiramr12317-png/hnsw-vault/blob/main/app/db.py): `app/db.py`
- [Metadata database](https://github.com/abiramr12317-png/hnsw-vault/tree/main/storage): `storage`
- [Cached thumbnails](https://github.com/abiramr12317-png/hnsw-vault/tree/main/storage/thumbnails): `storage/thumbnails`

### Other components

- **User**

## Connections

- User → Browser UI: uses (evidence: `README.md`)
- Browser UI → FastAPI endpoints: calls API (evidence: `frontend/script.js`)
- FastAPI endpoints → Runtime configuration: reads settings (evidence: `app/main.py`)
- FastAPI endpoints → Image ingestion: dispatches upload (evidence: `app/main.py`)
- Image ingestion → Original images: copies images (evidence: `app/pipeline.py`)
- Image ingestion → Face embeddings: extracts faces (evidence: `app/pipeline.py`)
- Image ingestion → HNSW index: inserts vectors (evidence: `app/pipeline.py`)
- Image ingestion → Metadata helpers: records image and faces (evidence: `app/pipeline.py`)
- FastAPI endpoints → HNSW index: loads, searches, saves (evidence: `app/main.py`)
- FastAPI endpoints → Face embeddings: embeds query (evidence: `app/main.py`)
- FastAPI endpoints → Metadata helpers: looks up matches (evidence: `app/main.py`)
- FastAPI endpoints → Thumbnail generation: requests thumbnails (evidence: `app/main.py`)
- FastAPI endpoints → Persisted index: loads and saves index (evidence: `app/main.py`)
- Metadata helpers → Metadata database: reads and writes (evidence: `app/db.py`)
- Thumbnail generation → Cached thumbnails: creates and caches (evidence: `app/thumbnails.py`)
- FastAPI endpoints → Original images: serves images (evidence: `app/main.py`)
- FastAPI endpoints → Cached thumbnails: serves thumbnails (evidence: `app/main.py`)
