# sakejaswanth/indexforge-db architecture

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

- Interactive diagram: https://gitdiagram.com/sakejaswanth/indexforge-db
- Repository: https://github.com/sakejaswanth/indexforge-db

## Overview

IndexForge-DB is a multidimensional nearest-neighbor search and benchmarking product: users submit 2D queries or audio/image files, then compare KD-Tree and R-Tree results against a linear-search baseline across several embedding dimensions. The FastAPI app coordinates query feature extraction, engine searches, metadata lookup, and result delivery to the React dashboard. The README documents the index and storage layers; source excerpts confirm API and fallback behavior, but do not expose all native bindings or preprocessing internals, so uncertain call links are omitted.

Main entry points: [`app.py`](https://github.com/sakejaswanth/indexforge-db/blob/main/app.py) (FastAPI service), [`src/buffer_pool_manager.cpp`](https://github.com/sakejaswanth/indexforge-db/blob/main/src/buffer_pool_manager.cpp) (Buffer pool), [`src/data_file.cpp`](https://github.com/sakejaswanth/indexforge-db/blob/main/src/data_file.cpp) (Vector data file), [`src/kdtree_disk.cpp`](https://github.com/sakejaswanth/indexforge-db/blob/main/src/kdtree_disk.cpp) (Disk KD-Tree)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard"]
  node_dashboard["React dashboard<br/>[App.jsx]"]
end

subgraph group_api["API and preprocessing"]
  node_api_app["FastAPI service<br/>[app.py]"]
  node_audio_features["Audio features"]
  node_image_features["Image features"]
  node_audio_prep["Audio preprocessing<br/>[preprocess.py]"]
  node_image_prep["Image preprocessing"]
  node_dataset_load["Dataset indexing<br/>[load_dataset.py]"]
  node_metadata["Media metadata<br/>[app.py]"]
end

subgraph group_search["Search engines"]
  node_kd_binding["KD native binding<br/>[bind_kdtree.cpp]"]
  node_rt_binding["R-Tree native binding<br/>[bind_rtree.cpp]"]
  node_kd_tree["Disk KD-Tree<br/>[kdtree_disk.cpp]"]
  node_rtree["R-Tree<br/>[rtree.cpp]"]
  node_linear["Linear baseline<br/>[search_engine.cpp]"]
  node_python_fallback["Python fallback engines<br/>[python_core.py]"]
end

subgraph group_storage["Paged storage"]
  node_data_file["Vector data file<br/>[data_file.cpp]"]
  node_rtree_file["R-Tree file layer<br/>[rtree_file.cpp]"]
  node_buffer_pool["Buffer pool"]
  node_lru["LRU replacer<br/>[lru_replacer.cpp]"]
  node_disk["Disk manager<br/>[disk_manager.cpp]"]
  node_db_files[("Page files")]
end

node_user(("Dashboard user"))
node_audio_upload(("Audio query"))
node_image_upload(("Image query"))
node_point_query(("2D point query"))

node_user -->|"uses"| node_dashboard
node_dashboard -->|"sends queries"| node_api_app
node_audio_upload -->|"uploads audio"| node_api_app
node_image_upload -->|"uploads image"| node_api_app
node_point_query -->|"submits point"| node_api_app
node_api_app -->|"extracts features"| node_audio_features
node_api_app -->|"extracts features"| node_image_features
node_audio_prep -.->|"projects queries"| node_audio_features
node_image_prep -.->|"projects queries"| node_image_features
node_dataset_load -.->|"stores vectors"| node_data_file
node_api_app -->|"runs KD search"| node_kd_binding
node_api_app -->|"runs R-Tree search"| node_rt_binding
node_api_app -->|"maps results"| node_metadata
node_kd_binding -->|"dispatches"| node_kd_tree
node_rt_binding -->|"dispatches"| node_rtree
node_kd_tree -->|"reads vectors"| node_data_file
node_kd_tree -->|"fetches pages"| node_buffer_pool
node_rtree -->|"reads and writes"| node_rtree_file
node_rtree -->|"fetches pages"| node_buffer_pool
node_rtree_file -->|"fetches pages"| node_buffer_pool
node_data_file -->|"fetches pages"| node_buffer_pool
node_buffer_pool -->|"evicts frames"| node_lru
node_buffer_pool -->|"reads and writes"| node_disk
node_disk -->|"page I/O"| node_db_files
node_api_app -.->|"uses if selected"| node_python_fallback
node_python_fallback -.->|"stores vectors"| node_data_file
node_linear -->|"scans records"| node_data_file

click node_dashboard "https://github.com/sakejaswanth/indexforge-db/blob/main/frontend/src/App.jsx"
click node_api_app "https://github.com/sakejaswanth/indexforge-db/blob/main/app.py"
click node_audio_features "https://github.com/sakejaswanth/indexforge-db/blob/main/scripts/extract_audio_features.py"
click node_image_features "https://github.com/sakejaswanth/indexforge-db/blob/main/scripts/extract_image_features.py"
click node_audio_prep "https://github.com/sakejaswanth/indexforge-db/blob/main/scripts/preprocess.py"
click node_image_prep "https://github.com/sakejaswanth/indexforge-db/blob/main/scripts/preprocess_images.py"
click node_dataset_load "https://github.com/sakejaswanth/indexforge-db/blob/main/scripts/load_dataset.py"
click node_metadata "https://github.com/sakejaswanth/indexforge-db/blob/main/app.py"
click node_kd_binding "https://github.com/sakejaswanth/indexforge-db/blob/main/src/bind_kdtree.cpp"
click node_rt_binding "https://github.com/sakejaswanth/indexforge-db/blob/main/src/bind_rtree.cpp"
click node_kd_tree "https://github.com/sakejaswanth/indexforge-db/blob/main/src/kdtree_disk.cpp"
click node_rtree "https://github.com/sakejaswanth/indexforge-db/blob/main/src/rtree.cpp"
click node_linear "https://github.com/sakejaswanth/indexforge-db/blob/main/src/search_engine.cpp"
click node_data_file "https://github.com/sakejaswanth/indexforge-db/blob/main/src/data_file.cpp"
click node_rtree_file "https://github.com/sakejaswanth/indexforge-db/blob/main/src/rtree_file.cpp"
click node_buffer_pool "https://github.com/sakejaswanth/indexforge-db/blob/main/src/buffer_pool_manager.cpp"
click node_lru "https://github.com/sakejaswanth/indexforge-db/blob/main/src/lru_replacer.cpp"
click node_disk "https://github.com/sakejaswanth/indexforge-db/blob/main/src/disk_manager.cpp"
click node_python_fallback "https://github.com/sakejaswanth/indexforge-db/blob/main/python_core.py"

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_dashboard,node_user toneBlue
class node_api_app,node_audio_features,node_image_features,node_audio_prep,node_image_prep,node_dataset_load,node_metadata toneAmber
class node_kd_binding,node_rt_binding,node_kd_tree,node_rtree,node_linear,node_python_fallback toneMint
class node_data_file,node_rtree_file,node_buffer_pool,node_lru,node_disk,node_db_files toneRose
class node_audio_upload,node_image_upload,node_point_query toneIndigo
```

## Components

### Dashboard

- [React dashboard](https://github.com/sakejaswanth/indexforge-db/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`

### API and preprocessing

- [FastAPI service](https://github.com/sakejaswanth/indexforge-db/blob/main/app.py): `app.py`
- [Audio features](https://github.com/sakejaswanth/indexforge-db/blob/main/scripts/extract_audio_features.py): `scripts/extract_audio_features.py`
- [Image features](https://github.com/sakejaswanth/indexforge-db/blob/main/scripts/extract_image_features.py): `scripts/extract_image_features.py`
- [Audio preprocessing](https://github.com/sakejaswanth/indexforge-db/blob/main/scripts/preprocess.py): `scripts/preprocess.py`
- [Image preprocessing](https://github.com/sakejaswanth/indexforge-db/blob/main/scripts/preprocess_images.py): `scripts/preprocess_images.py`
- [Dataset indexing](https://github.com/sakejaswanth/indexforge-db/blob/main/scripts/load_dataset.py): `scripts/load_dataset.py`
- [Media metadata](https://github.com/sakejaswanth/indexforge-db/blob/main/app.py): `app.py`

### Search engines

- [KD native binding](https://github.com/sakejaswanth/indexforge-db/blob/main/src/bind_kdtree.cpp): `src/bind_kdtree.cpp`
- [R-Tree native binding](https://github.com/sakejaswanth/indexforge-db/blob/main/src/bind_rtree.cpp): `src/bind_rtree.cpp`
- [Disk KD-Tree](https://github.com/sakejaswanth/indexforge-db/blob/main/src/kdtree_disk.cpp): `src/kdtree_disk.cpp`
- [R-Tree](https://github.com/sakejaswanth/indexforge-db/blob/main/src/rtree.cpp): `src/rtree.cpp`
- [Linear baseline](https://github.com/sakejaswanth/indexforge-db/blob/main/src/search_engine.cpp): `src/search_engine.cpp`
- [Python fallback engines](https://github.com/sakejaswanth/indexforge-db/blob/main/python_core.py): `python_core.py`

### Paged storage

- [Vector data file](https://github.com/sakejaswanth/indexforge-db/blob/main/src/data_file.cpp): `src/data_file.cpp`
- [R-Tree file layer](https://github.com/sakejaswanth/indexforge-db/blob/main/src/rtree_file.cpp): `src/rtree_file.cpp`
- [Buffer pool](https://github.com/sakejaswanth/indexforge-db/blob/main/src/buffer_pool_manager.cpp): `src/buffer_pool_manager.cpp`
- [LRU replacer](https://github.com/sakejaswanth/indexforge-db/blob/main/src/lru_replacer.cpp): `src/lru_replacer.cpp`
- [Disk manager](https://github.com/sakejaswanth/indexforge-db/blob/main/src/disk_manager.cpp): `src/disk_manager.cpp`
- **Page files**

### Other components

- **Dashboard user**
- **Audio query**
- **Image query**
- **2D point query**

## Connections

- Dashboard user → React dashboard: uses
- React dashboard → FastAPI service: sends queries
- Audio query → FastAPI service: uploads audio
- Image query → FastAPI service: uploads image
- 2D point query → FastAPI service: submits point
- FastAPI service → Audio features: extracts features
- FastAPI service → Image features: extracts features
- Audio preprocessing → Audio features: projects queries
- Image preprocessing → Image features: projects queries
- Dataset indexing → Vector data file: stores vectors
- FastAPI service → KD native binding: runs KD search
- FastAPI service → R-Tree native binding: runs R-Tree search
- FastAPI service → Media metadata: maps results
- KD native binding → Disk KD-Tree: dispatches
- R-Tree native binding → R-Tree: dispatches
- Disk KD-Tree → Vector data file: reads vectors
- Disk KD-Tree → Buffer pool: fetches pages
- R-Tree → R-Tree file layer: reads and writes
- R-Tree → Buffer pool: fetches pages
- R-Tree file layer → Buffer pool: fetches pages
- Vector data file → Buffer pool: fetches pages
- Buffer pool → LRU replacer: evicts frames
- Buffer pool → Disk manager: reads and writes
- Disk manager → Page files: page I/O
- FastAPI service → Python fallback engines: uses if selected
- Python fallback engines → Vector data file: stores vectors
- Linear baseline → Vector data file: scans records