# navaneeth1324/gazeshield architecture

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

- Interactive diagram: https://gitdiagram.com/navaneeth1324/gazeshield
- Repository: https://github.com/navaneeth1324/gazeshield

## Overview

GazeShield is an offline webcam privacy guard. Its main loop takes camera frames through face/iris and head-pose tracking, then evaluates the primary user’s attention and secondary faces. Confirmed intruders trigger security responses; away/absent states activate the privacy shield. The HUD presents gaze, attention, and alert status. The README documents snapshot logging, audio alerts, and optional workstation locking. Some main-loop calls are in omitted excerpts, so those links are supported by the README’s architecture description rather than claims of further source inspection.

Main entry points: [`main.py`](https://github.com/navaneeth1324/gazeshield/blob/main/main.py) (Application loop), [`src/privacy/security_handler.py`](https://github.com/navaneeth1324/gazeshield/blob/main/src/privacy/security_handler.py) (Security responses), [`src/privacy/overlay.py`](https://github.com/navaneeth1324/gazeshield/blob/main/src/privacy/overlay.py) (Shield controller), [`src/ui/hud.py`](https://github.com/navaneeth1324/gazeshield/blob/main/src/ui/hud.py) (HUD renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_vision["Vision and attention"]
  node_tracker["Face and iris tracking<br/>[face_tracker.py]"]
  node_gaze["Attention estimator<br/>[gaze_estimator.py]"]
  node_intruder["Intruder detection"]
end

subgraph group_security["Privacy and security"]
  node_security_handler["Security responses"]
  node_overlay["Shield controller<br/>[overlay.py]"]
  node_overlay_window["Shield window<br/>[overlay_window.py]"]
  node_snapshots["Incident snapshots"]
end

subgraph group_interface["User interface"]
  node_hud["HUD renderer<br/>[hud.py]"]
  node_drawing["HUD drawing utilities<br/>[visualizer.py]"]
end

node_user(("User"))
node_camera(("Webcam"))
node_app["Application loop<br/>[main.py]"]
node_system_alerts["Audio and workstation"]
node_preview(("Live preview"))

node_user -->|"faces"| node_camera
node_camera -->|"frames"| node_app
node_app -->|"processes frames"| node_tracker
node_app -->|"evaluates attention"| node_gaze
node_app -->|"checks secondary faces"| node_intruder
node_app -->|"triggers response"| node_security_handler
node_app -->|"controls shield"| node_overlay
node_app -->|"renders status"| node_hud
node_security_handler -->|"saves images"| node_snapshots
node_security_handler -->|"alerts or locks"| node_system_alerts
node_overlay -->|"launches and commands"| node_overlay_window
node_hud -->|"uses drawing helpers"| node_drawing
node_hud -->|"renders frame"| node_preview
node_overlay -->|"shields screen"| node_user

click node_app "https://github.com/navaneeth1324/gazeshield/blob/main/main.py"
click node_tracker "https://github.com/navaneeth1324/gazeshield/blob/main/src/core/face_tracker.py"
click node_gaze "https://github.com/navaneeth1324/gazeshield/blob/main/src/core/gaze_estimator.py"
click node_intruder "https://github.com/navaneeth1324/gazeshield/blob/main/src/core/intruder_detector.py"
click node_security_handler "https://github.com/navaneeth1324/gazeshield/blob/main/src/privacy/security_handler.py"
click node_overlay "https://github.com/navaneeth1324/gazeshield/blob/main/src/privacy/overlay.py"
click node_overlay_window "https://github.com/navaneeth1324/gazeshield/blob/main/src/privacy/overlay_window.py"
click node_hud "https://github.com/navaneeth1324/gazeshield/blob/main/src/ui/hud.py"
click node_drawing "https://github.com/navaneeth1324/gazeshield/blob/main/src/ui/visualizer.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tracker,node_gaze,node_intruder,node_user,node_preview toneBlue
class node_security_handler,node_overlay,node_overlay_window,node_snapshots toneAmber
class node_hud,node_drawing toneMint
class node_camera,node_system_alerts toneIndigo
class node_app toneTeal
```

## Components

### Vision and attention

- [Face and iris tracking](https://github.com/navaneeth1324/gazeshield/blob/main/src/core/face_tracker.py): `src/core/face_tracker.py`
- [Attention estimator](https://github.com/navaneeth1324/gazeshield/blob/main/src/core/gaze_estimator.py): `src/core/gaze_estimator.py`
- [Intruder detection](https://github.com/navaneeth1324/gazeshield/blob/main/src/core/intruder_detector.py): `src/core/intruder_detector.py`

### Privacy and security

- [Security responses](https://github.com/navaneeth1324/gazeshield/blob/main/src/privacy/security_handler.py): `src/privacy/security_handler.py`
- [Shield controller](https://github.com/navaneeth1324/gazeshield/blob/main/src/privacy/overlay.py): `src/privacy/overlay.py`
- [Shield window](https://github.com/navaneeth1324/gazeshield/blob/main/src/privacy/overlay_window.py): `src/privacy/overlay_window.py`
- **Incident snapshots**

### User interface

- [HUD renderer](https://github.com/navaneeth1324/gazeshield/blob/main/src/ui/hud.py): `src/ui/hud.py`
- [HUD drawing utilities](https://github.com/navaneeth1324/gazeshield/blob/main/src/ui/visualizer.py): `src/ui/visualizer.py`

### Other components

- **User**
- **Webcam**
- [Application loop](https://github.com/navaneeth1324/gazeshield/blob/main/main.py): `main.py`
- **Audio and workstation**
- **Live preview**

## Connections

- User → Webcam: faces (evidence: `README.md`)
- Webcam → Application loop: frames (evidence: `main.py`)
- Application loop → Face and iris tracking: processes frames (evidence: `README.md`)
- Application loop → Attention estimator: evaluates attention (evidence: `README.md`)
- Application loop → Intruder detection: checks secondary faces (evidence: `README.md`)
- Application loop → Security responses: triggers response (evidence: `main.py`)
- Application loop → Shield controller: controls shield (evidence: `README.md`)
- Application loop → HUD renderer: renders status (evidence: `main.py`)
- Security responses → Incident snapshots: saves images (evidence: `src/privacy/security_handler.py`)
- Security responses → Audio and workstation: alerts or locks (evidence: `src/privacy/security_handler.py`)
- Shield controller → Shield window: launches and commands (evidence: `src/privacy/overlay.py`)
- HUD renderer → HUD drawing utilities: uses drawing helpers (evidence: `src/ui/hud.py`)
- HUD renderer → Live preview: renders frame
- Shield controller → User: shields screen (evidence: `README.md`)
