# ashishgajare/face-id-blockchain-verification architecture

> Architecture diagram of the GitHub repository ashishgajare/face-id-blockchain-verification, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ashishgajare/face-id-blockchain-verification
- Repository: https://github.com/ashishgajare/face-id-blockchain-verification

## Overview

TraceFace accepts an image through its Streamlit UI or CLI, detects and embeds a face, searches for visually similar images, filters social candidates, and compares candidate faces against a similarity threshold. A verified match becomes a canonical verification record whose SHA-256 hash is submitted to Polygon Amoy and checked on-chain. The graph preserves the distinct discovery, comparison, record, and anchoring stages. Evidence is limited to the supplied excerpts and source index; unsampled subsystem details and some UI wiring are therefore not expanded.

Main entry points: [`face-blockchain-verification/verification/pipeline.py`](https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/verification/pipeline.py) (Verification Pipeline), [`face-blockchain-verification/reverse_search/serpapi_client.py`](https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/reverse_search/serpapi_client.py) (Reverse Image Search), [`face-blockchain-verification/blockchain/contract.py`](https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/blockchain/contract.py) (Contract Client), [`face-blockchain-verification/blockchain/client.py`](https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/blockchain/client.py) (Polygon Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_ui["Streamlit Studio<br/>[app.py]"]
  node_cli["CLI<br/>[main.py]"]
  node_pipeline["Verification Pipeline<br/>[pipeline.py]"]
  node_config["Runtime Config<br/>[config.py]"]
end

subgraph group_faces["Face Analysis"]
  node_detector["Face Detector<br/>[detector.py]"]
  node_embedding["Embedding Tools<br/>[embedding.py]"]
  node_similarity["Similarity Gate<br/>[similarity.py]"]
end

subgraph group_discovery["Search Discovery"]
  node_reverse["Reverse Image Search<br/>[serpapi_client.py]"]
  node_parser["Search Result Parser<br/>[result_parser.py]"]
  node_social["Social Candidate Filter<br/>[social_filter.py]"]
end

subgraph group_records["Verification Records"]
  node_record["Record Model<br/>[models.py]"]
  node_hashing["Record Hashing<br/>[hashing.py]"]
end

subgraph group_chain["Blockchain Anchoring"]
  node_blockclient["Polygon Client<br/>[client.py]"]
  node_contractclient["Contract Client<br/>[contract.py]"]
  node_contract["Verification Contract"]
  node_chainrecord["Blockchain Record Helpers<br/>[record.py]"]
end

node_user(("Image Submitter"))
node_search(("SerpApi"))
node_upload(("Temporary Image Host"))
node_candidate(("Candidate Image Sites"))
node_polygon(("Polygon Amoy RPC"))

node_user -->|"uploads image"| node_ui
node_user -->|"provides image"| node_cli
node_ui -->|"runs verification"| node_pipeline
node_cli -->|"runs verification"| node_pipeline
node_pipeline -->|"reads settings"| node_config
node_pipeline -->|"detects faces"| node_detector
node_pipeline -->|"normalizes vectors"| node_embedding
node_pipeline -->|"searches image"| node_reverse
node_reverse -->|"uploads image"| node_upload
node_reverse -->|"requests results"| node_search
node_pipeline -->|"parses results"| node_parser
node_pipeline -->|"filters candidates"| node_social
node_pipeline -->|"downloads images"| node_candidate
node_pipeline -->|"compares faces"| node_similarity
node_pipeline -->|"builds record"| node_record
node_pipeline -->|"hashes record"| node_hashing
node_hashing -->|"serializes model"| node_record
node_pipeline -->|"connects client"| node_blockclient
node_pipeline -->|"stores and checks"| node_contractclient
node_contractclient -->|"sends transactions"| node_blockclient
node_blockclient -->|"uses RPC"| node_polygon
node_contractclient -->|"calls contract"| node_contract

click node_ui "https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/ui/app.py"
click node_cli "https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/main.py"
click node_pipeline "https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/verification/pipeline.py"
click node_config "https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/config.py"
click node_detector "https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/face/detector.py"
click node_embedding "https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/face/embedding.py"
click node_similarity "https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/face/similarity.py"
click node_reverse "https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/reverse_search/serpapi_client.py"
click node_parser "https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/reverse_search/result_parser.py"
click node_social "https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/reverse_search/social_filter.py"
click node_record "https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/verification/models.py"
click node_hashing "https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/verification/hashing.py"
click node_blockclient "https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/blockchain/client.py"
click node_contractclient "https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/blockchain/contract.py"
click node_contract "https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/contracts/FaceVerification.sol"
click node_chainrecord "https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/blockchain/record.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_ui,node_cli,node_pipeline,node_config toneBlue
class node_detector,node_embedding,node_similarity toneAmber
class node_reverse,node_parser,node_social,node_search toneMint
class node_record,node_hashing toneRose
class node_blockclient,node_contractclient,node_contract,node_chainrecord,node_user,node_upload,node_candidate,node_polygon toneIndigo
```

## Components

### User Interfaces

- [Streamlit Studio](https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/ui/app.py): `face-blockchain-verification/ui/app.py`
- [CLI](https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/main.py): `face-blockchain-verification/main.py`
- [Verification Pipeline](https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/verification/pipeline.py): `face-blockchain-verification/verification/pipeline.py`
- [Runtime Config](https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/config.py): `face-blockchain-verification/config.py`

### Face Analysis

- [Face Detector](https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/face/detector.py): `face-blockchain-verification/face/detector.py`
- [Embedding Tools](https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/face/embedding.py): `face-blockchain-verification/face/embedding.py`
- [Similarity Gate](https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/face/similarity.py): `face-blockchain-verification/face/similarity.py`

### Search Discovery

- [Reverse Image Search](https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/reverse_search/serpapi_client.py): `face-blockchain-verification/reverse_search/serpapi_client.py`
- [Search Result Parser](https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/reverse_search/result_parser.py): `face-blockchain-verification/reverse_search/result_parser.py`
- [Social Candidate Filter](https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/reverse_search/social_filter.py): `face-blockchain-verification/reverse_search/social_filter.py`

### Verification Records

- [Record Model](https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/verification/models.py): `face-blockchain-verification/verification/models.py`
- [Record Hashing](https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/verification/hashing.py): `face-blockchain-verification/verification/hashing.py`

### Blockchain Anchoring

- [Polygon Client](https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/blockchain/client.py): `face-blockchain-verification/blockchain/client.py`
- [Contract Client](https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/blockchain/contract.py): `face-blockchain-verification/blockchain/contract.py`
- [Verification Contract](https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/contracts/FaceVerification.sol): `contracts/FaceVerification.sol`
- [Blockchain Record Helpers](https://github.com/ashishgajare/face-id-blockchain-verification/blob/master/face-blockchain-verification/blockchain/record.py): `face-blockchain-verification/blockchain/record.py`

### Other components

- **Image Submitter**
- **SerpApi**
- **Temporary Image Host**
- **Candidate Image Sites**
- **Polygon Amoy RPC**

## Connections

- Image Submitter → Streamlit Studio: uploads image (evidence: `face-blockchain-verification/ui/app.py`)
- Image Submitter → CLI: provides image (evidence: `face-blockchain-verification/main.py`)
- Streamlit Studio → Verification Pipeline: runs verification (evidence: `face-blockchain-verification/ui/app.py`)
- CLI → Verification Pipeline: runs verification (evidence: `face-blockchain-verification/main.py`)
- Verification Pipeline → Runtime Config: reads settings (evidence: `face-blockchain-verification/verification/pipeline.py`)
- Verification Pipeline → Face Detector: detects faces (evidence: `face-blockchain-verification/verification/pipeline.py`)
- Verification Pipeline → Embedding Tools: normalizes vectors (evidence: `face-blockchain-verification/verification/pipeline.py`)
- Verification Pipeline → Reverse Image Search: searches image (evidence: `face-blockchain-verification/verification/pipeline.py`)
- Reverse Image Search → Temporary Image Host: uploads image (evidence: `face-blockchain-verification/reverse_search/serpapi_client.py`)
- Reverse Image Search → SerpApi: requests results (evidence: `face-blockchain-verification/reverse_search/serpapi_client.py`)
- Verification Pipeline → Search Result Parser: parses results (evidence: `face-blockchain-verification/verification/pipeline.py`)
- Verification Pipeline → Social Candidate Filter: filters candidates (evidence: `face-blockchain-verification/verification/pipeline.py`)
- Verification Pipeline → Candidate Image Sites: downloads images (evidence: `face-blockchain-verification/verification/pipeline.py`)
- Verification Pipeline → Similarity Gate: compares faces (evidence: `face-blockchain-verification/verification/pipeline.py`)
- Verification Pipeline → Record Model: builds record (evidence: `face-blockchain-verification/verification/pipeline.py`)
- Verification Pipeline → Record Hashing: hashes record (evidence: `face-blockchain-verification/verification/pipeline.py`)
- Record Hashing → Record Model: serializes model (evidence: `face-blockchain-verification/verification/hashing.py`)
- Verification Pipeline → Polygon Client: connects client (evidence: `face-blockchain-verification/verification/pipeline.py`)
- Verification Pipeline → Contract Client: stores and checks (evidence: `face-blockchain-verification/verification/pipeline.py`)
- Contract Client → Polygon Client: sends transactions (evidence: `face-blockchain-verification/blockchain/contract.py`)
- Polygon Client → Polygon Amoy RPC: uses RPC (evidence: `face-blockchain-verification/blockchain/client.py`)
- Contract Client → Verification Contract: calls contract (evidence: `face-blockchain-verification/blockchain/contract.py`)
