# mridulpant2010/face_recognition architecture

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

- Interactive diagram: https://gitdiagram.com/mridulpant2010/face_recognition
- Repository: https://github.com/mridulpant2010/face_recognition

## Overview

This repository combines a face-recognition RAG pipeline with standalone neural-network and margin-loss implementations. The principal workflow is to discover and split identity-labeled images, embed gallery faces, persist a searchable index and probe set, then retrieve identity matches for queries; the CLI also exposes evaluation. The README is empty, and evaluation, configuration, and some model files were not sampled, so their internal behavior and wiring are not inferred.

Main entry points: [`src/face_recognition/rag/run_pipeline.py`](https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/run_pipeline.py) (Pipeline CLI), [`src/face_recognition/rag/pipeline/ingest.py`](https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/pipeline/ingest.py) (Ingestion), [`src/face_recognition/rag/implementations/arcface_embedder.py`](https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/implementations/arcface_embedder.py) (ArcFace embedder), [`src/face_recognition/rag/implementations/faiss_vector_store.py`](https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/implementations/faiss_vector_store.py) (FAISS store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rag["RAG pipeline"]
  node_runner["Pipeline CLI<br/>[run_pipeline.py]"]
  node_ingest["Ingestion<br/>[ingest.py]"]
  node_retrieve["Face retriever<br/>[retrieve.py]"]
  node_evaluate["Evaluation<br/>[evaluate.py]"]
  node_config["Pipeline configuration<br/>[config.py]"]
end

subgraph group_embed["Embedding"]
  node_embed_iface["Embedder interface<br/>[base_embedder.py]"]
  node_arc_embed["ArcFace embedder"]
end

subgraph group_models["Model components"]
  node_iresnet["IResNet architecture<br/>[iresnet.py]"]
  node_vit["Vision Transformer<br/>[vit.py]"]
  node_losses["Margin losses<br/>[losses.py]"]
  node_imagetext["Image-text model<br/>[imagetextmodel.py]"]
end

subgraph group_state["Index and data"]
  node_store_iface["Store interface"]
  node_faiss[("FAISS store")]
  node_dataset["Identity image dataset"]
  node_index_files[("Saved index and metadata")]
  node_probe_file["Saved probe set"]
end

node_user(("CLI user"))
node_insightface["InsightFace runtime"]

node_user -->|"runs"| node_runner
node_runner -->|"runs ingestion"| node_ingest
node_runner -->|"runs evaluation"| node_evaluate
node_runner -->|"queries via"| node_retrieve
node_runner -->|"creates"| node_arc_embed
node_runner -->|"creates and loads"| node_faiss
node_ingest -->|"discovers images"| node_dataset
node_ingest -->|"embeds gallery"| node_arc_embed
node_ingest -->|"adds and saves"| node_faiss
node_ingest -->|"writes probe paths"| node_probe_file
node_arc_embed -->|"runs inference"| node_insightface
node_retrieve -->|"embeds query"| node_arc_embed
node_retrieve -->|"searches"| node_faiss
node_faiss -->|"reads and writes"| node_index_files
node_ingest -->|"reads settings"| node_config
node_retrieve -->|"reads defaults"| node_config
node_arc_embed -.->|"implements"| node_embed_iface
node_faiss -.->|"implements"| node_store_iface
node_runner -.->|"not evidenced"| node_iresnet
node_runner -.->|"not evidenced"| node_vit
node_runner -.->|"not evidenced"| node_losses
node_runner -.->|"not evidenced"| node_imagetext

click node_runner "https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/run_pipeline.py"
click node_ingest "https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/pipeline/ingest.py"
click node_retrieve "https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/pipeline/retrieve.py"
click node_evaluate "https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/pipeline/evaluate.py"
click node_embed_iface "https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/interfaces/base_embedder.py"
click node_arc_embed "https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/implementations/arcface_embedder.py"
click node_store_iface "https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/interfaces/base_vector_store.py"
click node_faiss "https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/implementations/faiss_vector_store.py"
click node_dataset "https://github.com/mridulpant2010/face_recognition/tree/main/src/dataset"
click node_config "https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/core/config.py"
click node_iresnet "https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/iresnet.py"
click node_vit "https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/vit.py"
click node_losses "https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/losses.py"
click node_imagetext "https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/imagetextmodel.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_runner,node_ingest,node_retrieve,node_evaluate,node_config,node_user toneBlue
class node_embed_iface,node_arc_embed toneAmber
class node_iresnet,node_vit,node_losses,node_imagetext toneMint
class node_store_iface,node_faiss,node_dataset,node_index_files,node_probe_file toneRose
class node_insightface toneIndigo
```

## Components

### RAG pipeline

- [Pipeline CLI](https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/run_pipeline.py): `src/face_recognition/rag/run_pipeline.py`
- [Ingestion](https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/pipeline/ingest.py): `src/face_recognition/rag/pipeline/ingest.py`
- [Face retriever](https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/pipeline/retrieve.py): `src/face_recognition/rag/pipeline/retrieve.py`
- [Evaluation](https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/pipeline/evaluate.py): `src/face_recognition/rag/pipeline/evaluate.py`
- [Pipeline configuration](https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/core/config.py): `src/face_recognition/rag/core/config.py`

### Embedding

- [Embedder interface](https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/interfaces/base_embedder.py): `src/face_recognition/rag/interfaces/base_embedder.py`
- [ArcFace embedder](https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/implementations/arcface_embedder.py): `src/face_recognition/rag/implementations/arcface_embedder.py`

### Model components

- [IResNet architecture](https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/iresnet.py): `src/face_recognition/iresnet.py`
- [Vision Transformer](https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/vit.py): `src/face_recognition/vit.py`
- [Margin losses](https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/losses.py): `src/face_recognition/losses.py`
- [Image-text model](https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/imagetextmodel.py): `src/face_recognition/imagetextmodel.py`

### Index and data

- [Store interface](https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/interfaces/base_vector_store.py): `src/face_recognition/rag/interfaces/base_vector_store.py`
- [FAISS store](https://github.com/mridulpant2010/face_recognition/blob/main/src/face_recognition/rag/implementations/faiss_vector_store.py): `src/face_recognition/rag/implementations/faiss_vector_store.py`
- [Identity image dataset](https://github.com/mridulpant2010/face_recognition/tree/main/src/dataset): `src/dataset`
- **Saved index and metadata**
- **Saved probe set**

### Other components

- **CLI user**
- **InsightFace runtime**

## Connections

- CLI user → Pipeline CLI: runs
- Pipeline CLI → Ingestion: runs ingestion
- Pipeline CLI → Evaluation: runs evaluation
- Pipeline CLI → Face retriever: queries via
- Pipeline CLI → ArcFace embedder: creates
- Pipeline CLI → FAISS store: creates and loads
- Ingestion → Identity image dataset: discovers images
- Ingestion → ArcFace embedder: embeds gallery
- Ingestion → FAISS store: adds and saves
- Ingestion → Saved probe set: writes probe paths
- ArcFace embedder → InsightFace runtime: runs inference
- Face retriever → ArcFace embedder: embeds query
- Face retriever → FAISS store: searches
- FAISS store → Saved index and metadata: reads and writes
- Ingestion → Pipeline configuration: reads settings
- Face retriever → Pipeline configuration: reads defaults
- ArcFace embedder → Embedder interface: implements
- FAISS store → Store interface: implements
- Pipeline CLI → IResNet architecture: not evidenced
- Pipeline CLI → Vision Transformer: not evidenced
- Pipeline CLI → Margin losses: not evidenced
- Pipeline CLI → Image-text model: not evidenced