# thangved/face-detection architecture

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

- Interactive diagram: https://gitdiagram.com/thangved/face-detection
- Repository: https://github.com/thangved/face-detection

## Overview

##### Project Type and Purpose
- This is a client-only, single-page web application (built with Vite + React/TypeScript) for real-time face detection using faceapi.js.
- The app loads pre-trained models from the `public/models` folder and runs inference entirely in the browser via WebRTC video input.

##### Main Components
a. Client (Browser)
- React Application (src/App.tsx, src/main.tsx)
- FaceAPI.js Library (imported in code; no server dependency)
- Utilities
- getVideoStream.ts: acquires webcam via WebRTC
- loadModels.ts: fetches model shards & manifests from static server
b. Static Asset Server
- Serves `index.html`, JS bundles, CSS, and `public/models/*`
- Can be GitHub Pages, Netlify, Vercel, or any static host
c. CI/CD Pipeline
- GitHub Actions workflow (`.github/workflows/deploy.yml`)
- Runs build, test, and deployment steps on push

##### Relationships & Data Flow
- User → Browser: User navigates to the hosted URL.
- Browser → Static Server:
- Downloads `index.html` → bootstraps React app
- Downloads JS/CSS bundles (built by Vite)
- Downloads model weight manifests and shard files under `public/models`
- React App → Browser APIs:
- Calls `getUserMedia()` (WebRTC) to access webcam
- React App → FaceAPI.js:
- Calls `loadModels()` to fetch and initialize models in memory
- Streams video frames into faceapi.js detection pipeline
- React App → UI:
- Overlays detection results onto a `<canvas>` or `<video>` element

##### Architectural Patterns & Design Principles
- SPA Architecture: separation of concerns between static hosting and client logic
- Client-heavy ML Inference: all computation happens in the browser; no backend
- Modular Code: utilities under `src/utils/`, React components under `src/`
- CI/CD as Code: GitHub Actions defined in YAML

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "CI/CD Pipeline"
        CICD["CI/CD Pipeline"]:::cicd
    end
    subgraph "Static Host"
        Host["Static Host<br/>index.html, bundles, /models"]:::static
    end
    subgraph "User Browser"
        subgraph "React SPA"
            Entry["src/main.tsx"]:::static
            Root["src/App.tsx"]:::static
        end
        Util1["getVideoStream.ts"]:::runtime
        Util2["loadModels.ts"]:::runtime
        FaceAPI["faceapi.js Inference Engine"]:::runtime
        Video["WebRTC Video Stream"]:::runtime
        UI["React UI Overlay"]:::runtime
    end

    CICD -->|"build & deploy"| Host
    Host -->|"download index.html & JS/CSS"| Entry
    Entry -->|"bootstrap React App"| Root
    Root -->|"invoke loadModels()"| Util2
    Util2 -->|"fetch model shards & manifests"| Host
    Root -->|"invoke getUserMedia()"| Util1
    Util1 -->|"provide video feed"| Video
    Video -->|"video frames"| FaceAPI
    Util2 -->|"initialize models"| FaceAPI
    FaceAPI -->|"detection data"| UI

    click CICD "https://github.com/thangved/face-detection/blob/master/.github/workflows/deploy.yml"
    click Entry "https://github.com/thangved/face-detection/blob/master/src/main.tsx"
    click Root "https://github.com/thangved/face-detection/blob/master/src/App.tsx"
    click Util1 "https://github.com/thangved/face-detection/blob/master/src/utils/getVideoStream.ts"
    click Util2 "https://github.com/thangved/face-detection/blob/master/src/utils/loadModels.ts"
    click Host "https://github.com/thangved/face-detection/blob/master/index.html"
    click Host "https://github.com/thangved/face-detection/tree/master/public/models/"

    classDef static fill:#ADD8E6,stroke:#000,color:#000
    classDef runtime fill:#90EE90,stroke:#000,color:#000
    classDef cicd fill:#FFA500,stroke:#000,color:#000
```
