# bgiraudr/facerec architecture

> Architecture diagram of the GitHub repository bgiraudr/facerec, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bgiraudr/facerec
- Repository: https://github.com/bgiraudr/facerec

## Overview

##### Main Components
- Mobile Application (Android) – This is the host environment.
- UI Layer – Represented by Android activities (MainActivity, FindResultsActivity, ManageFacesActivity) and fragments (MainFragment, FindFragment). Also include the various adapters (e.g., MainFaceAdapter, MatchingResultAdapter, PersonAdapter) used to populate UI elements.
- Data Layer – Includes the domain models (Face, PairResults, Person) and persistence implemented through Room (FaceRecDatabase, FaceDAO, PersonDAO, PersonWithFacesEntity). This layer manages data storage and retrieval.
- Model and Inference Layer – The utilization of the FaceNet model. Note that the model file (facenet_xnn.pte) is meant to reside in the assets, and the native library (libexecutorch.so) is used for executing the model. Also, the “models” folder contains a Python script (facenet_casia_webfaces_xnn.py) used to generate these resources.
- Build/Configuration – The build.gradle.kts files, gradle configurations, and other scripts indicate that Gradle is being used to build the project. While not part of the run-time components, they’re important for understanding how the system is packaged and deployed.
- External Dependencies – References include Material 3 (MDC-Android), the Facenet implementation (e.g., the Davidsandberg and facenet-pytorch repos), and Executorch for model execution.

##### Relationships and Interactions
- UI Components (Activities, Fragments, Adapters, and ViewModels) interact with the Data Layer. For example, user input that starts a face recognition process will trigger calls from an Activity which may go through a SharedViewModel, eventually reaching the Room database or invoking native inference via the Executorch library.
- The Data Layer (Room database) acts as the persistent storage for user faces, model results, and related entities.
- The Model and Inference Layer utilizes the preprocessed model file (facenet_xnn.pte) and the Executorch native library (libexecutorch.so) to perform computations. This component is integrated via JNI (as indicated by the presence of libexecutorch.so in jniLibs) and is fed with data from the UI/Data layers.
- The Build Layer orchestrates how these components are compiled and packaged.

##### Architectural Patterns & Design Principles
- Modular design: Separation of UI (activities/fragments), data management (Room and model classes), and business logic (potentially layered through ViewModels and adapters).
- MVVM Pattern: Evidenced by the use of SharedViewModel in the adapter packages and clear separation between UI controllers and data handling.
- Dependency Injection may be implied (even if not explicitly seen) to manage the interactions between these layers.
- Clear separation between native components (inference engine) and managed Android components.

##### Relevant Technologies and Frameworks
- Android SDK and Material 3 for UI styling.
- Kotlin/Java as main programming languages.
- Room for database abstraction.
- PyTorch Executorch for model handling.
- Gradle as the build tool.

## Diagram (Mermaid)

```mermaid
flowchart TD
    MA["Mobile Application"]:::build

    subgraph "Android Environment"
        subgraph "UI Layer"
            UI1["MainActivity"]:::ui
            UI2["FindResultsActivity"]:::ui
            UI3["ManageFacesActivity"]:::ui
            UI4["MainFragment"]:::ui
            UI5["FindFragment"]:::ui
            UI6["MainFaceAdapter"]:::ui
            UI7["MatchingResultAdapter"]:::ui
            UI8["PersonAdapter"]:::ui
            UI9["SharedViewModel"]:::ui
        end

        subgraph "Data Layer"
            DATA1["FaceRecDatabase"]:::data
            DATA2["FaceDAO"]:::data
            DATA3["PersonDAO"]:::data
            DATA4["FaceEntity"]:::data
            DATA5["PersonEntity"]:::data
            DATA6["PersonWithFacesEntity"]:::data
            DATA7["Face"]:::data
            DATA8["PairResults"]:::data
            DATA9["Person"]:::data
        end

        subgraph "Inference Engine"
            INF1["Executorch Library"]:::model
            INF2["Model Generator Script"]:::model
        end

        subgraph "Build & Configuration"
            BUILD1["Gradle Build Config"]:::build
        end
    end

    %% Relationships

    %% Mobile Application encapsulates UI interactions
    MA --> UI1
    MA --> UI2
    MA --> UI3

    %% UI Activities interact with SharedViewModel
    UI1 --> UI9
    UI2 --> UI9
    UI3 --> UI9

    %% UI Fragments interact with SharedViewModel
    UI4 --> UI9
    UI5 --> UI9

    %% UI Adapters are associated with SharedViewModel
    UI6 --> UI9
    UI7 --> UI9
    UI8 --> UI9

    %% SharedViewModel interacts with Data Layer and Inference Engine
    UI9 -->|"CRUD"| DATA1
    UI9 -->|"InferenceCall"| INF1

    %% Data Layer internal relationships
    DATA1 --> DATA2
    DATA1 --> DATA3
    DATA1 --> DATA4
    DATA1 --> DATA5
    DATA1 --> DATA6
    DATA7 --> DATA1
    DATA8 --> DATA1
    DATA9 --> DATA1

    %% Inference Engine internal relationship
    INF2 --> INF1

    %% Build & Configuration feeds into other layers
    BUILD1 --> UI9
    BUILD1 --> DATA1
    BUILD1 --> INF1

    %% Click Events
    click MA "https://github.com/bgiraudr/facerec/tree/main/app/src/main/java/com/tituya/facerec"
    click UI1 "https://github.com/bgiraudr/facerec/blob/main/app/src/main/java/com/tituya/facerec/MainActivity.kt"
    click UI2 "https://github.com/bgiraudr/facerec/blob/main/app/src/main/java/com/tituya/facerec/FindResultsActivity.kt"
    click UI3 "https://github.com/bgiraudr/facerec/blob/main/app/src/main/java/com/tituya/facerec/ManageFacesActivity.kt"
    click UI4 "https://github.com/bgiraudr/facerec/blob/main/app/src/main/java/com/tituya/facerec/ui/intent/MainFragment.kt"
    click UI5 "https://github.com/bgiraudr/facerec/blob/main/app/src/main/java/com/tituya/facerec/ui/intent/FindFragment.kt"
    click UI6 "https://github.com/bgiraudr/facerec/blob/main/app/src/main/java/com/tituya/facerec/adapter/MainFaceAdapter.kt"
    click UI7 "https://github.com/bgiraudr/facerec/blob/main/app/src/main/java/com/tituya/facerec/adapter/MatchingResultAdapter.kt"
    click UI8 "https://github.com/bgiraudr/facerec/blob/main/app/src/main/java/com/tituya/facerec/adapter/PersonAdapter.kt"
    click UI9 "https://github.com/bgiraudr/facerec/blob/main/app/src/main/java/com/tituya/facerec/adapter/SharedViewModel.kt"
    click DATA7 "https://github.com/bgiraudr/facerec/blob/main/app/src/main/java/com/tituya/facerec/data/model/Face.kt"
    click DATA8 "https://github.com/bgiraudr/facerec/blob/main/app/src/main/java/com/tituya/facerec/data/model/PairResults.kt"
    click DATA9 "https://github.com/bgiraudr/facerec/blob/main/app/src/main/java/com/tituya/facerec/data/model/Person.kt"
    click DATA1 "https://github.com/bgiraudr/facerec/blob/main/app/src/main/java/com/tituya/facerec/data/room/FaceRecDatabase.kt"
    click DATA2 "https://github.com/bgiraudr/facerec/blob/main/app/src/main/java/com/tituya/facerec/data/room/FaceDAO.kt"
    click DATA4 "https://github.com/bgiraudr/facerec/blob/main/app/src/main/java/com/tituya/facerec/data/room/FaceEntity.kt"
    click DATA3 "https://github.com/bgiraudr/facerec/blob/main/app/src/main/java/com/tituya/facerec/data/room/PersonDAO.kt"
    click DATA5 "https://github.com/bgiraudr/facerec/blob/main/app/src/main/java/com/tituya/facerec/data/room/PersonEntity.kt"
    click DATA6 "https://github.com/bgiraudr/facerec/blob/main/app/src/main/java/com/tituya/facerec/data/room/PersonWithFacesEntity.kt"
    click INF2 "https://github.com/bgiraudr/facerec/blob/main/models/facenet_casia_webfaces_xnn.py"
    click INF1 "https://github.com/bgiraudr/facerec/blob/main/app/libs/executorch.jar"
    click BUILD1 "https://github.com/bgiraudr/facerec/blob/main/app/build.gradle.kts"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef data fill:#90EE90,stroke:#000,stroke-width:1px
    classDef model fill:#FFA500,stroke:#000,stroke-width:1px
    classDef build fill:#D3D3D3,stroke:#000,stroke-width:1px
```
