# beginnercoder52/mmm-face-reco-dnn architecture

> Architecture diagram of the GitHub repository beginnercoder52/mmm-face-reco-dnn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/beginnercoder52/mmm-face-reco-dnn
- Repository: https://github.com/beginnercoder52/mmm-face-reco-dnn

## Overview

##### Project Type and Overall Purpose
- This is a node-based MagicMirror² module for facial recognition. It leverages OpenCV, dlib, and face_recognition alongside Python and Node.js tools to detect faces and control module visibility based on recognition.
- The module runs face detection in the background to show and hide different displays (e.g., agenda, notifications) according to whether no face, an unrecognized face, or a known face is present.

##### Analyzing the File Structure
- Top-level files: configuration files (.eslintrc.json, .prettierrc.json, etc.), core module file (MMM-Face-Reco-DNN.js), node_helper.js for backend operations.
- The model folder holds the haarcascade XML file and (after running encode) will contain face encoding data.
- The tools/ folder includes several Python scripts for encoding images, recognition, taking pictures, and assorted utility functions – these represent key processing components.
- The translations folder covers localization support, demonstrating that multi-language capability is included.

##### Main Components
a. User Interaction and MagicMirror² Interface
- MagicMirror configuration and module activation (the module itself does not directly render content but controls the visibility of other modules).
b. Face Detection and Recognition Engine
- Face detection using Haarcascade (OpenCV-based) and deep recognition using dnn which ultimately checks against precomputed encodings.
- Python scripts in tools (encode.py, recognition.py, etc.) that process image data, compute facial embeddings, and perform the recognition functions.
c. Dataset and Model Management
- The dataset directory holds user images for training/embedding.
- The model directory contains detection model files and eventually the pickle file with encoded faces.
d. Application Configuration and Dependency Management
- Configuration settings in package.json and README that detail dependencies, including OpenCV, dlib, face_recognition, numpy, and others.
- Environment set up, including instructions for virtual environments and system package installations.

##### Relationships and Data Flow
- The camera feed (via picamera2) captures images, which are then piped into the recognition pipeline.
- Python scripts (within the tools folder) process these images and generate or update face encodings.
- The module’s node_helper.js acts as the bridge to send notifications (USERS_LOGIN, USERS_LOGOUT, etc.) back to MagicMirror².
- There are clear boundaries between static configuration (README, config.js setup) and runtime data processing.

##### Architectural Patterns and Technologies
- Separation of Concerns: JavaScript handles module management and integration with MagicMirror², while Python handles image processing and facial recognition.
- Modular Design: Each tool and configuration file is grouped logically (e.g., models, tools, translations) to accommodate future extensibility.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Làm cho các khối có không gian rộng rãi

    %% External Nodes
    CAMERA["Camera Feed (picamera2)"]:::external
    EXT_DEP["External Dependencies (OpenCV,dlib,face_recognition,numpy)"]:::external

    %% Face Detection and Recognition Engine
    subgraph "Face Detection and Recognition Engine"
        HAAR["Haarcascade Detection"]:::python
        TAKE["Take Pictures Script"]:::python
        RECOG["Recognition Script"]:::python
        ENCODE["Encode Script"]:::python
        UTIL["Python Utilities (arguments.py,helper.py,image.py,print.py)"]:::python
        MODEL_REPO["Model Repository"]:::model
    end

    %% MagicMirror² Module
    subgraph "MagicMirror² Module"
        NH["node_helper.js"]:::nodejs
        UI["MMM-Face-Reco-DNN.js"]:::nodejs
    end

    %% Configuration and Localization
    subgraph "Configuration and Localization"
        PKG["package.json"]:::config
        ESLINT[".eslintrc.json"]:::config
        PRETTI[".prettierrc.json"]:::config
        README["README.md"]:::config
        TRANS["Translations"]:::trans
    end

    %% Data Flow Connections
    CAMERA -->|"capture"| TAKE
    TAKE -->|"process"| RECOG
    ENCODE -->|"updateModel"| MODEL_REPO
    EXT_DEP -->|"deps"| RECOG
    RECOG -->|"notif"| NH
    NH -->|"updateUI"| UI

    %% Configuration influences
    PKG -->|"config"| UI
    ESLINT -->|"config"| UI
    PRETTI -->|"config"| UI
    README -->|"doc"| UI
    TRANS -->|"i18n"| UI
    PKG -->|"config"| RECOG

    %% Click Events
    click UI "https://github.com/beginnercoder52/mmm-face-reco-dnn/blob/master/MMM-Face-Reco-DNN.js"
    click NH "https://github.com/beginnercoder52/mmm-face-reco-dnn/blob/master/node_helper.js"
    click HAAR "https://github.com/beginnercoder52/mmm-face-reco-dnn/blob/master/model/haarcascade_frontalface_default.xml"
    click ENCODE "https://github.com/beginnercoder52/mmm-face-reco-dnn/blob/master/tools/encode.py"
    click RECOG "https://github.com/beginnercoder52/mmm-face-reco-dnn/blob/master/tools/recognition.py"
    click TAKE "https://github.com/beginnercoder52/mmm-face-reco-dnn/blob/master/tools/takesPictures.py"
    click UTIL "https://github.com/beginnercoder52/mmm-face-reco-dnn/tree/master/tools/utils/"
    click MODEL_REPO "https://github.com/beginnercoder52/mmm-face-reco-dnn/tree/master/model/"
    click PKG "https://github.com/beginnercoder52/mmm-face-reco-dnn/blob/master/package.json"
    click ESLINT "https://github.com/beginnercoder52/mmm-face-reco-dnn/blob/master/.eslintrc.json"
    click PRETTI "https://github.com/beginnercoder52/mmm-face-reco-dnn/blob/master/.prettierrc.json"
    click README "https://github.com/beginnercoder52/mmm-face-reco-dnn/blob/master/README.md"
    click TRANS "https://github.com/beginnercoder52/mmm-face-reco-dnn/tree/master/translations/"

    %% Styles
    classDef python fill:#a9dfbf,stroke:#28a745,stroke-width:2px;
    classDef nodejs fill:#aed6f1,stroke:#1f77b4,stroke-width:2px;
    classDef config fill:#f9e79f,stroke:#f1c40f,stroke-width:2px;
    classDef trans fill:#d2b4de,stroke:#9b59b6,stroke-width:2px;
    classDef external fill:#f5b7b1,stroke:#e74c3c,stroke-width:2px;
    classDef model fill:#fbc531,stroke:#e1a32b,stroke-width:2px;
```
