# hrishikeshchandi/visitor-face-matching architecture

> Architecture diagram of the GitHub repository hrishikeshchandi/visitor-face-matching, 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/hrishikeshchandi/visitor-face-matching
- Repository: https://github.com/hrishikeshchandi/visitor-face-matching

## Overview

The product is a Streamlit visitor face-recognition app. Its main workflow accepts an image, generates an embedding, searches the FAISS index, verifies the nearest known face, maps that image filename to a requisition number, and retrieves visitor records from MySQL for display. A separate setup workflow builds the initial embeddings and index; batch uploads add embeddings to the existing index. The README documents these capabilities, while the sampled source shows the runtime calls. The graph omits unshown implementation details and external library internals.

Main entry points: [`main.py`](https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/main.py) (Streamlit app), [`generate_embeddings.py`](https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/generate_embeddings.py) (Initial index builder), [`files_handler.py`](https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/files_handler.py) (Batch upload processor), [`config.py`](https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/config.py) (Known visitor images)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Visitor interface"]
  node_app["Streamlit app<br/>[main.py]"]
  node_recognition_results["Recognition results<br/>[main.py]"]
  node_upload_storage[("Temporary uploads<br/>[config.py]")]
end

subgraph group_recognition["Face recognition"]
  node_query_embedding["Query embedding<br/>[face_matching.py]"]
  node_face_search["Similarity search<br/>[face_matching.py]"]
  node_face_verification["Face verification<br/>[face_matching.py]"]
  node_requisition_mapping["Requisition mapping<br/>[face_matching.py]"]
end

subgraph group_data["Visitor data"]
  node_known_images[("Known visitor images<br/>[config.py]")]
  node_faiss_index[("FAISS index<br/>[config.py]")]
  node_visitor_records["Visitor records<br/>[database.py]"]
  node_embedding_store[("Saved embeddings<br/>[config.py]")]
end

subgraph group_setup["Index setup and updates"]
  node_settings["Environment settings<br/>[config.py]"]
  node_initial_builder["Initial index builder"]
  node_batch_processor["Batch upload processor<br/>[files_handler.py]"]
end

node_visitor(("Visitor"))
node_mysql[("MySQL database")]

node_visitor -->|"uploads images"| node_app
node_app -->|"saves query image"| node_upload_storage
node_app -->|"requests recognition"| node_query_embedding
node_query_embedding -->|"searches embedding"| node_face_search
node_face_search -->|"reads and searches"| node_faiss_index
node_face_search -->|"checks nearest face"| node_face_verification
node_face_verification -->|"verifies against image"| node_known_images
node_face_verification -->|"returns verified match"| node_requisition_mapping
node_requisition_mapping -->|"returns requisition number"| node_app
node_app -->|"requests records"| node_visitor_records
node_visitor_records -->|"queries records"| node_mysql
node_app -->|"displays records"| node_recognition_results
node_visitor -->|"provides dataset images"| node_initial_builder
node_initial_builder -->|"reads image files"| node_known_images
node_initial_builder -->|"saves embeddings"| node_embedding_store
node_initial_builder -->|"builds and saves"| node_faiss_index
node_app -->|"submits batch uploads"| node_batch_processor
node_batch_processor -->|"adds image files"| node_known_images
node_batch_processor -->|"loads and updates"| node_embedding_store
node_batch_processor -->|"loads and updates"| node_faiss_index
node_settings -.->|"configures location"| node_known_images
node_settings -.->|"configures location"| node_faiss_index
node_settings -.->|"configures location"| node_embedding_store

click node_app "https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/main.py"
click node_recognition_results "https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/main.py"
click node_upload_storage "https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/config.py"
click node_settings "https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/config.py"
click node_query_embedding "https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/face_matching.py"
click node_face_search "https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/face_matching.py"
click node_face_verification "https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/face_matching.py"
click node_requisition_mapping "https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/face_matching.py"
click node_known_images "https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/config.py"
click node_faiss_index "https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/config.py"
click node_visitor_records "https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/database.py"
click node_initial_builder "https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/generate_embeddings.py"
click node_batch_processor "https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/files_handler.py"
click node_embedding_store "https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/config.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_app,node_recognition_results,node_upload_storage toneBlue
class node_query_embedding,node_face_search,node_face_verification,node_requisition_mapping,node_mysql toneAmber
class node_known_images,node_faiss_index,node_visitor_records,node_embedding_store toneMint
class node_settings,node_initial_builder,node_batch_processor toneRose
class node_visitor toneIndigo
```

## Components

### Visitor interface

- [Streamlit app](https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/main.py): `main.py`
- [Recognition results](https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/main.py): `main.py`
- [Temporary uploads](https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/config.py): `config.py`

### Face recognition

- [Query embedding](https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/face_matching.py): `face_matching.py`
- [Similarity search](https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/face_matching.py): `face_matching.py`
- [Face verification](https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/face_matching.py): `face_matching.py`
- [Requisition mapping](https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/face_matching.py): `face_matching.py`

### Visitor data

- [Known visitor images](https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/config.py): `config.py`
- [FAISS index](https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/config.py): `config.py`
- [Visitor records](https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/database.py): `database.py`
- [Saved embeddings](https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/config.py): `config.py`

### Index setup and updates

- [Environment settings](https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/config.py): `config.py`
- [Initial index builder](https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/generate_embeddings.py): `generate_embeddings.py`
- [Batch upload processor](https://github.com/hrishikeshchandi/visitor-face-matching/blob/main/files_handler.py): `files_handler.py`

### Other components

- **Visitor**
- **MySQL database**

## Connections

- Visitor → Streamlit app: uploads images (evidence: `README.md`)
- Streamlit app → Temporary uploads: saves query image (evidence: `main.py`)
- Streamlit app → Query embedding: requests recognition (evidence: `main.py`)
- Query embedding → Similarity search: searches embedding (evidence: `face_matching.py`)
- Similarity search → FAISS index: reads and searches (evidence: `face_matching.py`)
- Similarity search → Face verification: checks nearest face (evidence: `face_matching.py`)
- Face verification → Known visitor images: verifies against image (evidence: `face_matching.py`)
- Face verification → Requisition mapping: returns verified match (evidence: `face_matching.py`)
- Requisition mapping → Streamlit app: returns requisition number (evidence: `main.py`)
- Streamlit app → Visitor records: requests records (evidence: `main.py`)
- Visitor records → MySQL database: queries records (evidence: `database.py`)
- Streamlit app → Recognition results: displays records (evidence: `main.py`)
- Visitor → Initial index builder: provides dataset images (evidence: `README.md`)
- Initial index builder → Known visitor images: reads image files (evidence: `generate_embeddings.py`)
- Initial index builder → Saved embeddings: saves embeddings (evidence: `generate_embeddings.py`)
- Initial index builder → FAISS index: builds and saves (evidence: `generate_embeddings.py`)
- Streamlit app → Batch upload processor: submits batch uploads (evidence: `main.py`)
- Batch upload processor → Known visitor images: adds image files (evidence: `files_handler.py`)
- Batch upload processor → Saved embeddings: loads and updates (evidence: `files_handler.py`)
- Batch upload processor → FAISS index: loads and updates (evidence: `files_handler.py`)
- Environment settings → Known visitor images: configures location (evidence: `config.py`)
- Environment settings → FAISS index: configures location (evidence: `config.py`)
- Environment settings → Saved embeddings: configures location (evidence: `config.py`)