# ahmetnasri/retrieval-pipeline architecture

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

- Interactive diagram: https://gitdiagram.com/ahmetnasri/retrieval-pipeline
- Repository: https://github.com/ahmetnasri/retrieval-pipeline

## Overview

This is a GPU-accelerated image retrieval API. A client submits an image to FastAPI, which can add embeddings or run searches; the documented full workflow uses two global-retrieval phases, then local-feature verification, with optional rotation handling. The vector database owns embedding and Qdrant operations, while separate modules implement embedding and local-feature extraction. The README documents the overall stages, but parts of the API and retrieval implementation were not sampled, so some stage links rely on that documentation.

Main entry points: [`src/app.py`](https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/app.py) (FastAPI endpoints), [`src/retrieve.py`](https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/retrieve.py) (Retrieval coordinator), [`src/main.py`](https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/main.py) (API runner), [`src/main_decision_maker.py`](https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/main_decision_maker.py) (Feature preparation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and configuration"]
  node_api_app["FastAPI endpoints<br/>[app.py]"]
  node_api_runner["API runner<br/>[main.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

subgraph group_global["Global retrieval"]
  node_vector_db["Retrieval coordinator<br/>[retrieve.py]"]
  node_phase1["Phase 1 search<br/>[retrieve.py]"]
  node_phase2["Phase 2 refinement<br/>[retrieve.py]"]
  node_embedding["SSCD embeddings"]
end

subgraph group_matching["Local matching"]
  node_decision["Feature preparation"]
  node_superpoint["SuperPoint extractor"]
  node_local_match["Local matching<br/>[retrieve.py]"]
end

subgraph group_state["Retrieval state"]
  node_qdrant[("Qdrant vectors")]
  node_feature_files[("Feature files")]
end

node_client(("Image client"))
node_lightglue["LightGlue matcher"]
node_results["Ranked results"]

node_client -->|"submits image"| node_api_app
node_api_runner -->|"runs"| node_api_app
node_api_runner -->|"loads"| node_settings
node_api_app -->|"imports"| node_settings
node_api_app -->|"invokes"| node_vector_db
node_vector_db -->|"uses model"| node_embedding
node_vector_db -->|"creates"| node_decision
node_vector_db -->|"searches and writes"| node_qdrant
node_api_app -->|"queries phase 1"| node_phase1
node_api_app -->|"refines candidates"| node_phase2
node_api_app -->|"verifies candidates"| node_local_match
node_api_app -->|"returns scores"| node_results
node_vector_db -->|"matches features"| node_local_match
node_decision -->|"uses extractor"| node_superpoint
node_local_match -->|"matches features"| node_lightglue
node_local_match -->|"reads candidates"| node_feature_files
node_api_app -.->|"optionally rotates"| node_local_match

click node_api_app "https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/app.py"
click node_api_runner "https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/main.py"
click node_settings "https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/helpers/config.py"
click node_vector_db "https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/retrieve.py"
click node_phase1 "https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/retrieve.py"
click node_phase2 "https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/retrieve.py"
click node_embedding "https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/lightweight_model.py"
click node_decision "https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/main_decision_maker.py"
click node_superpoint "https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/superpoint_modified.py"
click node_local_match "https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/retrieve.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_api_app,node_api_runner,node_settings,node_client toneBlue
class node_vector_db,node_phase1,node_phase2,node_embedding toneAmber
class node_decision,node_superpoint,node_local_match toneMint
class node_qdrant,node_feature_files toneRose
class node_lightglue,node_results toneIndigo
```

## Components

### API and configuration

- [FastAPI endpoints](https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/app.py): `src/app.py`
- [API runner](https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/main.py): `src/main.py`
- [Runtime settings](https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/helpers/config.py): `src/helpers/config.py`

### Global retrieval

- [Retrieval coordinator](https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/retrieve.py): `src/retrieve.py`
- [Phase 1 search](https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/retrieve.py): `src/retrieve.py`
- [Phase 2 refinement](https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/retrieve.py): `src/retrieve.py`
- [SSCD embeddings](https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/lightweight_model.py): `src/lightweight_model.py`

### Local matching

- [Feature preparation](https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/main_decision_maker.py): `src/main_decision_maker.py`
- [SuperPoint extractor](https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/superpoint_modified.py): `src/superpoint_modified.py`
- [Local matching](https://github.com/ahmetnasri/retrieval-pipeline/blob/main/src/retrieve.py): `src/retrieve.py`

### Retrieval state

- **Qdrant vectors**
- **Feature files**

### Other components

- **Image client**
- **LightGlue matcher**
- **Ranked results**

## Connections

- Image client → FastAPI endpoints: submits image (evidence: `README.md`)
- API runner → FastAPI endpoints: runs (evidence: `src/main.py`)
- API runner → Runtime settings: loads (evidence: `src/main.py`)
- FastAPI endpoints → Runtime settings: imports (evidence: `src/app.py`)
- FastAPI endpoints → Retrieval coordinator: invokes (evidence: `src/app.py`)
- Retrieval coordinator → SSCD embeddings: uses model (evidence: `src/retrieve.py`)
- Retrieval coordinator → Feature preparation: creates (evidence: `src/retrieve.py`)
- Retrieval coordinator → Qdrant vectors: searches and writes (evidence: `src/retrieve.py`)
- FastAPI endpoints → Phase 1 search: queries phase 1 (evidence: `README.md`)
- FastAPI endpoints → Phase 2 refinement: refines candidates (evidence: `README.md`)
- FastAPI endpoints → Local matching: verifies candidates (evidence: `README.md`)
- FastAPI endpoints → Ranked results: returns scores (evidence: `README.md`)
- Retrieval coordinator → Local matching: matches features (evidence: `src/retrieve.py`)
- Feature preparation → SuperPoint extractor: uses extractor (evidence: `src/main_decision_maker.py`)
- Local matching → LightGlue matcher: matches features (evidence: `src/retrieve.py`)
- Local matching → Feature files: reads candidates (evidence: `src/retrieve.py`)
- FastAPI endpoints → Local matching: optionally rotates (evidence: `README.md`)
