# limkhashing/face-matching architecture

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

- Interactive diagram: https://gitdiagram.com/limkhashing/face-matching
- Repository: https://github.com/limkhashing/face-matching

## Overview

##### Project Type and Purpose
- This is a Python/Flask full-stack application that compares a face provided in a still image against faces extracted from a short video. Its goal is to return a JSON response indicating if the faces match, along with a confidence score.
- The README clarifies its use of various processing techniques (image resizing/compression, frame extraction, rotation fixes, etc.) and the involvement of multiple external software components (e.g., Tesseract, FFMPEG, OpenCV) that are essential parts of the processing pipeline.

##### File Structure
- Top-Level Components:
- app.py: Likely the entry point for starting the Flask web server.
- Dockerfile, Procfile, Aptfile, .dockerignore, etc.: Indicate the project is containerized and also deployable (Heroku was once supported, now deprecated), ensuring that deployment architectures are considered.
- README.md and requirements.txt: Provide installation and dependency details.
- src directory: Contains the core application logic including subdirectories for OCR tasks (OCR folder), CPBD processing (cpbd folder), and other utilities (face_processing.py, orientation_processing.py, sharpness_processing.py). These handle the image/video processing, face detection/comparison, and possibly pre/post-processing steps.
- static and templates directories: Support the frontend aspects of the web application (e.g., HTML views and assets).
- tests directory: Contains test cases that validate critical components of the application.

##### Extract Architectural Insights from the README
- The application workflow is clearly explained in the README:
- Upload a picture and a video.
- Resize or compress images if necessary.
- Extract frames from video and pre-process them (rotation, compression).
- Compare the uploaded image against multiple extracted frames.
- Return JSON with matching information.
- Key external technologies include: Face_Recognition Python package, Flask for the web framework, OpenCV & FFMPEG for media processing, and Docker for containerization.

a. Main Components:
- Web Frontend: Represented by the HTML templates and static assets, serving the client interface.
- Flask Web Server (app.py): Acts as the central controller for handling HTTP requests and routing.
- Processing Modules:
- Face Comparison Module (face_processing.py)
- OCR Processing Module (src/OCR/ folder includes crop_morphology.py, ocr_process.py, regex_patterns.py)
- CPBD Module (src/cpbd/) for possibly assessing image sharpness or similar metrics.
- Orientation & Sharpness Processing: Handled by orientation_processing.py and sharpness_processing.py.
- External Dependencies/Services:
- Face_Recognition Library
- OpenCV
- FFMPEG
- Tesseract (external dependency, installed separately)
- Data Flow: Include sample data (illustrated in sample_data/) and illustrate testing (tests directory) if desired.
- Docker Containerization: Note the Dockerfile and related deployment files to recognize that the entire app runs inside a container environment.

b. Relationships and Interactions:
- A user initiates requests via the frontend (browser) to the Flask web server.
- The Flask server (app.py) routes requests to appropriate backend processing modules.
- For an upload request: The image and video files are passed to various processing modules:
- Pre-processing (compression and orientation corrections)
- Frame extraction (possibly via FFMPEG)
- Face detection and matching using the Face_Recognition library
- Processors call helper functions in the OCR and CPBD modules as needed.
- Results (confidence percentage, match status) are compiled and sent back as JSON responses.

c. Architectural Patterns and Design Principles:
- Separation of Concerns: The system separates the concerns of web presentation (static/templates) from business logic and processing (app.py and src/ modules).
- Modular Design: Each processing task (OCR, CPBD, face processing, etc.) is encapsulated in its own module, easing testing and maintainability.
- Containerization: The use of Docker indicates a deployment pattern that encapsulates the application and its dependencies for consistent behavior across environments.
- External Dependency Integration: Clear integration with various libraries and external binaries (FFMPEG, Tesseract) for specialized processing steps.

d. Relevant Technologies, Frameworks, and Libraries:
- Flask for the web server.
- Python libraries: face_recognition, OpenCV.
- External processing software: FFMPEG, Tesseract, and cmake (via Aptfile for installing additional packages).
- Testing frameworks and CI/CD integration (Travis CI, Codecov as seen from the badges).

##### Elements
- Web UI components (e.g., blue rectangles for HTML/templates),
- Backend modules (e.g., green ovals for processing modules),
- Including notes about the purpose of each module next to its representation.

##### Detailed Component Breakdown
- Client/User: Browser initiating image and video uploads.
- Frontend Layer: Static files and templates served by Flask.
- Flask Application (app.py): Serves as the entry point, handling HTTP requests/responses.
- Business Logic Modules (inside src/):
- OCR Subsystem: Contains crop_morphology.py, ocr_process.py, regex_patterns.py.
- CPBD Subsystem: Includes cpbd module files (compute.py, octave.py).
- Face Processing: Modules for face_processing, orientation_processing, sharpness_processing.
- Additional Utilities: Constants, delete_files, etc.
- External Dependencies:
- Face_Recognition library
- OpenCV
- FFMPEG and Tesseract (illustrate these as prerequisites or external services).
- Docker Container: Represent the system encapsulated within a Docker container, including configuration files like Dockerfile, and mention the container orchestration potential.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client/Frontend"
        Browser["User Browser"]:::frontend
        StaticAssets["Static Assets"]:::frontend
        Templates["Templates"]:::frontend
    end

    subgraph "Backend"
        FlaskApp["Flask App (app.py)"]:::backend
        subgraph "Processing Modules"
            OCRModule["OCR Module"]:::backend
            CPBDModule["CPBD Module"]:::backend
            FaceProcessing["Face Processing Module"]:::backend
            OrientationProcessing["Orientation Processing"]:::backend
            SharpnessProcessing["Sharpness Processing"]:::backend
        end
        subgraph "External Dependencies"
            FaceRecognition["Face_Recognition Library"]:::external
            OpenCV["OpenCV Library"]:::external
            FFMPEG["FFMPEG"]:::external
            Tesseract["Tesseract"]:::external
        end
    end

    subgraph "Deployment & Testing"
         DockerfileNode["Dockerfile"]:::deployment
         DockerignoreNode[".dockerignore"]:::deployment
         AptfileNode["Aptfile"]:::deployment
         ProcfileNode["Procfile"]:::deployment
         TestingSuite["Testing Suite"]:::deployment
    end

    %% Data Flow
    Browser -->|"HTTP_Request"| FlaskApp
    FlaskApp -->|"FaceMatch"| FaceProcessing
    FlaskApp -->|"OCR"| OCRModule
    FlaskApp -->|"CPBD"| CPBDModule
    FlaskApp -->|"Orientation"| OrientationProcessing
    FlaskApp -->|"Sharpness"| SharpnessProcessing
    FlaskApp -->|"FrameExtraction"| FFMPEG

    OCRModule -->|"Use"| Tesseract
    CPBDModule -->|"Use"| OpenCV
    FaceProcessing -->|"Use"| FaceRecognition
    FaceProcessing -->|"Use"| OpenCV
    OrientationProcessing -->|"Use"| OpenCV
    SharpnessProcessing -->|"Use"| OpenCV

    FaceProcessing -->|"MatchResult"| FlaskApp
    OCRModule -->|"TextData"| FlaskApp
    CPBDModule -->|"SharpnessScore"| FlaskApp
    OrientationProcessing -->|"CorrectOrientation"| FlaskApp
    SharpnessProcessing -->|"SharpnessData"| FlaskApp

    FlaskApp -->|"JSON_Response"| Templates
    Templates -->|"Render"| Browser

    %% Click Events
    click StaticAssets "https://github.com/limkhashing/face-matching/tree/master/static"
    click Templates "https://github.com/limkhashing/face-matching/blob/master/templates/index.html"
    click FlaskApp "https://github.com/limkhashing/face-matching/blob/master/app.py"
    click OCRModule "https://github.com/limkhashing/face-matching/tree/master/src/OCR"
    click CPBDModule "https://github.com/limkhashing/face-matching/tree/master/src/cpbd"
    click FaceProcessing "https://github.com/limkhashing/face-matching/blob/master/src/face_processing.py"
    click OrientationProcessing "https://github.com/limkhashing/face-matching/blob/master/src/orientation_processing.py"
    click SharpnessProcessing "https://github.com/limkhashing/face-matching/blob/master/src/sharpness_processing.py"
    click DockerfileNode "https://github.com/limkhashing/face-matching/tree/master/Dockerfile"
    click DockerignoreNode "https://github.com/limkhashing/face-matching/blob/master/.dockerignore"
    click AptfileNode "https://github.com/limkhashing/face-matching/tree/master/Aptfile"
    click ProcfileNode "https://github.com/limkhashing/face-matching/tree/master/Procfile"
    click TestingSuite "https://github.com/limkhashing/face-matching/tree/master/tests"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#1e88e5,stroke-width:2px;
    classDef backend fill:#a5d6a7,stroke:#43a047,stroke-width:2px;
    classDef external fill:#ef9a9a,stroke:#e53935,stroke-width:2px;
    classDef deployment fill:#ffe082,stroke:#ffb300,stroke-width:2px;
```
