# dweep-desai/facegate-mac architecture

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

- Interactive diagram: https://gitdiagram.com/dweep-desai/facegate-mac
- Repository: https://github.com/dweep-desai/facegate-mac

## Overview

FaceGate is a native macOS app locker. Its main flow monitors app launches, gates locked apps with an authentication overlay, then records a per-app unlock session. Face authentication uses a camera-to-recognition pipeline; Touch ID and password are fallbacks. The README also documents scheduling, sleep locking, liveness checks, and other controls. Connections reflect source-index references, shown calls, or README statements; some documented capabilities are not represented by sampled implementation details.

Main entry points: [`FaceGate/App/AppDelegate.swift`](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/App/AppDelegate.swift) (App lifecycle), [`FaceGate/FaceAuth/FaceAuthManager.swift`](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/FaceAuth/FaceAuthManager.swift) (Face auth pipeline), [`FaceGate/UI/SettingsView.swift`](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/UI/SettingsView.swift) (Settings), [`FaceGate/Core/LockedAppsManager.swift`](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/Core/LockedAppsManager.swift) (Locked app list)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["App runtime"]
  node_app["App lifecycle<br/>[AppDelegate.swift]"]
  node_appui["Menu bar app<br/>[FaceGateApp.swift]"]
end

subgraph group_locking["App locking"]
  node_monitor["Launch monitor<br/>[AppMonitor.swift]"]
  node_locker["Lock enforcement<br/>[AppLocker.swift]"]
  node_sessions["Unlock sessions"]
  node_lockedapps[("Locked app list")]
  node_schedules["Lock schedules"]
end

subgraph group_face["Face recognition"]
  node_enrollment["Face enrollment"]
  node_enrollmentui["Enrollment UI"]
  node_camera_mgr["Camera capture"]
  node_faceauth["Face auth pipeline"]
  node_detector["Face detector<br/>[FaceDetector.swift]"]
  node_embedder["Face embedder<br/>[FaceEmbedder.swift]"]
  node_matcher["Face matcher<br/>[FaceMatcher.swift]"]
  node_face_store[("Encrypted face data")]
end

subgraph group_auth["Authentication"]
  node_overlay["Authentication overlay"]
  node_authmanager["Auth coordinator"]
  node_touchid["Touch ID<br/>[TouchIDAuth.swift]"]
  node_password["Password auth<br/>[PasswordAuth.swift]"]
  node_actionauth["Sensitive-action auth"]
end

subgraph group_settings["User controls"]
  node_settings["Settings<br/>[SettingsView.swift]"]
  node_setup["Initial setup<br/>[SetupView.swift]"]
  node_picker["App picker"]
  node_scanner["Installed app scanner"]
  node_hotkey["Emergency hotkey"]
end

node_user(("User"))
node_macos["macOS apps"]
node_camera["Camera"]

node_user -->|"uses"| node_appui
node_appui -->|"starts"| node_app
node_app -->|"starts monitoring"| node_monitor
node_macos -.->|"reports launches"| node_monitor
node_monitor -->|"checks lock list"| node_lockedapps
node_monitor -->|"checks sessions"| node_sessions
node_monitor -.->|"enforces locks"| node_locker
node_locker -->|"shows gate"| node_overlay
node_locker -->|"checks session"| node_sessions
node_locker -->|"checks app state"| node_lockedapps
node_overlay -->|"requests authentication"| node_authmanager
node_authmanager -->|"starts face check"| node_faceauth
node_authmanager -->|"requests Touch ID"| node_touchid
node_authmanager -->|"verifies password"| node_password
node_overlay -.->|"records unlock"| node_sessions
node_faceauth -->|"starts capture"| node_camera_mgr
node_camera -->|"provides frames"| node_camera_mgr
node_faceauth -->|"detects faces"| node_detector
node_faceauth -->|"generates embeddings"| node_embedder
node_faceauth -->|"matches faces"| node_matcher
node_faceauth -->|"loads enrollment"| node_face_store
node_enrollmentui -->|"controls enrollment"| node_enrollment
node_enrollment -->|"captures frames"| node_camera_mgr
node_enrollment -->|"checks quality"| node_detector
node_enrollment -->|"creates embeddings"| node_embedder
node_enrollment -->|"stores enrollment"| node_face_store
node_schedules -->|"reads locked apps"| node_lockedapps
node_schedules -->|"creates sessions"| node_sessions
node_lockedapps -->|"records overrides"| node_schedules
node_user -->|"configures"| node_settings
node_settings -->|"manages app locks"| node_lockedapps
node_settings -->|"configures schedules"| node_schedules
node_settings -->|"configures timers"| node_sessions
node_settings -->|"manages enrollment data"| node_face_store
node_setup -->|"offers enrollment"| node_enrollmentui
node_setup -->|"selects apps"| node_picker
node_picker -->|"sets locked apps"| node_lockedapps
node_picker -->|"scans installed apps"| node_scanner
node_app -->|"configures hotkey"| node_hotkey
node_app -->|"opens protected actions"| node_actionauth
node_app -->|"opens settings"| node_settings
node_app -->|"opens setup"| node_setup

click node_app "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/App/AppDelegate.swift"
click node_appui "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/App/FaceGateApp.swift"
click node_monitor "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/Core/AppMonitor.swift"
click node_locker "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/Core/AppLocker.swift"
click node_sessions "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/Core/SessionManager.swift"
click node_lockedapps "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/Core/LockedAppsManager.swift"
click node_schedules "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/Core/AppScheduleManager.swift"
click node_overlay "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/UI/AuthOverlayView.swift"
click node_authmanager "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/Auth/AuthenticationManager.swift"
click node_touchid "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/Auth/TouchIDAuth.swift"
click node_password "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/Auth/PasswordAuth.swift"
click node_enrollment "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/FaceAuth/FaceEnrollmentManager.swift"
click node_enrollmentui "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/UI/FaceEnrollmentView.swift"
click node_camera_mgr "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/FaceAuth/CameraManager.swift"
click node_faceauth "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/FaceAuth/FaceAuthManager.swift"
click node_detector "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/FaceAuth/FaceDetector.swift"
click node_embedder "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/FaceAuth/FaceEmbedder.swift"
click node_matcher "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/FaceAuth/FaceMatcher.swift"
click node_face_store "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/FaceAuth/FaceDataStore.swift"
click node_settings "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/UI/SettingsView.swift"
click node_setup "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/UI/SetupView.swift"
click node_picker "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/UI/AppPickerView.swift"
click node_scanner "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/Utilities/InstalledAppsScanner.swift"
click node_hotkey "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/Core/GlobalHotkeyManager.swift"
click node_actionauth "https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/UI/ActionAuthWindow.swift"

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_app,node_appui,node_user toneBlue
class node_monitor,node_locker,node_sessions,node_lockedapps,node_schedules toneAmber
class node_enrollment,node_enrollmentui,node_camera_mgr,node_faceauth,node_detector,node_embedder,node_matcher,node_face_store toneMint
class node_overlay,node_authmanager,node_touchid,node_password,node_actionauth toneRose
class node_settings,node_setup,node_picker,node_scanner,node_hotkey,node_macos,node_camera toneIndigo
```

## Components

### App runtime

- [App lifecycle](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/App/AppDelegate.swift): `FaceGate/App/AppDelegate.swift`
- [Menu bar app](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/App/FaceGateApp.swift): `FaceGate/App/FaceGateApp.swift`

### App locking

- [Launch monitor](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/Core/AppMonitor.swift): `FaceGate/Core/AppMonitor.swift`
- [Lock enforcement](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/Core/AppLocker.swift): `FaceGate/Core/AppLocker.swift`
- [Unlock sessions](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/Core/SessionManager.swift): `FaceGate/Core/SessionManager.swift`
- [Locked app list](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/Core/LockedAppsManager.swift): `FaceGate/Core/LockedAppsManager.swift`
- [Lock schedules](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/Core/AppScheduleManager.swift): `FaceGate/Core/AppScheduleManager.swift`

### Face recognition

- [Face enrollment](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/FaceAuth/FaceEnrollmentManager.swift): `FaceGate/FaceAuth/FaceEnrollmentManager.swift`
- [Enrollment UI](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/UI/FaceEnrollmentView.swift): `FaceGate/UI/FaceEnrollmentView.swift`
- [Camera capture](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/FaceAuth/CameraManager.swift): `FaceGate/FaceAuth/CameraManager.swift`
- [Face auth pipeline](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/FaceAuth/FaceAuthManager.swift): `FaceGate/FaceAuth/FaceAuthManager.swift`
- [Face detector](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/FaceAuth/FaceDetector.swift): `FaceGate/FaceAuth/FaceDetector.swift`
- [Face embedder](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/FaceAuth/FaceEmbedder.swift): `FaceGate/FaceAuth/FaceEmbedder.swift`
- [Face matcher](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/FaceAuth/FaceMatcher.swift): `FaceGate/FaceAuth/FaceMatcher.swift`
- [Encrypted face data](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/FaceAuth/FaceDataStore.swift): `FaceGate/FaceAuth/FaceDataStore.swift`

### Authentication

- [Authentication overlay](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/UI/AuthOverlayView.swift): `FaceGate/UI/AuthOverlayView.swift`
- [Auth coordinator](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/Auth/AuthenticationManager.swift): `FaceGate/Auth/AuthenticationManager.swift`
- [Touch ID](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/Auth/TouchIDAuth.swift): `FaceGate/Auth/TouchIDAuth.swift`
- [Password auth](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/Auth/PasswordAuth.swift): `FaceGate/Auth/PasswordAuth.swift`
- [Sensitive-action auth](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/UI/ActionAuthWindow.swift): `FaceGate/UI/ActionAuthWindow.swift`

### User controls

- [Settings](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/UI/SettingsView.swift): `FaceGate/UI/SettingsView.swift`
- [Initial setup](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/UI/SetupView.swift): `FaceGate/UI/SetupView.swift`
- [App picker](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/UI/AppPickerView.swift): `FaceGate/UI/AppPickerView.swift`
- [Installed app scanner](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/Utilities/InstalledAppsScanner.swift): `FaceGate/Utilities/InstalledAppsScanner.swift`
- [Emergency hotkey](https://github.com/dweep-desai/facegate-mac/blob/main/FaceGate/Core/GlobalHotkeyManager.swift): `FaceGate/Core/GlobalHotkeyManager.swift`

### Other components

- **User**
- **macOS apps**
- **Camera**

## Connections

- User → Menu bar app: uses (evidence: `FaceGate/App/FaceGateApp.swift`)
- Menu bar app → App lifecycle: starts (evidence: `FaceGate/App/FaceGateApp.swift`)
- App lifecycle → Launch monitor: starts monitoring (evidence: `FaceGate/App/AppDelegate.swift`)
- macOS apps → Launch monitor: reports launches (evidence: `README.md`)
- Launch monitor → Locked app list: checks lock list (evidence: `FaceGate/Core/AppMonitor.swift`)
- Launch monitor → Unlock sessions: checks sessions (evidence: `FaceGate/Core/AppMonitor.swift`)
- Launch monitor → Lock enforcement: enforces locks (evidence: `FaceGate/Core/AppLocker.swift`)
- Lock enforcement → Authentication overlay: shows gate (evidence: `FaceGate/Core/AppLocker.swift`)
- Lock enforcement → Unlock sessions: checks session (evidence: `FaceGate/Core/AppLocker.swift`)
- Lock enforcement → Locked app list: checks app state (evidence: `FaceGate/Core/AppLocker.swift`)
- Authentication overlay → Auth coordinator: requests authentication (evidence: `FaceGate/UI/AuthOverlayView.swift`)
- Auth coordinator → Face auth pipeline: starts face check (evidence: `FaceGate/Auth/AuthenticationManager.swift`)
- Auth coordinator → Touch ID: requests Touch ID (evidence: `FaceGate/Auth/AuthenticationManager.swift`)
- Auth coordinator → Password auth: verifies password (evidence: `FaceGate/Auth/AuthenticationManager.swift`)
- Authentication overlay → Unlock sessions: records unlock
- Face auth pipeline → Camera capture: starts capture (evidence: `FaceGate/FaceAuth/FaceAuthManager.swift`)
- Camera → Camera capture: provides frames (evidence: `FaceGate/FaceAuth/CameraManager.swift`)
- Face auth pipeline → Face detector: detects faces (evidence: `FaceGate/FaceAuth/FaceAuthManager.swift`)
- Face auth pipeline → Face embedder: generates embeddings (evidence: `FaceGate/FaceAuth/FaceAuthManager.swift`)
- Face auth pipeline → Face matcher: matches faces (evidence: `FaceGate/FaceAuth/FaceAuthManager.swift`)
- Face auth pipeline → Encrypted face data: loads enrollment (evidence: `FaceGate/FaceAuth/FaceAuthManager.swift`)
- Enrollment UI → Face enrollment: controls enrollment (evidence: `FaceGate/UI/FaceEnrollmentView.swift`)
- Face enrollment → Camera capture: captures frames (evidence: `FaceGate/FaceAuth/FaceEnrollmentManager.swift`)
- Face enrollment → Face detector: checks quality (evidence: `FaceGate/FaceAuth/FaceEnrollmentManager.swift`)
- Face enrollment → Face embedder: creates embeddings (evidence: `FaceGate/FaceAuth/FaceEnrollmentManager.swift`)
- Face enrollment → Encrypted face data: stores enrollment (evidence: `FaceGate/FaceAuth/FaceEnrollmentManager.swift`)
- Lock schedules → Locked app list: reads locked apps (evidence: `FaceGate/Core/AppScheduleManager.swift`)
- Lock schedules → Unlock sessions: creates sessions (evidence: `FaceGate/Core/AppScheduleManager.swift`)
- Locked app list → Lock schedules: records overrides (evidence: `FaceGate/Core/LockedAppsManager.swift`)
- User → Settings: configures (evidence: `FaceGate/UI/SettingsView.swift`)
- Settings → Locked app list: manages app locks (evidence: `FaceGate/UI/SettingsView.swift`)
- Settings → Lock schedules: configures schedules (evidence: `FaceGate/UI/SettingsView.swift`)
- Settings → Unlock sessions: configures timers (evidence: `FaceGate/UI/SettingsView.swift`)
- Settings → Encrypted face data: manages enrollment data (evidence: `FaceGate/UI/SettingsView.swift`)
- Initial setup → Enrollment UI: offers enrollment (evidence: `FaceGate/UI/SetupView.swift`)
- Initial setup → App picker: selects apps (evidence: `FaceGate/UI/SetupView.swift`)
- App picker → Locked app list: sets locked apps (evidence: `FaceGate/UI/AppPickerView.swift`)
- App picker → Installed app scanner: scans installed apps (evidence: `FaceGate/UI/AppPickerView.swift`)
- App lifecycle → Emergency hotkey: configures hotkey (evidence: `FaceGate/App/AppDelegate.swift`)
- App lifecycle → Sensitive-action auth: opens protected actions (evidence: `FaceGate/App/AppDelegate.swift`)
- App lifecycle → Settings: opens settings (evidence: `FaceGate/App/AppDelegate.swift`)
- App lifecycle → Initial setup: opens setup (evidence: `FaceGate/App/AppDelegate.swift`)
