# tanish-sarkar/real-time-facial-detection architecture

> Architecture diagram of the GitHub repository tanish-sarkar/real-time-facial-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tanish-sarkar/real-time-facial-detection
- Repository: https://github.com/tanish-sarkar/real-time-facial-detection

## Overview

This is a **single-node real-time computer vision + web streaming application**:
- **Input**: Local webcam frames (OpenCV).
- **Processing pipeline**: grayscale → Haar cascade face detection → Laplacian-variance blur scoring → annotate.
- **Output**: **Live MJPEG stream** served by **Flask** to a **browser**.
- **Side effects (parallel concerns)**: event-based frame saving (only when blurry) + timestamped logging.

- **Real-time frame pipeline** (hot path)
- **Streaming mechanism** (generator-based MJPEG)
- **Resource lifecycle** (camera ownership in generator)
- **Observability + event outputs** (logs + saved frames)
- **Local filesystem assets** (Haar cascade XML)

##### File-tree-driven architecture mapping (turn directories into components)

You effectively have **two entrypoints** (two “modes”):

##### What to extract from README (key runtime behaviors to reflect)
- **Generator-based MJPEG streaming** (core to Flask integration and performance).
- **Camera lifecycle handling** (camera opened/owned inside generator to avoid conflicts).
- **Event-based frame saving** (prevents I/O overload).
- **Cooldown logic** (avoids repeated captures).
- **Defensive programming** (avoid silent stream crashes).
- **Parallel outputs**: “saved and logged in parallel without interrupting the video stream.”

These are architectural concerns, not just implementation details—include them as labeled subcomponents or notes.

##### Side-effect branches (non-blocking outputs)
From the **Decision: BLURRY** node, branch to:
- **Cooldown Gate** (prevents repeated saves)
- If allowed → **Frame Saver** → `saved_frames/blur_YYYYMMDD_HHMMSS.jpg` (README mentions this; even if the folder isn’t in your current tree, model it as a filesystem sink).
- Also branch to:
- **Event Logger** → `logs/detections.log`

Important: visually indicate these are **side effects** that must not block the streaming loop. Use:
- a “non-blocking / best-effort” label, or
- a small “async-like” annotation (even if implemented synchronously, the design intent is “don’t interrupt the stream”).

- **Browser → Flask**: HTTP GET `/` and `/video_feed` (or similar)
- **Flask → Browser**: `multipart/x-mixed-replace` MJPEG stream
- **OpenCV → Asset**: loads Haar cascade XML from `assets/`
- **Pipeline → Filesystem**:
- append-only logging to `logs/detections.log`
- conditional image writes to `saved_frames/`

- “frames (numpy array)” for internal steps
- “JPEG bytes” after encoding
- “MJPEG multipart” for the network response

##### Architectural patterns/design principles to call out
- **Single-process streaming loop** with **generator** producing frames.
- **Event-driven side effects** (save/log only on blur).
- **Backpressure-friendly approach**: don’t accumulate frames; process latest frame and stream.
- **Separation of concerns**:
- Web serving (Flask)
- CV pipeline (OpenCV stages)
- Observability (logging)
- Persistence (frame saving)
- Configuration/assets (Haar XML)

Purpose: “Who talks to what?”
- Browser
- Flask app (on local machine)
- Webcam device
- Local filesystem (assets/logs/saved frames)

Purpose: “What are the major runtime components?”
- Flask server
- MJPEG generator
- CV pipeline components
- Logger + frame saver
- Assets

Purpose: “What happens per frame and when do we save/log?”
Show:
- → process → annotate → encode → yield
- if blur & cooldown ok → save + log

- `src/flask_app.py` next to the Flask/MJPEG components.
- `logs/detections.log` next to the logging sink.

##### What “most detailed” means here (separate into as many components as possible)
- Capture
- Grayscale
- Face detect (asset dependency)
- Blur score
- Threshold decision
- Annotation
- Encoding
- Streaming

Likewise, don’t collapse “output”:
- Streaming output (browser)
- Logging output (file)
- Saved-frame output (folder)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram 1 — System Context
  %% =========================
  subgraph D1["Diagram 1 — System Context (C4 L1-ish)"]
    direction TB

    Browser["Web Browser Client\n(&lt;img&gt; MJPEG viewer)"]:::external
    Webcam["Webcam Device\n(Hardware camera)"]:::hardware

    subgraph LM1["Local Machine (Single Node)"]
      direction TB
      PyRT["Python Runtime\n(Single host)"]:::runtime

      subgraph WSM["Web Streaming Mode (Process)"]
        direction TB
        FlaskApp["Flask Web App\n(MJPEG server)"]:::service
      end

      subgraph LMP["Local Mode (Process)"]
        direction TB
        LocalRunner["OpenCV Local Runner\n(standalone)"]:::service
      end

      subgraph LFS1["Local Filesystem"]
        direction TB
        AssetsDir["assets/ (Model assets)"]:::storage
        HaarXml["Haar Cascade XML\n(frontalface)"]:::asset
        LogsDir["logs/ (Logging dir)"]:::storage
        DetectLog[("detections.log\n(append-only)")]:::db
        SavedFrames[("saved_frames/\n(blur captures)")]:::db
        OutputsDir["outputs/ (Artifacts)"]:::storage
        Reqs["requirements.txt\n(Dependencies)"]:::asset
      end
    end

    Browser -->|"HTTP_GET /"| FlaskApp
    Browser -->|"HTTP_GET /video_feed"| FlaskApp
    FlaskApp -->|"HTTP_200 multipart/x-mixed-replace\n(MJPEG stream)"| Browser

    Webcam -->|"camera_frames"| PyRT
    FlaskApp -->|"reads/writes"| SavedFrames
    FlaskApp -->|"append_logs"| DetectLog
    FlaskApp -->|"loads_model"| HaarXml
    LocalRunner -->|"loads_model"| HaarXml
    LocalRunner -->|"append_logs"| DetectLog
    LocalRunner -->|"writes"| SavedFrames

    AssetsDir -->|"contains"| HaarXml
    LogsDir -->|"contains"| DetectLog
  end

  %% ==========================================
  %% Diagram 2 — Container/Component (C4 L2/3)
  %% ==========================================
  subgraph D2["Diagram 2 — Container/Component View (C4 L2/3 hybrid)"]
    direction TB

    Browser2["Browser\n(MJPEG viewer)"]:::external
    Webcam2["Webcam\n(Device)"]:::hardware

    subgraph LM2["Local Machine (Python Runtime)"]
      direction TB

      subgraph FWP["Flask Web App Process"]
        direction TB
        RouteIndex["Route: / (HTML page)"]:::api
        RouteFeed["Route: /video_feed\n(MJPEG Response)"]:::api

        MJPEGGen["MJPEG Stream Generator\n(yield multipart frames)\n(owns camera lifecycle)"]:::stream

        subgraph RTP["Real-time CV Pipeline (Hot Path)"]
          direction TB
          Capture["OpenCV VideoCapture\nFrame Grabber\n(open/close in generator)"]:::hot
          Gray["Preprocess: Grayscale\n(cv2.cvtColor)"]:::hot
          FaceDetect["Face Detection: Haar Cascade\n(CascadeClassifier.detectMultiScale)"]:::hot
          BlurScore["Blur Score: Laplacian Variance\n(var(Laplacian))"]:::hot
          Decision{"Decision:\nBLURRY vs CLEAR\n(threshold)"}:::decision
          Annotate["Annotator:\nboxes + labels + blur score text"]:::hot
          Encode["Encoder: JPEG\n(cv2.imencode)"]:::hot
        end

        subgraph SE["Event-based Side Effects (Should not block stream)"]
          direction TB
          Cooldown{"Cooldown Gate\n(avoid repeated captures)"}:::side
          FrameSaver["Frame Saver\n(write timestamped JPG)"]:::side
          EventLogger["Event Logger\n(timestamped events)"]:::side
        end

        Defensive["Defensive Handling\nif capture fails:\nrelease camera + stop generator/\nreturn error frame"]:::note
      end

      subgraph LFS2["Filesystem (Local)"]
        direction TB
        HaarXml2["Haar Cascade XML\nassets/*.xml"]:::asset
        DetectLog2[("logs/detections.log")]:::db
        SavedFrames2[("saved_frames/")]:::db
      end
    end

    %% Client/Web interactions
    Browser2 -->|"HTTP_GET /"| RouteIndex
    Browser2 -->|"HTTP_GET /video_feed"| RouteFeed
    RouteFeed -->|"creates/iterates"| MJPEGGen
    MJPEGGen -->|"multipart/x-mixed-replace\n(MJPEG)"| Browser2

    %% Hot path pipeline
    Webcam2 -->|"camera_frames"| Capture
    MJPEGGen -->|"owns"| Capture
    Capture -->|"frame (numpy array)"| Gray
    Gray -->|"gray_frame"| FaceDetect
    HaarXml2 -->|"loaded_by"| FaceDetect
    FaceDetect -->|"faces"| BlurScore
    BlurScore -->|"blur_score"| Decision
    Decision -->|"CLEAR"| Annotate
    Decision -->|"BLURRY"| Annotate
    Annotate -->|"annotated_frame"| Encode
    Encode -->|"JPEG bytes"| MJPEGGen

    %% Side effects (dashed, best-effort intent)
    Decision -.->|"BLURRY_event"| Cooldown
    Cooldown -.->|"allowed"| FrameSaver
    FrameSaver -.->|"write_jpg"| SavedFrames2
    Decision -.->|"log_event"| EventLogger
    EventLogger -.->|"append"| DetectLog2

    %% Notes / annotations
    Defensive -.->|"guards"| Capture
    Defensive -.->|"guards"| MJPEGGen
  end

  %% ==========================================
  %% Diagram 3 — Per-frame Sequence (Activity)
  %% ==========================================
  subgraph D3["Diagram 3 — Per-frame Sequence (Activity)"]
    direction TB

    B["Browser"]:::external
    F["Flask: /video_feed"]:::api
    G["MJPEG Generator"]:::stream
    C["OpenCV VideoCapture"]:::hot
    P["CV Pipeline Stages\n(grayscale → face detect → blur score → annotate)"]:::hot
    E["JPEG Encoder"]:::hot
    CD["Cooldown Gate"]:::side
    S["Frame Saver"]:::side
    L["Event Logger"]:::side
    FS["Local Filesystem\n(saved_frames/, logs/)"]:::storage

    B -->|"HTTP GET /video_feed"| F
    F -->|"start generator\n(Response streaming)"| G
    G -.->|"Camera lifecycle owned in generator\n(open/close to avoid conflicts)"| C

    G -->|"read()"| C
    C -->|"frame (numpy array)\n(if capture ok)"| P
    P -->|"annotated_frame"| E
    E -->|"JPEG bytes"| G
    G -->|"yield multipart MJPEG chunk"| F
    F -->|"stream chunk"| B

    P -->|"blur_score"| D3Dec{"BLURRY?"}:::decision
    D3Dec -.->|"yes"| CD
    CD -.->|"cooldown allows"| S
    S -.->|"write JPG\nsaved_frames/blur_YYYYMMDD_HHMMSS.jpg"| FS
    CD -.->|"cooldown blocks\n(skip save)"| G
    D3Dec -.->|"yes (also)"| L
    L -.->|"append logs/detections.log"| FS
    D3Dec -->|"no (CLEAR)\nno save/log side effects"| G

    C -.->|"capture fails"| D3Fail["Defensive handling:\nrelease camera + stop generator/emit error frame"]:::note
    D3Fail -.->|"release()"| C
    D3Fail -.->|"stop/terminate stream"| F
  end

  %% =========================
  %% Click Events (mappings)
  %% =========================
  click FlaskApp "https://github.com/tanish-sarkar/real-time-facial-detection/blob/main/src/flask_app.py"
  click MJPEGGen "https://github.com/tanish-sarkar/real-time-facial-detection/blob/main/src/flask_app.py"
  click LocalRunner "https://github.com/tanish-sarkar/real-time-facial-detection/blob/main/src/run_detection.py"
  click HaarXml "https://github.com/tanish-sarkar/real-time-facial-detection/blob/main/assets/haarcascade_frontalface_default.xml"
  click HaarXml2 "https://github.com/tanish-sarkar/real-time-facial-detection/blob/main/assets/haarcascade_frontalface_default.xml"
  click AssetsDir "https://github.com/tanish-sarkar/real-time-facial-detection/tree/main/assets/"
  click DetectLog "https://github.com/tanish-sarkar/real-time-facial-detection/blob/main/logs/detections.log"
  click DetectLog2 "https://github.com/tanish-sarkar/real-time-facial-detection/blob/main/logs/detections.log"
  click LogsDir "https://github.com/tanish-sarkar/real-time-facial-detection/tree/main/logs/"
  click OutputsDir "https://github.com/tanish-sarkar/real-time-facial-detection/tree/main/outputs/"
  click PyRT "https://github.com/tanish-sarkar/real-time-facial-detection/blob/main/src/__init__.py"
  click Reqs "https://github.com/tanish-sarkar/real-time-facial-detection/blob/main/requirements.txt"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#6f42c1,stroke:#3d1f6e,color:#ffffff,stroke-width:1px
  classDef hardware fill:#8a2be2,stroke:#4b1485,color:#ffffff,stroke-width:1px
  classDef runtime fill:#e9ecef,stroke:#6c757d,color:#212529,stroke-width:1px

  classDef service fill:#0d6efd,stroke:#084298,color:#ffffff,stroke-width:1px
  classDef api fill:#1f6feb,stroke:#0b3d91,color:#ffffff,stroke-width:1px
  classDef stream fill:#0ea5e9,stroke:#075985,color:#ffffff,stroke-width:1px

  classDef hot fill:#2563eb,stroke:#1e3a8a,color:#ffffff,stroke-width:1px
  classDef decision fill:#1d4ed8,stroke:#1e3a8a,color:#ffffff,stroke-width:1px

  classDef side fill:#f59e0b,stroke:#92400e,color:#111827,stroke-width:1px
  classDef storage fill:#adb5bd,stroke:#495057,color:#111827,stroke-width:1px
  classDef db fill:#9ca3af,stroke:#374151,color:#111827,stroke-width:1px
  classDef asset fill:#cbd5e1,stroke:#475569,color:#0f172a,stroke-width:1px
  classDef note fill:#fff3cd,stroke:#b45309,color:#111827,stroke-width:1px
```
