# kv4u/safescreen architecture

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

- Interactive diagram: https://gitdiagram.com/kv4u/safescreen
- Repository: https://github.com/kv4u/safescreen

## Overview

SafeScreen is a Windows privacy-screen application: it observes webcam frames, estimates whether the user is looking at the display, and protects the desktop when attention is absent or detection fails. The README documents the detection and protection stages, but their Dart sources are not present in the supplied tree, so those nodes have no source path. The sampled native code supports the in-memory Media Foundation capture path and the Windows camera plugin’s preview/record/photo functions; exact Dart orchestration is not visible.

Main entry points: [`windows/runner/mf_camera.cpp`](https://github.com/kv4u/safescreen/blob/main/windows/runner/mf_camera.cpp) (Flutter method channel), [`packages/camera_windows/windows/capture_controller.cpp`](https://github.com/kv4u/safescreen/blob/main/packages/camera_windows/windows/capture_controller.cpp) (Camera plugin controller), [`packages/camera_windows/windows/preview_handler.cpp`](https://github.com/kv4u/safescreen/blob/main/packages/camera_windows/windows/preview_handler.cpp) (Preview sample handler), [`packages/camera_windows/windows/capture_engine_listener.cpp`](https://github.com/kv4u/safescreen/blob/main/packages/camera_windows/windows/capture_engine_listener.cpp) (Capture event listener)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Frame capture"]
  node_mf_capture["Media Foundation capture<br/>[mf_camera.cpp]"]
  node_camera_plugin["Camera plugin controller"]
  node_preview["Preview sample handler"]
  node_sample_listener["Capture event listener"]
end

subgraph group_detection["Attention detection"]
  node_blazeface["BlazeFace detector"]
  node_head_pose["Head pose estimator"]
  node_gaze["Gaze detector service"]
  node_calibration["Neutral calibration"]
  node_surfer["Second-face check"]
  node_failsafe["Staleness failsafe"]
end

subgraph group_protection["Screen protection"]
  node_decision["Visibility decision"]
  node_desktop_cover["Desktop blackout"]
  node_tray["Tray controls"]
  node_settings["User settings"]
end

subgraph group_native["Windows runtime"]
  node_flutter_entry["Flutter app entry<br/>[main.cpp]"]
  node_channel["Flutter method channel<br/>[mf_camera.cpp]"]
end

node_user(("User"))
node_webcam(("Webcam"))
node_tflite["TFLite runtime"]

node_user -->|"launches"| node_flutter_entry
node_flutter_entry -->|"registers channel"| node_channel
node_channel -->|"starts or grabs"| node_mf_capture
node_webcam -->|"supplies frames"| node_mf_capture
node_mf_capture -->|"returns frame bytes"| node_channel
node_channel -->|"provides frames"| node_blazeface
node_blazeface -->|"runs inference"| node_tflite
node_blazeface -->|"returns keypoints"| node_head_pose
node_head_pose -->|"provides pose"| node_calibration
node_calibration -->|"provides neutral baseline"| node_gaze
node_head_pose -->|"provides pose"| node_gaze
node_blazeface -->|"reports faces"| node_surfer
node_gaze -->|"reports attention"| node_decision
node_surfer -->|"reports extra face"| node_decision
node_failsafe -->|"forces protection"| node_decision
node_decision -->|"shows or hides"| node_desktop_cover
node_settings -->|"sets sensitivity"| node_gaze
node_settings -->|"configures detection"| node_surfer
node_settings -->|"configures startup"| node_tray
node_user -->|"controls"| node_tray
node_webcam -.->|"fallback capture"| node_camera_plugin
node_camera_plugin -->|"starts preview"| node_preview
node_preview -->|"sets sample callback"| node_sample_listener
node_sample_listener -->|"forwards samples and events"| node_camera_plugin

click node_flutter_entry "https://github.com/kv4u/safescreen/blob/main/windows/runner/main.cpp"
click node_mf_capture "https://github.com/kv4u/safescreen/blob/main/windows/runner/mf_camera.cpp"
click node_camera_plugin "https://github.com/kv4u/safescreen/blob/main/packages/camera_windows/windows/capture_controller.cpp"
click node_preview "https://github.com/kv4u/safescreen/blob/main/packages/camera_windows/windows/preview_handler.cpp"
click node_sample_listener "https://github.com/kv4u/safescreen/blob/main/packages/camera_windows/windows/capture_engine_listener.cpp"
click node_channel "https://github.com/kv4u/safescreen/blob/main/windows/runner/mf_camera.cpp"

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_mf_capture,node_camera_plugin,node_preview,node_sample_listener,node_user toneBlue
class node_blazeface,node_head_pose,node_gaze,node_calibration,node_surfer,node_failsafe toneAmber
class node_decision,node_desktop_cover,node_tray,node_settings toneMint
class node_flutter_entry,node_channel toneRose
class node_webcam,node_tflite toneIndigo
```

## Components

### Frame capture

- [Media Foundation capture](https://github.com/kv4u/safescreen/blob/main/windows/runner/mf_camera.cpp): `windows/runner/mf_camera.cpp`
- [Camera plugin controller](https://github.com/kv4u/safescreen/blob/main/packages/camera_windows/windows/capture_controller.cpp): `packages/camera_windows/windows/capture_controller.cpp`
- [Preview sample handler](https://github.com/kv4u/safescreen/blob/main/packages/camera_windows/windows/preview_handler.cpp): `packages/camera_windows/windows/preview_handler.cpp`
- [Capture event listener](https://github.com/kv4u/safescreen/blob/main/packages/camera_windows/windows/capture_engine_listener.cpp): `packages/camera_windows/windows/capture_engine_listener.cpp`

### Attention detection

- **BlazeFace detector**
- **Head pose estimator**
- **Gaze detector service**
- **Neutral calibration**
- **Second-face check**
- **Staleness failsafe**

### Screen protection

- **Visibility decision**
- **Desktop blackout**
- **Tray controls**
- **User settings**

### Windows runtime

- [Flutter app entry](https://github.com/kv4u/safescreen/blob/main/windows/runner/main.cpp): `windows/runner/main.cpp`
- [Flutter method channel](https://github.com/kv4u/safescreen/blob/main/windows/runner/mf_camera.cpp): `windows/runner/mf_camera.cpp`

### Other components

- **User**
- **Webcam**
- **TFLite runtime**

## Connections

- User → Flutter app entry: launches
- Flutter app entry → Flutter method channel: registers channel
- Flutter method channel → Media Foundation capture: starts or grabs
- Webcam → Media Foundation capture: supplies frames
- Media Foundation capture → Flutter method channel: returns frame bytes
- Flutter method channel → BlazeFace detector: provides frames
- BlazeFace detector → TFLite runtime: runs inference
- BlazeFace detector → Head pose estimator: returns keypoints
- Head pose estimator → Neutral calibration: provides pose
- Neutral calibration → Gaze detector service: provides neutral baseline
- Head pose estimator → Gaze detector service: provides pose
- BlazeFace detector → Second-face check: reports faces
- Gaze detector service → Visibility decision: reports attention
- Second-face check → Visibility decision: reports extra face
- Staleness failsafe → Visibility decision: forces protection
- Visibility decision → Desktop blackout: shows or hides
- User settings → Gaze detector service: sets sensitivity
- User settings → Second-face check: configures detection
- User settings → Tray controls: configures startup
- User → Tray controls: controls
- Webcam → Camera plugin controller: fallback capture
- Camera plugin controller → Preview sample handler: starts preview
- Preview sample handler → Capture event listener: sets sample callback
- Capture event listener → Camera plugin controller: forwards samples and events