# batman1103/local_face_search_system architecture

> Architecture diagram of the GitHub repository batman1103/local_face_search_system, 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/batman1103/local_face_search_system
- Repository: https://github.com/batman1103/local_face_search_system

## Overview

FaceSearch Desktop is a local photo-face search application. A user connects a photo folder, which the backend scans and incrementally indexes by detecting faces, storing embeddings and metadata; the user then submits a query photo and receives matching originals. The graph distinguishes desktop launch/UI mediation, indexing and search, and persistence. The sampled source establishes these backend calls; other README-level product claims are not available beyond the minimal README title.

Main entry points: [`facesearch-desktop/backend/app/main.py`](https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/backend/app/main.py) (HTTP API), [`facesearch-desktop/frontend/src/main.jsx`](https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/frontend/src/main.jsx) (Search UI), [`facesearch-desktop/backend/app/services/indexer.py`](https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/backend/app/services/indexer.py) (Incremental indexer), [`facesearch-desktop/desktop/main.js`](https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/desktop/main.js) (Electron host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop interface"]
  node_desktop_app["Electron host<br/>[main.js]"]
  node_preload["IPC bridge<br/>[preload.js]"]
  node_frontend["Search UI<br/>[main.jsx]"]
end

subgraph group_backend["Backend workflows"]
  node_api["HTTP API<br/>[main.py]"]
  node_config["Runtime config<br/>[config.py]"]
  node_face_engine["Face detection<br/>[face_engine.py]"]
end

subgraph group_indexing["Library indexing"]
  node_indexer["Incremental indexer<br/>[indexer.py]"]
  node_watcher["Folder watcher<br/>[watcher.py]"]
end

subgraph group_storage["Local persistence"]
  node_vector_store[("FAISS vectors<br/>[vector_store.py]")]
  node_metadata_db[("Image metadata<br/>[database.py]")]
end

node_user(("User"))
node_photo_folder["Photo folder"]
node_query_photo["Query photo"]
node_image_files["Original images"]
node_desktop_os["Desktop services"]

node_user -->|"uses"| node_frontend
node_desktop_app -->|"starts backend"| node_api
node_desktop_app -->|"loads UI"| node_frontend
node_frontend -->|"requests folder"| node_preload
node_preload -->|"invokes IPC"| node_desktop_app
node_desktop_app -->|"returns folder"| node_frontend
node_frontend -->|"calls API"| node_api
node_api -->|"loads settings"| node_config
node_api -->|"reads/writes"| node_metadata_db
node_api -->|"loads/searches"| node_vector_store
node_api -->|"detects query faces"| node_face_engine
node_api -->|"starts scans"| node_indexer
node_api -->|"starts/stops watch"| node_watcher
node_indexer -->|"scans/reads"| node_photo_folder
node_indexer -->|"detects faces"| node_face_engine
node_indexer -->|"adds embeddings"| node_vector_store
node_indexer -->|"records image/faces"| node_metadata_db
node_watcher -->|"enqueues changes"| node_indexer
node_watcher -->|"marks missing"| node_metadata_db
node_api -->|"searches query vectors"| node_vector_store
node_api -->|"resolves matches"| node_metadata_db
node_api -->|"serves original"| node_image_files
node_frontend -->|"requests match images"| node_api
node_api -->|"opens image/folder"| node_desktop_os
node_frontend -->|"requests open action"| node_api

click node_desktop_app "https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/desktop/main.js"
click node_preload "https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/desktop/preload.js"
click node_frontend "https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/frontend/src/main.jsx"
click node_api "https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/backend/app/main.py"
click node_config "https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/backend/app/config.py"
click node_face_engine "https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/backend/app/services/face_engine.py"
click node_indexer "https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/backend/app/services/indexer.py"
click node_watcher "https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/backend/app/services/watcher.py"
click node_vector_store "https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/backend/app/services/vector_store.py"
click node_metadata_db "https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/backend/app/db/database.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_desktop_app,node_preload,node_frontend,node_user toneBlue
class node_api,node_config,node_face_engine toneAmber
class node_indexer,node_watcher toneMint
class node_vector_store,node_metadata_db toneRose
class node_photo_folder,node_query_photo,node_image_files,node_desktop_os toneIndigo
```

## Components

### Desktop interface

- [Electron host](https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/desktop/main.js): `facesearch-desktop/desktop/main.js`
- [IPC bridge](https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/desktop/preload.js): `facesearch-desktop/desktop/preload.js`
- [Search UI](https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/frontend/src/main.jsx): `facesearch-desktop/frontend/src/main.jsx`

### Backend workflows

- [HTTP API](https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/backend/app/main.py): `facesearch-desktop/backend/app/main.py`
- [Runtime config](https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/backend/app/config.py): `facesearch-desktop/backend/app/config.py`
- [Face detection](https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/backend/app/services/face_engine.py): `facesearch-desktop/backend/app/services/face_engine.py`

### Library indexing

- [Incremental indexer](https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/backend/app/services/indexer.py): `facesearch-desktop/backend/app/services/indexer.py`
- [Folder watcher](https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/backend/app/services/watcher.py): `facesearch-desktop/backend/app/services/watcher.py`

### Local persistence

- [FAISS vectors](https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/backend/app/services/vector_store.py): `facesearch-desktop/backend/app/services/vector_store.py`
- [Image metadata](https://github.com/batman1103/local_face_search_system/blob/main/facesearch-desktop/backend/app/db/database.py): `facesearch-desktop/backend/app/db/database.py`

### Other components

- **User**
- **Photo folder**
- **Query photo**
- **Original images**
- **Desktop services**

## Connections

- User → Search UI: uses
- Electron host → HTTP API: starts backend
- Electron host → Search UI: loads UI
- Search UI → IPC bridge: requests folder
- IPC bridge → Electron host: invokes IPC
- Electron host → Search UI: returns folder
- Search UI → HTTP API: calls API
- HTTP API → Runtime config: loads settings
- HTTP API → Image metadata: reads/writes
- HTTP API → FAISS vectors: loads/searches
- HTTP API → Face detection: detects query faces
- HTTP API → Incremental indexer: starts scans
- HTTP API → Folder watcher: starts/stops watch
- Incremental indexer → Photo folder: scans/reads
- Incremental indexer → Face detection: detects faces
- Incremental indexer → FAISS vectors: adds embeddings
- Incremental indexer → Image metadata: records image/faces
- Folder watcher → Incremental indexer: enqueues changes
- Folder watcher → Image metadata: marks missing
- HTTP API → FAISS vectors: searches query vectors
- HTTP API → Image metadata: resolves matches
- HTTP API → Original images: serves original
- Search UI → HTTP API: requests match images
- HTTP API → Desktop services: opens image/folder
- Search UI → HTTP API: requests open action