.. _architecture:

*************************************
Architecture
*************************************

Be sure to take a minute to learn the FindFace Enterprise Server architecture. This knowledge is essential for the FindFace Enterprise Server deployment, integration, maintenance and troubleshooting.

.. rubric:: In this chapter:

.. contents::
   :local:




Architectural Elements
==============================

FindFace Enterprise Server consists of the following architectural elements:

* FindFace core,
* (optional) application modules.

  .. note::
     Application modules are not available in the basic configuration. To learn more about building a turnkey application with the help of our team, contact our experts by info@ntechlab.com.


The FindFace core includes the following components:

   .. image:: /_static/architecture.png

+------------------------------+--------------------------------------------------------------------------------------+--------------------------------------------+
| Component                    | Description                                                                          | Vendor                                     |
+==============================+======================================================================================+============================================+
| findface-extraction-api      | A service which uses neural networks to detect a face in an image and extract a      | Ntech Lab own deployment                   |
|                              | face biometric sample (feature vector), gender, age, emotions and other face         |                                            |
|                              | features. CPU- or GPU-acceleration.                                                  |                                            | 
+------------------------------+--------------------------------------------------------------------------------------+                                            |
| findface-sf-api              | A service that implements HTTP API for face detection and                            |                                            |
|                              | face recognition.                                                                    |                                            |
+------------------------------+--------------------------------------------------------------------------------------+                                            |
| findface-tarantool-server    | A service that provides interaction between the ``findface-sf-api`` service and the  |                                            |
|                              | biometric database (database that stores face biometric samples)                     |                                            |
|                              | powered by Tarantool.                                                                |                                            |
+------------------------------+--------------------------------------------------------------------------------------+                                            |
| findface-upload              | An NginX-based web server used as a storage for original images, thumbnails and      |                                            |
|                              | normalized face images.                                                              |                                            |
+------------------------------+--------------------------------------------------------------------------------------+                                            |
| findface-facerouter          | A service used to define processing directives for detected faces.                   |                                            |
+------------------------------+--------------------------------------------------------------------------------------+                                            |
| findface-video-manager       | A service, part of the video face detection module, that is used for managing the    |                                            |
|                              | video face detection functionality, configuring the video face detector              |                                            |
|                              | settings and specifying the list of to-be-processed video streams.                   |                                            |
+------------------------------+--------------------------------------------------------------------------------------+                                            |
| findface-video-worker        | A service, part of the video face detection module, which recognizes a face in video |                                            |
|                              | and posts its normalized image, full frame and metadata (such as the camera ID and   |                                            |
|                              | detection time) to the ``findface-facerouter`` service for further processing        |                                            |
|                              | according to given directives. CPU- or GPU-acceleration.                             |                                            |
+------------------------------+--------------------------------------------------------------------------------------+                                            |
| findface-ntls                | A license server which interfaces with the NtechLab Global License Server or USB     |                                            |
|                              | dongle to verify the FindFace Enterprise Server license.                             |                                            |
+------------------------------+--------------------------------------------------------------------------------------+--------------------------------------------+
| Tarantool                    | Third-party software which implements the biometric database that stores extracted   | `Tarantool <https://tarantool.io/en/>`_    |
|                              | biometric samples (feature vectors).                                                 |                                            |
+------------------------------+--------------------------------------------------------------------------------------+--------------------------------------------+
| etcd                         | Third-party software that implements a distributed key-value store for               | `etcd <https://github.com/etcd-io/etcd>`_  |
|                              | ``findface-video-manager``. Used as a coordination service in the distributed        |                                            |
|                              | system, providing the video face detector with fault tolerance.                      |                                            |
+------------------------------+--------------------------------------------------------------------------------------+--------------------------------------------+
| NginX                        | Third-party software which implements the system web interfaces.                     | `nginx <https://www.nginx.com>`_           |
+------------------------------+--------------------------------------------------------------------------------------+--------------------------------------------+
| memcached                    | Third-party software which implements a distributed memory caching system.           | `memcached <https://memcached.org>`_       |
|                              | Used by ``findface-extraction-api`` as a temporary storage for extracted face        |                                            | 
|                              | biometric samples before they are written to the biometric database powered by       |                                            |
|                              | Tarantool.                                                                           |                                            |
+------------------------------+--------------------------------------------------------------------------------------+--------------------------------------------+


.. seealso::
   :ref:`components`


Single- and Multi-Host Deployment
==================================

Depending on your system characteristics and performance requirements, you can opt to install FindFace Enterprise Server standalone or in a cluster environment:

+----------------+-----------------------------------------------------------------------------------------------------------------------------+
| Deployment     | Recommendation                                                                                                              |
+================+=============================================================================================================================+
| Standalone     | You can deploy FindFace Enterprise Server and neural network models on a single host (standalone)                           |
|                | if the number of faces in the database does not exceed some 1,000,000 (recommended limit). This variant makes it easier to  | 
|                | start deployment and cater to basic requirements of your system.                                                            | 
+----------------+-----------------------------------------------------------------------------------------------------------------------------+
| Cluster        | If the number of faces in the database does exceed 1,000,000, we recommend you to deploy FindFace Enterprise Server         |
|                | in a cluster environment. In this case, FindFace Enterprise Server                                                          |
|                | components will be distributed across several hosts. This is a medium and large deployment which can be scaled almost       |
|                | infinitely. It will also suit professional high load projects with severe requirements to performance.                      |  
+----------------+-----------------------------------------------------------------------------------------------------------------------------+

If you opt for the cluster deployment, we offer you one of the following deployment schemes: 

* Deploy FindFace Enterprise Server standalone and distribute additional ``findface-video-worker`` components across multiple hosts.
* Distribute the FindFace Enterprise Server components across multiple hosts. If necessary, set up load balancing.


CPU- and GPU-acceleration
==========================================

The ``findface-extraction-api`` and ``findface-video-worker`` services can be either CPU- or GPU-based. During installation from the developer-friendly :ref:`installer <installer>`, you will have an opportunity to choose the acceleration type you need.  

If you opt to install FindFace Enterprise Server from the :ref:`repository package <step-by-step>`, deploy the ``findface-extraction-api`` and ``findface-video-worker`` packages on a CPU-based server, and the ``findface-extraction-api-gpu`` and/or ``findface-video-worker-gpu`` packages on a GPU-based server. 

.. important::
   Refer to :ref:`requirements` when choosing hardware configuration. 

.. important::
   If the resolution of a camera(s) in use is more than 1280x720px, it is strongly recommended to use the GPU-accelerated package ``findface-video-worker-gpu``.


.. important::
   The :ref:`face liveness detection <liveness>` can be enabled only on the GPU-accelerated video face detector ``findface-video-worker-gpu``.