# recognito-vision/linux-facerecognition-facelivenessdetection architecture

> Architecture diagram of the GitHub repository recognito-vision/linux-facerecognition-facelivenessdetection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/recognito-vision/linux-facerecognition-facelivenessdetection
- Repository: https://github.com/recognito-vision/linux-facerecognition-facelivenessdetection

## Overview

##### Project Type and Purpose
- This is a demo repository showcasing on-premise face-based services (recognition, liveness detection, 1:N identification and a “lite” SDK) all built to run on a Linux server.
- Each demo is packaged as a Docker-ready microservice exposing both a REST API (Flask) and a web UI (Gradio). Under the hood they all invoke a common C++-based Face Engine (via OpenVINO) to perform inference.

##### File Structure Highlights
- Top-level demo folders:
– FaceSDK-Lite-Demo: C++ sample (CMake + main.cpp) + Python wrappers (Flask, Gradio)
– Recognition-Demo, LivenessDetection-Demo, Identification(1:N)-Demo: share identical structure
- Each demo contains:
– Dockerfile (builds container with OpenVINO, custom kernels, Python deps)
– dependency/openvino (IR models + custom VPU kernels)
– flask/app.py (REST endpoints)
– install.sh, run_demo.sh
– license.txt
- README.md ties it all together and documents Docker commands & runtime ports (8000 API, 7860 UI).

##### Key Architectural Components
a. Physical Host & Container Platform
– Ubuntu 20.04/22.04 server running Docker Engine
b. Microservices (one per demo)
– Docker Container
- Flask API Layer
- Gradio UI Layer
- Face Engine client library (C++ wrapper or Python binding)
- OpenVINO runtime + custom VPU kernels + IR models
- License file (mounted volume)
c. Shared Services / Artifacts
– Face Engine Core (compiled C++ .so or static lib)
– Model files (face detection, feature extractor, liveness net, attribute net)
– Face database (for 1:N identification)
– Temporary storage for input/output images (optional)
d. External Integrations
– eKYC system or CCTV ingest (HTTP/REST calls to Flask endpoints)
– Client applications consuming REST API or embedded Gradio UI

##### Inter-Component Relationships & Data Flow
1. User/browser → Gradio UI (port 7860)
2. Gradio → Flask REST API (localhost:8000)
3. Flask handler → Face Engine binding
4. Face Engine → OpenVINO runtime with IR models + custom kernels
5. OpenVINO → Model inference → returns results (features, liveness score, attributes)
6. For 1:N identification: Engine queries face database → nearest-neighbor search → returns candidate IDs
7. Flask → JSON response → Gradio or external client

##### Architectural Patterns & Design Principles
- Microservices: each demo is an isolated container/service
- Separation of concerns: UI (Gradio) / API (Flask) / Inference Engine (C++)
- Containerization: Dockerfiles ensure reproducible environment (OpenVINO, Python, C++ SDK)
- Plug-and-play: drop in new IR models or kernels under dependency/openvino
- Dual UI layer: easily swap or disable Gradio vs Flask-only via command-line flags

- Clear labels for each container/demo (Recognition, Liveness, 1:N ID, Lite)
- Sub-components inside each (Gradio UI, Flask API, C++ Engine, OpenVINO + Models)
- Notes about ports (8000, 7860) and volume mounts (license.txt, models)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Integrations
    Browser["User Browser"]:::external
    eKYC["eKYC System"]:::external
    CCTV["CCTV Ingest"]:::external

    %% FaceSDK-Lite Demo Container
    subgraph "FaceSDK-Lite Demo (Docker Container)" 
        direction TB
        UI_Lite["Gradio UI<br/>port 7860"]:::ui
        API_Lite["Flask API<br/>port 8000"]:::api
        Engine_Lite["C++ Face Engine Client"]:::engine
        OpenVINO_Lite["OpenVINO Runtime + IR Models"]:::engine
        License_Lite["license.txt Volume"]:::volume
        UI_Lite -->|calls REST| API_Lite
        API_Lite -->|invokes| Engine_Lite
        Engine_Lite -->|runs inference| OpenVINO_Lite
    end

    %% Recognition Demo Container
    subgraph "Recognition Demo (Docker Container)" 
        direction TB
        UI_Recog["Gradio UI<br/>port 7860"]:::ui
        API_Recog["Flask API<br/>port 8000"]:::api
        Engine_Recog["C++ Face Engine Client"]:::engine
        OpenVINO_Recog["OpenVINO Runtime + IR Models"]:::engine
        License_Recog["license.txt Volume"]:::volume
        UI_Recog -->|calls REST| API_Recog
        API_Recog -->|invokes| Engine_Recog
        Engine_Recog -->|runs inference| OpenVINO_Recog
    end

    %% Liveness Detection Demo Container
    subgraph "Liveness Detection Demo (Docker Container)" 
        direction TB
        UI_Liveness["Gradio UI<br/>port 7860"]:::ui
        API_Liveness["Flask API<br/>port 8000"]:::api
        Engine_Liveness["C++ Face Engine Client"]:::engine
        OpenVINO_Liveness["OpenVINO Runtime + IR Models"]:::engine
        License_Liveness["license.txt Volume"]:::volume
        UI_Liveness -->|calls REST| API_Liveness
        API_Liveness -->|invokes| Engine_Liveness
        Engine_Liveness -->|runs inference| OpenVINO_Liveness
    end

    %% Identification (1:N) Demo Container
    subgraph "Identification (1:N) Demo (Docker Container)" 
        direction TB
        UI_ID["Gradio UI<br/>port 7860"]:::ui
        API_ID["Flask API<br/>port 8000"]:::api
        Engine_ID["C++ Face Engine Client"]:::engine
        OpenVINO_ID["OpenVINO Runtime + IR Models"]:::engine
        License_ID["license.txt Volume"]:::volume
        DB["Face Database"]:::db
        UI_ID -->|calls REST| API_ID
        API_ID -->|invokes| Engine_ID
        Engine_ID -->|runs inference| OpenVINO_ID
        Engine_ID -->|NN search| DB
    end

    %% Connections from External
    Browser --> UI_Lite
    Browser --> UI_Recog
    Browser --> UI_Liveness
    Browser --> UI_ID
    eKYC --> API_Lite
    eKYC --> API_Recog
    eKYC --> API_Liveness
    eKYC --> API_ID
    CCTV --> API_Lite
    CCTV --> API_Recog
    CCTV --> API_Liveness
    CCTV --> API_ID

    %% Shared Core Library
    FaceCore["Face Engine Core (.so/.lib)"]:::shared
    FaceCore -.-> Engine_Lite
    FaceCore -.-> Engine_Recog
    FaceCore -.-> Engine_Liveness
    FaceCore -.-> Engine_ID

    %% Click Events for FaceSDK-Lite Demo
    click UI_Lite "https://github.com/recognito-vision/linux-facerecognition-facelivenessdetection/blob/main/FaceSDK-Lite-Demo/gradio/app.py"
    click API_Lite "https://github.com/recognito-vision/linux-facerecognition-facelivenessdetection/blob/main/FaceSDK-Lite-Demo/flask/app.py"
    click Engine_Lite "https://github.com/recognito-vision/linux-facerecognition-facelivenessdetection/blob/main/FaceSDK-Lite-Demo/cpp_demo/main.cpp"
    click OpenVINO_Lite "https://github.com/recognito-vision/linux-facerecognition-facelivenessdetection/tree/main/FaceSDK-Lite-Demo/Dockerfile"
    click License_Lite "https://github.com/recognito-vision/linux-facerecognition-facelivenessdetection/blob/main/FaceSDK-Lite-Demo/license.txt"
    click FaceCore "https://github.com/recognito-vision/linux-facerecognition-facelivenessdetection/blob/main/FaceSDK-Lite-Demo/cpp_demo/faceengine.h"

    %% Click Events for Recognition Demo
    click UI_Recog "https://github.com/recognito-vision/linux-facerecognition-facelivenessdetection/blob/main/Recognition-Demo/gradio/app.py"
    click API_Recog "https://github.com/recognito-vision/linux-facerecognition-facelivenessdetection/blob/main/Recognition-Demo/flask/app.py"
    click Engine_Recog "https://github.com/recognito-vision/linux-facerecognition-facelivenessdetection/tree/main/Recognition-Demo/Dockerfile"
    click OpenVINO_Recog "https://github.com/recognito-vision/linux-facerecognition-facelivenessdetection/blob/main/Recognition-Demo/dependency/openvino/plugins.xml"

    %% Click Events for Liveness Detection Demo
    click UI_Liveness "https://github.com/recognito-vision/linux-facerecognition-facelivenessdetection/blob/main/LivenessDetection-Demo/gradio/app.py"
    click API_Liveness "https://github.com/recognito-vision/linux-facerecognition-facelivenessdetection/blob/main/LivenessDetection-Demo/flask/app.py"
    click Engine_Liveness "https://github.com/recognito-vision/linux-facerecognition-facelivenessdetection/tree/main/LivenessDetection-Demo/Dockerfile"
    click OpenVINO_Liveness "https://github.com/recognito-vision/linux-facerecognition-facelivenessdetection/blob/main/LivenessDetection-Demo/dependency/openvino/cache.json"

    %% Click Events for Identification Demo
    click UI_ID "https://github.com/recognito-vision/linux-facerecognition-facelivenessdetection/blob/main/Identification(1:N)-Demo/gradio/app.py"
    click API_ID "https://github.com/recognito-vision/linux-facerecognition-facelivenessdetection/blob/main/Identification(1:N)-Demo/flask/app.py"
    click Engine_ID "https://github.com/recognito-vision/linux-facerecognition-facelivenessdetection/tree/main/Identification(1:N)-Demo/Dockerfile"
    click DB "https://github.com/recognito-vision/linux-facerecognition-facelivenessdetection/blob/main/Identification(1:N)-Demo/README.md"

    %% Styles
    classDef ui fill:#c8e6c9,stroke:#2e7d32,color:#2e7d32;
    classDef api fill:#bbdefb,stroke:#1976d2,color:#0d47a1;
    classDef engine fill:#ffe0b2,stroke:#ef6c00,color:#e65100;
    classDef external fill:#e1bee7,stroke:#8e24aa,color:#6a1b9a;
    classDef shared fill:#f0f4c3,stroke:#9e9d24,color:#827717;
    classDef db fill:#d7ccc8,stroke:#5d4037,color:#3e2723;
    classDef volume fill:#f5f5f5,stroke:#616161,color:#212121;
```
