# muhammademmadsiddiqui/ra-fr architecture

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

- Interactive diagram: https://gitdiagram.com/muhammademmadsiddiqui/ra-fr
- Repository: https://github.com/muhammademmadsiddiqui/ra-fr

## Overview

RA-FR is a research system for risk-aware face retrieval: prepare or select a face dataset, train an uncertainty-aware embedding model, evaluate retrieval, then apply RAFR to evaluated embeddings and uncertainty. The graph preserves the documented IMFDB and SCFace paths, model variants, and retrieval analysis. Some evaluation and RAFR internals are only partially sampled, so only documented or indexed relationships are shown; optional SCFace restoration tools are external.

Main entry points: [`networks/__init__.py`](https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/networks/__init__.py) (Model selection), [`lightning_modules/datamodule.py`](https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/lightning_modules/datamodule.py) (Data loading), [`run.py`](https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/run.py) (Train and eval runner), [`lightning_modules/lightning.py`](https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/lightning_modules/lightning.py) (Metric learning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_imfdb_prep["IMFDB preparation"]
  node_imfdb_metadata["IMFDB metadata"]
  node_scface_prep["SCFace preparation"]
  node_imfdb["IMFDB dataset<br/>[imfdb.py]"]
  node_scface["SCFace dataset<br/>[scface.py]"]
end

subgraph group_training["Training and models"]
  node_data_module["Data loading<br/>[datamodule.py]"]
  node_runner["Train and eval runner<br/>[run.py]"]
  node_training_module["Metric learning<br/>[lightning.py]"]
  node_model_factory["Model selection<br/>[__init__.py]"]
  node_resnet_model["R50-GeM<br/>[network.py]"]
  node_vit_gem["ViTB-DN-GeM<br/>[ViTB-DN-GeM.py]"]
  node_vit_ggem["ViTB-DN-GGeM<br/>[ViTB-DN-GGeM.py]"]
  node_pooling["Pooling functions<br/>[functional.py]"]
  node_loss["Metric losses<br/>[loss.py]"]
  node_loss_functions["Loss functions<br/>[functional.py]"]
end

subgraph group_retrieval["Retrieval and risk"]
  node_retrieval_utils["Nearest-neighbor retrieval<br/>[utils.py]"]
  node_rafr["RAFR uncertainty<br/>[rafr.py]"]
  node_rafr_utils["Coverage utilities<br/>[cp_utils.py]"]
end

subgraph group_analysis["Result analysis"]
  node_visualizations["Retrieval analysis"]
end

node_researcher(("Researcher"))
node_restoration["Face restoration tools"]

node_researcher -->|"organizes images"| node_imfdb_prep
node_imfdb_prep -->|"precedes metadata"| node_imfdb_metadata
node_imfdb_metadata -->|"prepares dataset"| node_imfdb
node_researcher -->|"prepares images"| node_scface_prep
node_scface_prep -->|"prepares dataset"| node_scface
node_restoration -.->|"restores faces"| node_scface_prep
node_researcher -->|"starts training"| node_runner
node_runner -->|"configures loaders"| node_data_module
node_runner -->|"starts training"| node_training_module
node_data_module -->|"loads dataset"| node_imfdb
node_data_module -->|"loads dataset"| node_scface
node_training_module -->|"selects model"| node_model_factory
node_model_factory -->|"provides architecture"| node_resnet_model
node_model_factory -->|"provides architecture"| node_vit_gem
node_model_factory -->|"provides architecture"| node_vit_ggem
node_resnet_model -->|"uses pooling"| node_pooling
node_vit_gem -->|"uses pooling"| node_pooling
node_training_module -->|"computes loss"| node_loss
node_loss -->|"delegates calculations"| node_loss_functions
node_researcher -->|"applies RAFR"| node_rafr
node_rafr -->|"searches neighbors"| node_retrieval_utils
node_rafr -->|"uses coverage metrics"| node_rafr_utils
node_researcher -->|"analyzes results"| node_visualizations

click node_imfdb_prep "https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/preparation/step1_organize_folders.py"
click node_imfdb_metadata "https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/preparation/step2_generate_metadata.py"
click node_imfdb "https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/datasets/imfdb.py"
click node_scface "https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/datasets/scface.py"
click node_data_module "https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/lightning_modules/datamodule.py"
click node_runner "https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/run.py"
click node_training_module "https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/lightning_modules/lightning.py"
click node_model_factory "https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/networks/__init__.py"
click node_resnet_model "https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/networks/network.py"
click node_vit_gem "https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/networks/ViTB-DN-GeM.py"
click node_vit_ggem "https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/networks/ViTB-DN-GGeM.py"
click node_pooling "https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/cirtorch/functional.py"
click node_loss "https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/losses/loss.py"
click node_loss_functions "https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/losses/functional.py"
click node_retrieval_utils "https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/utils/utils.py"
click node_rafr "https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/rafr.py"
click node_rafr_utils "https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/utils/cp_utils.py"
click node_visualizations "https://github.com/muhammademmadsiddiqui/ra-fr/tree/main/Visualizations"

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_imfdb_prep,node_imfdb_metadata,node_scface_prep,node_imfdb,node_scface toneBlue
class node_data_module,node_runner,node_training_module,node_model_factory,node_resnet_model,node_vit_gem,node_vit_ggem,node_pooling,node_loss,node_loss_functions toneAmber
class node_retrieval_utils,node_rafr,node_rafr_utils toneMint
class node_visualizations toneRose
class node_researcher,node_restoration toneIndigo
```

## Components

### Data preparation

- [IMFDB preparation](https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/preparation/step1_organize_folders.py): `preparation/step1_organize_folders.py`
- [IMFDB metadata](https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/preparation/step2_generate_metadata.py): `preparation/step2_generate_metadata.py`
- **SCFace preparation**
- [IMFDB dataset](https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/datasets/imfdb.py): `datasets/imfdb.py`
- [SCFace dataset](https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/datasets/scface.py): `datasets/scface.py`

### Training and models

- [Data loading](https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/lightning_modules/datamodule.py): `lightning_modules/datamodule.py`
- [Train and eval runner](https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/run.py): `run.py`
- [Metric learning](https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/lightning_modules/lightning.py): `lightning_modules/lightning.py`
- [Model selection](https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/networks/__init__.py): `networks/__init__.py`
- [R50-GeM](https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/networks/network.py): `networks/network.py`
- [ViTB-DN-GeM](https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/networks/ViTB-DN-GeM.py): `networks/ViTB-DN-GeM.py`
- [ViTB-DN-GGeM](https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/networks/ViTB-DN-GGeM.py): `networks/ViTB-DN-GGeM.py`
- [Pooling functions](https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/cirtorch/functional.py): `cirtorch/functional.py`
- [Metric losses](https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/losses/loss.py): `losses/loss.py`
- [Loss functions](https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/losses/functional.py): `losses/functional.py`

### Retrieval and risk

- [Nearest-neighbor retrieval](https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/utils/utils.py): `utils/utils.py`
- [RAFR uncertainty](https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/rafr.py): `rafr.py`
- [Coverage utilities](https://github.com/muhammademmadsiddiqui/ra-fr/blob/main/utils/cp_utils.py): `utils/cp_utils.py`

### Result analysis

- [Retrieval analysis](https://github.com/muhammademmadsiddiqui/ra-fr/tree/main/Visualizations): `Visualizations`

### Other components

- **Researcher**
- **Face restoration tools**

## Connections

- Researcher → IMFDB preparation: organizes images (evidence: `README.md`)
- IMFDB preparation → IMFDB metadata: precedes metadata (evidence: `README.md`)
- IMFDB metadata → IMFDB dataset: prepares dataset (evidence: `README.md`)
- Researcher → SCFace preparation: prepares images (evidence: `README.md`)
- SCFace preparation → SCFace dataset: prepares dataset (evidence: `README.md`)
- Face restoration tools → SCFace preparation: restores faces (evidence: `README.md`)
- Researcher → Train and eval runner: starts training (evidence: `README.md`)
- Train and eval runner → Data loading: configures loaders (evidence: `run.py`)
- Train and eval runner → Metric learning: starts training (evidence: `run.py`)
- Data loading → IMFDB dataset: loads dataset (evidence: `lightning_modules/datamodule.py`)
- Data loading → SCFace dataset: loads dataset (evidence: `lightning_modules/datamodule.py`)
- Metric learning → Model selection: selects model (evidence: `lightning_modules/lightning.py`)
- Model selection → R50-GeM: provides architecture (evidence: `networks/__init__.py`)
- Model selection → ViTB-DN-GeM: provides architecture (evidence: `README.md`)
- Model selection → ViTB-DN-GGeM: provides architecture (evidence: `README.md`)
- R50-GeM → Pooling functions: uses pooling (evidence: `networks/network.py`)
- ViTB-DN-GeM → Pooling functions: uses pooling (evidence: `networks/ViTB-DN-GeM.py`)
- Metric learning → Metric losses: computes loss (evidence: `lightning_modules/lightning.py`)
- Metric losses → Loss functions: delegates calculations (evidence: `losses/loss.py`)
- Researcher → RAFR uncertainty: applies RAFR (evidence: `README.md`)
- RAFR uncertainty → Nearest-neighbor retrieval: searches neighbors (evidence: `rafr.py`)
- RAFR uncertainty → Coverage utilities: uses coverage metrics (evidence: `rafr.py`)
- Researcher → Retrieval analysis: analyzes results (evidence: `README.md`)