# vineshbhaskar/screenprivacysystem architecture

> Architecture diagram of the GitHub repository vineshbhaskar/screenprivacysystem, 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/vineshbhaskar/screenprivacysystem
- Repository: https://github.com/vineshbhaskar/screenprivacysystem

## Overview

This is a desktop shoulder-surfing protection app with a FastAPI alert-logging backend. The main workflow is webcam capture, multi-face and iris-gaze analysis, primary-user comparison, then a threat decision that can trigger privacy responses and optionally log an alert. The client is largely implemented in one source file, so several distinct responsibilities share its path. The README documents the client-to-server alert flow; the server excerpt shows database writes. Client implementation details beyond the supplied excerpts are represented only where documented.

Main entry points: [`client_app/screen_privacy.py`](https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py) (Threat Decision), [`server/main.py`](https://github.com/vineshbhaskar/screenprivacysystem/blob/main/server/main.py) (FastAPI Alert Endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_detection["Threat Detection"]
  node_monitoring["Camera Monitoring<br/>[screen_privacy.py]"]
  node_face_detection["Multi-Face Detection<br/>[screen_privacy.py]"]
  node_gaze["Iris Gaze Analysis<br/>[screen_privacy.py]"]
  node_primary_user["Primary User Selection<br/>[screen_privacy.py]"]
  node_alert["Threat Decision<br/>[screen_privacy.py]"]
  node_cooldown["Alert Cooldown<br/>[screen_privacy.py]"]
end

subgraph group_desktop["Desktop Client"]
  node_dashboard["Tkinter Dashboard<br/>[screen_privacy.py]"]
  node_spotlight["Spotlight Overlay<br/>[screen_privacy.py]"]
  node_screen_dim["Screen Dimming<br/>[screen_privacy.py]"]
  node_preview["Camera Preview<br/>[screen_privacy.py]"]
  node_notifications["Push Notifications<br/>[screen_privacy.py]"]
end

subgraph group_backend["Alert Backend"]
  node_api["FastAPI Alert Endpoint<br/>[main.py]"]
  node_alert_log["Alert Log Writer<br/>[main.py]"]
end

node_user(("Desktop User"))
node_webcam["Webcam"]
node_database[("PostgreSQL Alerts")]

node_user -->|"configures"| node_dashboard
node_dashboard -->|"starts monitoring"| node_monitoring
node_webcam -->|"provides frames"| node_monitoring
node_monitoring -->|"processes frames"| node_face_detection
node_face_detection -->|"analyzes eyes"| node_gaze
node_gaze -->|"compares faces"| node_primary_user
node_primary_user -->|"identifies bystanders"| node_alert
node_alert -->|"checks cooldown"| node_cooldown
node_alert -->|"activates"| node_spotlight
node_alert -->|"activates"| node_screen_dim
node_alert -->|"triggers preview"| node_preview
node_alert -->|"sends alert"| node_notifications
node_alert -->|"posts alert"| node_api
node_api -->|"routes to"| node_alert_log
node_alert_log -->|"writes event"| node_database

click node_dashboard "https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py"
click node_monitoring "https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py"
click node_face_detection "https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py"
click node_gaze "https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py"
click node_primary_user "https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py"
click node_alert "https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py"
click node_cooldown "https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py"
click node_spotlight "https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py"
click node_screen_dim "https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py"
click node_preview "https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py"
click node_notifications "https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py"
click node_api "https://github.com/vineshbhaskar/screenprivacysystem/blob/main/server/main.py"
click node_alert_log "https://github.com/vineshbhaskar/screenprivacysystem/blob/main/server/main.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_monitoring,node_face_detection,node_gaze,node_primary_user,node_alert,node_cooldown,node_user toneBlue
class node_dashboard,node_spotlight,node_screen_dim,node_preview,node_notifications,node_database toneAmber
class node_api,node_alert_log toneMint
class node_webcam toneIndigo
```

## Components

### Threat Detection

- [Camera Monitoring](https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py): `client_app/screen_privacy.py`
- [Multi-Face Detection](https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py): `client_app/screen_privacy.py`
- [Iris Gaze Analysis](https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py): `client_app/screen_privacy.py`
- [Primary User Selection](https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py): `client_app/screen_privacy.py`
- [Threat Decision](https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py): `client_app/screen_privacy.py`
- [Alert Cooldown](https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py): `client_app/screen_privacy.py`

### Desktop Client

- [Tkinter Dashboard](https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py): `client_app/screen_privacy.py`
- [Spotlight Overlay](https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py): `client_app/screen_privacy.py`
- [Screen Dimming](https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py): `client_app/screen_privacy.py`
- [Camera Preview](https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py): `client_app/screen_privacy.py`
- [Push Notifications](https://github.com/vineshbhaskar/screenprivacysystem/blob/main/client_app/screen_privacy.py): `client_app/screen_privacy.py`

### Alert Backend

- [FastAPI Alert Endpoint](https://github.com/vineshbhaskar/screenprivacysystem/blob/main/server/main.py): `server/main.py`
- [Alert Log Writer](https://github.com/vineshbhaskar/screenprivacysystem/blob/main/server/main.py): `server/main.py`

### Other components

- **Desktop User**
- **Webcam**
- **PostgreSQL Alerts**

## Connections

- Desktop User → Tkinter Dashboard: configures (evidence: `README.md`)
- Tkinter Dashboard → Camera Monitoring: starts monitoring (evidence: `client_app/screen_privacy.py`)
- Webcam → Camera Monitoring: provides frames (evidence: `README.md`)
- Camera Monitoring → Multi-Face Detection: processes frames (evidence: `README.md`)
- Multi-Face Detection → Iris Gaze Analysis: analyzes eyes (evidence: `README.md`)
- Iris Gaze Analysis → Primary User Selection: compares faces (evidence: `README.md`)
- Primary User Selection → Threat Decision: identifies bystanders (evidence: `README.md`)
- Threat Decision → Alert Cooldown: checks cooldown (evidence: `README.md`)
- Threat Decision → Spotlight Overlay: activates (evidence: `README.md`)
- Threat Decision → Screen Dimming: activates (evidence: `README.md`)
- Threat Decision → Camera Preview: triggers preview (evidence: `README.md`)
- Threat Decision → Push Notifications: sends alert (evidence: `README.md`)
- Threat Decision → FastAPI Alert Endpoint: posts alert (evidence: `README.md`)
- FastAPI Alert Endpoint → Alert Log Writer: routes to (evidence: `server/main.py`)
- Alert Log Writer → PostgreSQL Alerts: writes event (evidence: `server/main.py`)
