# nithish-007/boq-image-retrieval architecture

> Architecture diagram of the GitHub repository nithish-007/boq-image-retrieval, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nithish-007/boq-image-retrieval
- Repository: https://github.com/nithish-007/boq-image-retrieval

## Overview

This repository trains a visual product-retrieval model: training data is assembled into sampled anchor/positive/negative batches, encoded into descriptors, and evaluated against candidate images using nearest-neighbor search. The training entry point also supports checkpointing, optional MLflow logging, and model export. The excerpts show the central calls and data flow; some training and validation implementation is omitted, so unsampled connections are not inferred.

Main entry points: [`train.py`](https://github.com/nithish-007/boq-image-retrieval/blob/main/train.py) (Training entry point), [`dataloaders/boq_dataloader.py`](https://github.com/nithish-007/boq-image-retrieval/blob/main/dataloaders/boq_dataloader.py) (Training loader), [`dataloaders/boq_dataset.py`](https://github.com/nithish-007/boq-image-retrieval/blob/main/dataloaders/boq_dataset.py) (Training dataset), [`models/boq_model.py`](https://github.com/nithish-007/boq-image-retrieval/blob/main/models/boq_model.py) (Metric-learning model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_train_data["Training loader<br/>[boq_dataloader.py]"]
  node_train_set["Training dataset<br/>[boq_dataset.py]"]
  node_transform["Image transforms<br/>[boq_transform.py]"]
  node_centroid["Color centroids<br/>[hist_centroid.py]"]
  node_sampler["Triplet sampler<br/>[boq_sampler.py]"]
  node_val_set["Retrieval validation set<br/>[boq_dataset.py]"]
end

subgraph group_model["Descriptor model"]
  node_backbone["Feature backbone<br/>[backbones.py]"]
  node_aggregator["BoQ aggregator<br/>[boq.py]"]
  node_model_module["Metric-learning model<br/>[boq_model.py]"]
end

subgraph group_runtime["Training and evaluation"]
  node_train["Training entry point<br/>[train.py]"]
  node_search_db[("Vector search index<br/>[usearch_db.py]")]
  node_mlflow["MLflow tracking"]
end

subgraph group_export["Model export"]
  node_config_export["Config and export utilities<br/>[boq_utils.py]"]
end

node_operator(("Training operator"))
node_training_data["Image datasets"]
node_model_artifacts["Exported model artifacts"]

node_operator -->|"starts training"| node_train
node_train -->|"loads config"| node_config_export
node_train -->|"constructs"| node_backbone
node_train -->|"constructs"| node_aggregator
node_train -->|"initializes"| node_model_module
node_train -->|"requests loaders"| node_train_data
node_train -.->|"logs runs"| node_mlflow
node_train -->|"exports models"| node_config_export
node_train_data -->|"builds dataset"| node_train_set
node_train_data -->|"computes centroids"| node_centroid
node_train_data -->|"builds sampler"| node_sampler
node_train_data -->|"builds validation set"| node_val_set
node_train_set -->|"uses augmentation"| node_transform
node_train_set -->|"loads images"| node_training_data
node_sampler -->|"selects samples"| node_train_set
node_sampler -->|"chooses negatives"| node_centroid
node_centroid -->|"reads originals"| node_train_set
node_val_set -->|"uses transforms"| node_transform
node_val_set -->|"loads candidates"| node_training_data
node_model_module -->|"encodes images"| node_backbone
node_model_module -->|"builds descriptors"| node_aggregator
node_model_module -->|"indexes candidates"| node_search_db
node_config_export -->|"writes exports"| node_model_artifacts
node_train -->|"saves checkpoint"| node_model_artifacts

click node_train "https://github.com/nithish-007/boq-image-retrieval/blob/main/train.py"
click node_train_data "https://github.com/nithish-007/boq-image-retrieval/blob/main/dataloaders/boq_dataloader.py"
click node_train_set "https://github.com/nithish-007/boq-image-retrieval/blob/main/dataloaders/boq_dataset.py"
click node_transform "https://github.com/nithish-007/boq-image-retrieval/blob/main/dataloaders/boq_transform.py"
click node_centroid "https://github.com/nithish-007/boq-image-retrieval/blob/main/dataloaders/hist_centroid.py"
click node_sampler "https://github.com/nithish-007/boq-image-retrieval/blob/main/dataloaders/boq_sampler.py"
click node_val_set "https://github.com/nithish-007/boq-image-retrieval/blob/main/dataloaders/boq_dataset.py"
click node_backbone "https://github.com/nithish-007/boq-image-retrieval/blob/main/models/backbones.py"
click node_aggregator "https://github.com/nithish-007/boq-image-retrieval/blob/main/models/boq.py"
click node_model_module "https://github.com/nithish-007/boq-image-retrieval/blob/main/models/boq_model.py"
click node_search_db "https://github.com/nithish-007/boq-image-retrieval/blob/main/dataloaders/usearch_db.py"
click node_config_export "https://github.com/nithish-007/boq-image-retrieval/blob/main/utils/boq_utils.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_train_data,node_train_set,node_transform,node_centroid,node_sampler,node_val_set toneBlue
class node_backbone,node_aggregator,node_model_module toneAmber
class node_train,node_search_db,node_mlflow toneMint
class node_config_export toneRose
class node_operator,node_training_data,node_model_artifacts toneIndigo
```

## Components

### Data preparation

- [Training loader](https://github.com/nithish-007/boq-image-retrieval/blob/main/dataloaders/boq_dataloader.py): `dataloaders/boq_dataloader.py`
- [Training dataset](https://github.com/nithish-007/boq-image-retrieval/blob/main/dataloaders/boq_dataset.py): `dataloaders/boq_dataset.py`
- [Image transforms](https://github.com/nithish-007/boq-image-retrieval/blob/main/dataloaders/boq_transform.py): `dataloaders/boq_transform.py`
- [Color centroids](https://github.com/nithish-007/boq-image-retrieval/blob/main/dataloaders/hist_centroid.py): `dataloaders/hist_centroid.py`
- [Triplet sampler](https://github.com/nithish-007/boq-image-retrieval/blob/main/dataloaders/boq_sampler.py): `dataloaders/boq_sampler.py`
- [Retrieval validation set](https://github.com/nithish-007/boq-image-retrieval/blob/main/dataloaders/boq_dataset.py): `dataloaders/boq_dataset.py`

### Descriptor model

- [Feature backbone](https://github.com/nithish-007/boq-image-retrieval/blob/main/models/backbones.py): `models/backbones.py`
- [BoQ aggregator](https://github.com/nithish-007/boq-image-retrieval/blob/main/models/boq.py): `models/boq.py`
- [Metric-learning model](https://github.com/nithish-007/boq-image-retrieval/blob/main/models/boq_model.py): `models/boq_model.py`

### Training and evaluation

- [Training entry point](https://github.com/nithish-007/boq-image-retrieval/blob/main/train.py): `train.py`
- [Vector search index](https://github.com/nithish-007/boq-image-retrieval/blob/main/dataloaders/usearch_db.py): `dataloaders/usearch_db.py`
- **MLflow tracking**

### Model export

- [Config and export utilities](https://github.com/nithish-007/boq-image-retrieval/blob/main/utils/boq_utils.py): `utils/boq_utils.py`

### Other components

- **Training operator**
- **Image datasets**
- **Exported model artifacts**

## Connections

- Training operator → Training entry point: starts training (evidence: `train.py`)
- Training entry point → Config and export utilities: loads config (evidence: `train.py`)
- Training entry point → Feature backbone: constructs (evidence: `train.py`)
- Training entry point → BoQ aggregator: constructs (evidence: `train.py`)
- Training entry point → Metric-learning model: initializes (evidence: `train.py`)
- Training entry point → Training loader: requests loaders (evidence: `train.py`)
- Training entry point → MLflow tracking: logs runs (evidence: `train.py`)
- Training entry point → Config and export utilities: exports models (evidence: `train.py`)
- Training loader → Training dataset: builds dataset (evidence: `dataloaders/boq_dataloader.py`)
- Training loader → Color centroids: computes centroids (evidence: `dataloaders/boq_dataloader.py`)
- Training loader → Triplet sampler: builds sampler (evidence: `dataloaders/boq_dataloader.py`)
- Training loader → Retrieval validation set: builds validation set (evidence: `dataloaders/boq_dataloader.py`)
- Training dataset → Image transforms: uses augmentation (evidence: `dataloaders/boq_dataset.py`)
- Training dataset → Image datasets: loads images (evidence: `dataloaders/boq_dataset.py`)
- Triplet sampler → Training dataset: selects samples (evidence: `dataloaders/boq_sampler.py`)
- Triplet sampler → Color centroids: chooses negatives (evidence: `dataloaders/boq_sampler.py`)
- Color centroids → Training dataset: reads originals (evidence: `dataloaders/hist_centroid.py`)
- Retrieval validation set → Image transforms: uses transforms (evidence: `dataloaders/boq_dataset.py`)
- Retrieval validation set → Image datasets: loads candidates (evidence: `dataloaders/boq_dataset.py`)
- Metric-learning model → Feature backbone: encodes images (evidence: `models/boq_model.py`)
- Metric-learning model → BoQ aggregator: builds descriptors (evidence: `models/boq_model.py`)
- Metric-learning model → Vector search index: indexes candidates (evidence: `models/boq_model.py`)
- Config and export utilities → Exported model artifacts: writes exports (evidence: `utils/boq_utils.py`)
- Training entry point → Exported model artifacts: saves checkpoint (evidence: `train.py`)
