# alok-kumar8765/biometric_face_caputure architecture

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

- Interactive diagram: https://gitdiagram.com/alok-kumar8765/biometric_face_caputure
- Repository: https://github.com/alok-kumar8765/biometric_face_caputure

## Overview

##### Project Type & Purpose
- This is a full-stack, production-ready Django package (a pluggable app) that provides a client-side face-liveness widget (JavaScript + MediaPipe) and a server-side validation pipeline (Python/Django + OpenCV).
- Purpose: let any Django 4.2+ app drop in a widget to capture a passport-style photo with blink/head-turn liveness checks, then POST a base64 image for brightness/blur/face detection validation.

##### Main Components
A. Client (Browser)
- MediaPipe FaceMesh SDK (via CDN)
- WidgetHTML + widget.js + widget.css
- JavaScript liveness flow (5-step guide + capture)
B. Django HTTP Layer
- `face_liveness_capture.django_integration.urls` → routes `/face-capture/` and `/face-capture/upload/`
- `widget_view(request)` → serves the widget template & CSRF cookie
- `upload_face(request)` → CSRF-protected POST entry point
C. Backend Pipeline
- detection.verify_liveness(image_base64)
– face_utils.decode_base64_image()
– face_utils.detect_face() (OpenCV Haar Cascade)
– validation.is_bright_enough()
– validation.is_not_blurry()
– face_utils.save_image() → `captured_faces/` or Django MEDIA_ROOT
- Returns JSON → `{success, path, message, error}`
D. Storage
- Local disk (`captured_faces/` by default) or configurable Django file storage
E. Demo/Test Project
- A minimal Django project (`test_project/`) illustrating integration
F. Packaging & Deployment
- Dockerfile + docker-compose.yml + nginx.conf
- GitHub Actions workflows (build, test, publish)
- docs/ for Installation, Deployment, REST API guides

##### Relationships & Data Flow
1. User loads `/face-capture/` → Browser fetches widget HTML/CSS/JS & MediaPipe scripts.
2. Browser requests camera → real-time FaceMesh landmarks → JS guides user through liveness checks.
3. On success → JS encodes photo as data URL → sends POST `/face-capture/upload/` + `X-CSRFToken`.
4. Django `upload_face` view receives request → calls `verify_liveness()`.
5. Backend pipeline processes image → saves file → returns JSON response.
6. JS parses JSON → displays success/failure to user.

##### Architectural Patterns & Design Principles
- MVC (Django views + templates) separation
- Clear C/S boundary: client does all heavy ML (MediaPipe), server only lightweight checks
- Pluggable app: isolated `django_integration` module, static & templates packaged via `MANIFEST.in`
- REST-style POST endpoint with CSRF protection
- Modular Python backend: detection, utils, validation layers

##### Technologies & Frameworks
- Frontend: HTML5, CSS, vanilla JavaScript, MediaPipe FaceMesh (CDN)
- Backend: Python 3.8+, Django ≥4.2, OpenCV (opencv-python), NumPy
- Packaging: setuptools/pyproject.toml, pip-editable installs
- CI/CD: GitHub Actions, Docker, docker-compose, optional Nginx reverse proxy

## Diagram (Mermaid)

```mermaid
graph TB
  %% Client Lane
  subgraph "Client (Browser)"
    MP["MediaPipe FaceMesh (CDN)"]:::external
    WH["Widget HTML"]:::frontend
    WC["Widget CSS"]:::frontend
    WJ["Widget JS"]:::frontend
  end

  %% Server Lane
  subgraph "Server (Django App)"
    subgraph "django_integration"
      Router["Django URL Router (/face-capture/)"]:::http
      View["upload_face View"]:::http
      Template["widget.html Template"]:::http
      Apps["App Config"]:::http
      Ser["Serializers"]:::http
      Tags["Template Tags"]:::http
    end
    Pipeline["Verify Liveness Pipeline"]:::backend
    Utils["Face Utils Module"]:::backend
    Val["Validation Module"]:::backend
    Config["Config Constants"]:::backend
  end

  %% Storage Lane
  subgraph "Storage"
    Storage[(Captured Faces Storage)]:::storage
  end

  %% Deployment Lane
  subgraph "Deployment"
    Docker["Docker & Nginx Configs"]:::deploy
    CI["GitHub Actions Workflows"]:::deploy
    Docs["Project Documentation"]:::deploy
  end

  %% Data Flow
  MP -->|"loads scripts"| WH
  WH -->|"applies styles"| WC
  WH -->|"executes logic"| WJ
  WJ -->|"captures landmarks"| MP
  WJ -->|"encode & POST base64+CSRF"| Router
  Router -->|"routes to upload_face"| View
  View -->|"calls verify_liveness()"| Pipeline
  Pipeline -->|"uses decode & detect"| Utils
  Pipeline -->|"uses brightness & blur checks"| Val
  Pipeline -->|"reads constants"| Config
  Pipeline -->|"saves image to"| Storage
  Storage -->|"returns file path"| View
  View -->|"returns JSON response"| WJ
  Template -->|"renders widget & CSRF"| WH
  Apps --> Template
  Ser --> View
  Tags --> Template

  %% Click Events
  click WH "https://github.com/alok-kumar8765/biometric_face_caputure/blob/main/face_liveness_capture/static/face_liveness_capture/html/widget.html"
  click WC "https://github.com/alok-kumar8765/biometric_face_caputure/blob/main/face_liveness_capture/static/face_liveness_capture/css/widget.css"
  click WJ "https://github.com/alok-kumar8765/biometric_face_caputure/blob/main/face_liveness_capture/static/face_liveness_capture/js/widget.js"
  click Router "https://github.com/alok-kumar8765/biometric_face_caputure/blob/main/face_liveness_capture/face_liveness_capture/django_integration/urls.py"
  click View "https://github.com/alok-kumar8765/biometric_face_caputure/blob/main/face_liveness_capture/face_liveness_capture/django_integration/views.py"
  click Template "https://github.com/alok-kumar8765/biometric_face_caputure/blob/main/face_liveness_capture/face_liveness_capture/django_integration/templates/face_liveness_capture/widget.html"
  click Apps "https://github.com/alok-kumar8765/biometric_face_caputure/blob/main/face_liveness_capture/face_liveness_capture/django_integration/apps.py"
  click Ser "https://github.com/alok-kumar8765/biometric_face_caputure/blob/main/face_liveness_capture/face_liveness_capture/django_integration/serializers.py"
  click Tags "https://github.com/alok-kumar8765/biometric_face_caputure/blob/main/face_liveness_capture/face_liveness_capture/django_integration/template_tags.py"
  click Pipeline "https://github.com/alok-kumar8765/biometric_face_caputure/blob/main/face_liveness_capture/face_liveness_capture/backend/detection.py"
  click Utils "https://github.com/alok-kumar8765/biometric_face_caputure/blob/main/face_liveness_capture/face_liveness_capture/backend/face_utils.py"
  click Val "https://github.com/alok-kumar8765/biometric_face_caputure/blob/main/face_liveness_capture/face_liveness_capture/backend/validation.py"
  click Config "https://github.com/alok-kumar8765/biometric_face_caputure/blob/main/face_liveness_capture/face_liveness_capture/config.py"
  click Storage "https://github.com/alok-kumar8765/biometric_face_caputure/tree/main/face_liveness_capture/test_project/captured_photos/"
  click Docker "https://github.com/alok-kumar8765/biometric_face_caputure/tree/main/face_liveness_capture/Dockerfile"
  click CI "https://github.com/alok-kumar8765/biometric_face_caputure/blob/main/face_liveness_capture/.github/workflows/docker-build.yml"
  click Docs "https://github.com/alok-kumar8765/biometric_face_caputure/blob/main/face_liveness_capture/docs/INSTALLATION.md"

  %% Styles
  classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
  classDef http fill:#E6FFEA,stroke:#22863A,color:#22863A
  classDef backend fill:#FFEFD5,stroke:#D2691E,color:#D2691E
  classDef storage fill:#FFF5B1,stroke:#DBAB09,color:#DBAB09
  classDef external fill:#F0F0F0,stroke:#6A737D,color:#6A737D
  classDef deploy fill:#F5F0FF,stroke:#6F42C1,color:#6F42C1
```
