# fiaabsinthe/mavfacesorter architecture

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

- Interactive diagram: https://gitdiagram.com/fiaabsinthe/mavfacesorter
- Repository: https://github.com/fiaabsinthe/mavfacesorter

## Overview

FaceSort has two distinct image-grouping workflows in the supplied sources: a command-line RetinaFace/DeepFace pipeline described by the README, and a Streamlit uploader using InsightFace embeddings and DBSCAN in app.py. Both detect faces, associate them with images, group images, and produce downloadable or on-disk results. The app excerpt omits some UI and file-handling lines, so its uncertain internal wiring is not expanded.

Main entry points: [`app.py`](https://github.com/fiaabsinthe/mavfacesorter/blob/main/app.py) (Streamlit interface), [`facesort.py`](https://github.com/fiaabsinthe/mavfacesorter/blob/main/facesort.py) (CLI orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_cli_main["CLI orchestrator<br/>[facesort.py]"]
  node_scan["Image scan<br/>[facesort.py]"]
  node_extract["Face extraction<br/>[facesort.py]"]
  node_match["Face matching<br/>[facesort.py]"]
  node_assign["Person assignments<br/>[facesort.py]"]
end

subgraph group_web["Web workflow"]
  node_web_ui["Streamlit interface<br/>[app.py]"]
  node_detect["Face detection<br/>[app.py]"]
  node_embeddings["Face embeddings<br/>[app.py]"]
  node_cluster["Face clustering<br/>[app.py]"]
end

subgraph group_vision["Vision services"]
  node_retina["RetinaFace"]
  node_deepface["DeepFace verification"]
  node_insightface["InsightFace analysis"]
  node_dbscan["DBSCAN"]
end

subgraph group_results["Grouping and results"]
  node_sort["Folder sorting<br/>[facesort.py]"]
  node_cli_files[("Image and output folders<br/>[facesort.py]")]
  node_web_files[("Uploaded and output files<br/>[app.py]")]
  node_web_groups["Person folders<br/>[app.py]"]
  node_archive["ZIP download<br/>[app.py]"]
end

node_cli_user(("CLI user"))
node_web_user(("Photo uploader"))

node_cli_user -->|"runs"| node_cli_main
node_cli_main -->|"calls"| node_scan
node_scan -->|"reads images"| node_cli_files
node_cli_main -->|"calls"| node_extract
node_extract -->|"extracts faces"| node_retina
node_extract -->|"checks faces"| node_match
node_match -->|"verifies identity"| node_deepface
node_match -->|"records matches"| node_assign
node_cli_main -->|"calls"| node_sort
node_sort -->|"reads assignments"| node_assign
node_sort -->|"copies images"| node_cli_files
node_web_user -->|"uploads photos"| node_web_ui
node_web_ui -->|"saves uploads"| node_web_files
node_web_ui -->|"starts sorting"| node_detect
node_detect -->|"reads images"| node_web_files
node_detect -->|"detects faces"| node_insightface
node_detect -->|"collects embeddings"| node_embeddings
node_web_ui -->|"clusters embeddings"| node_cluster
node_cluster -->|"reads embeddings"| node_embeddings
node_cluster -->|"fits clusters"| node_dbscan
node_web_ui -->|"creates groups"| node_web_groups
node_web_groups -->|"copies grouped images"| node_web_files
node_web_ui -->|"builds archive"| node_archive
node_archive -->|"reads output files"| node_web_files
node_web_ui -->|"offers download"| node_web_user

click node_cli_main "https://github.com/fiaabsinthe/mavfacesorter/blob/main/facesort.py"
click node_scan "https://github.com/fiaabsinthe/mavfacesorter/blob/main/facesort.py"
click node_extract "https://github.com/fiaabsinthe/mavfacesorter/blob/main/facesort.py"
click node_match "https://github.com/fiaabsinthe/mavfacesorter/blob/main/facesort.py"
click node_assign "https://github.com/fiaabsinthe/mavfacesorter/blob/main/facesort.py"
click node_sort "https://github.com/fiaabsinthe/mavfacesorter/blob/main/facesort.py"
click node_cli_files "https://github.com/fiaabsinthe/mavfacesorter/blob/main/facesort.py"
click node_web_ui "https://github.com/fiaabsinthe/mavfacesorter/blob/main/app.py"
click node_web_files "https://github.com/fiaabsinthe/mavfacesorter/blob/main/app.py"
click node_detect "https://github.com/fiaabsinthe/mavfacesorter/blob/main/app.py"
click node_embeddings "https://github.com/fiaabsinthe/mavfacesorter/blob/main/app.py"
click node_cluster "https://github.com/fiaabsinthe/mavfacesorter/blob/main/app.py"
click node_web_groups "https://github.com/fiaabsinthe/mavfacesorter/blob/main/app.py"
click node_archive "https://github.com/fiaabsinthe/mavfacesorter/blob/main/app.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_cli_main,node_scan,node_extract,node_match,node_assign,node_cli_user toneBlue
class node_web_ui,node_detect,node_embeddings,node_cluster toneAmber
class node_retina,node_deepface,node_insightface,node_dbscan toneMint
class node_sort,node_cli_files,node_web_files,node_web_groups,node_archive toneRose
class node_web_user toneIndigo
```

## Components

### CLI workflow

- [CLI orchestrator](https://github.com/fiaabsinthe/mavfacesorter/blob/main/facesort.py): `facesort.py`
- [Image scan](https://github.com/fiaabsinthe/mavfacesorter/blob/main/facesort.py): `facesort.py`
- [Face extraction](https://github.com/fiaabsinthe/mavfacesorter/blob/main/facesort.py): `facesort.py`
- [Face matching](https://github.com/fiaabsinthe/mavfacesorter/blob/main/facesort.py): `facesort.py`
- [Person assignments](https://github.com/fiaabsinthe/mavfacesorter/blob/main/facesort.py): `facesort.py`

### Web workflow

- [Streamlit interface](https://github.com/fiaabsinthe/mavfacesorter/blob/main/app.py): `app.py`
- [Face detection](https://github.com/fiaabsinthe/mavfacesorter/blob/main/app.py): `app.py`
- [Face embeddings](https://github.com/fiaabsinthe/mavfacesorter/blob/main/app.py): `app.py`
- [Face clustering](https://github.com/fiaabsinthe/mavfacesorter/blob/main/app.py): `app.py`

### Vision services

- **RetinaFace**
- **DeepFace verification**
- **InsightFace analysis**
- **DBSCAN**

### Grouping and results

- [Folder sorting](https://github.com/fiaabsinthe/mavfacesorter/blob/main/facesort.py): `facesort.py`
- [Image and output folders](https://github.com/fiaabsinthe/mavfacesorter/blob/main/facesort.py): `facesort.py`
- [Uploaded and output files](https://github.com/fiaabsinthe/mavfacesorter/blob/main/app.py): `app.py`
- [Person folders](https://github.com/fiaabsinthe/mavfacesorter/blob/main/app.py): `app.py`
- [ZIP download](https://github.com/fiaabsinthe/mavfacesorter/blob/main/app.py): `app.py`

### Other components

- **CLI user**
- **Photo uploader**

## Connections

- CLI user → CLI orchestrator: runs
- CLI orchestrator → Image scan: calls
- Image scan → Image and output folders: reads images
- CLI orchestrator → Face extraction: calls
- Face extraction → RetinaFace: extracts faces
- Face extraction → Face matching: checks faces
- Face matching → DeepFace verification: verifies identity
- Face matching → Person assignments: records matches
- CLI orchestrator → Folder sorting: calls
- Folder sorting → Person assignments: reads assignments
- Folder sorting → Image and output folders: copies images
- Photo uploader → Streamlit interface: uploads photos
- Streamlit interface → Uploaded and output files: saves uploads
- Streamlit interface → Face detection: starts sorting
- Face detection → Uploaded and output files: reads images
- Face detection → InsightFace analysis: detects faces
- Face detection → Face embeddings: collects embeddings
- Streamlit interface → Face clustering: clusters embeddings
- Face clustering → Face embeddings: reads embeddings
- Face clustering → DBSCAN: fits clusters
- Streamlit interface → Person folders: creates groups
- Person folders → Uploaded and output files: copies grouped images
- Streamlit interface → ZIP download: builds archive
- ZIP download → Uploaded and output files: reads output files
- Streamlit interface → Photo uploader: offers download