# prithvisb08/neuromouse architecture

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

- Interactive diagram: https://gitdiagram.com/prithvisb08/neuromouse
- Repository: https://github.com/prithvisb08/neuromouse

## Overview

NeuroMouse has two runtimes: a native Swift macOS menu-bar/dashboard app and a Python reference prototype. Both turn webcam-based head motion into cursor control, with calibration, filtering, gesture input, and safety behavior; the README also describes headphone-triggered clicks and accessibility target gravity. The sampled Swift AppState excerpt and Python entry-point excerpt expose only parts of their processing loops, so unsampled subsystem connections are omitted rather than inferred.

Main entry points: [`macos-app/Sources/HeadMotionMouseCore/App/AppState.swift`](https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/App/AppState.swift) (App State), [`python-prototype/main.py`](https://github.com/prithvisb08/neuromouse/blob/main/python-prototype/main.py) (Python Entry), [`python-prototype/cursor/cursor_controller.py`](https://github.com/prithvisb08/neuromouse/blob/main/python-prototype/cursor/cursor_controller.py) (Python Cursor), [`macos-app/Sources/HeadMotionMouseCore/MotionEngine/MovementEngine.swift`](https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/MotionEngine/MovementEngine.swift) (Movement Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["App Runtime"]
  node_swiftapp["Swift App Entry"]
  node_appstate["App State<br/>[AppState.swift]"]
  node_dashboard["Dashboard"]
  node_settings[("Settings Store")]
  node_permissions["Permissions"]
  node_pythonmain["Python Entry<br/>[main.py]"]
end

subgraph group_perception["Camera Perception"]
  node_camera["Camera Capture"]
  node_landmarks["Face Landmarks"]
  node_pose["Craniofacial Pose"]
  node_headphonevision["Headphone Tracker"]
  node_pycamera["Python Camera<br/>[camera_manager.py]"]
  node_pyvision["Python Vision<br/>[face_landmarks.py]"]
end

subgraph group_motion["Motion Processing"]
  node_calibration["Calibration"]
  node_movement["Movement Engine"]
  node_deadzone["Dead Zone"]
  node_filter["1€ Filter"]
  node_pymotion["Movement Mapper<br/>[movement_mapper.py]"]
  node_pycalibration["Python Calibration<br/>[calibration.py]"]
end

subgraph group_interaction["Cursor Interaction"]
  node_gestures["Gesture Engine"]
  node_dwell["Dwell Detector"]
  node_tap["Headphone Tap"]
  node_hardware["Headphone Monitor"]
  node_gravity["Target Gravity"]
  node_cursor["Cursor Controller"]
  node_pygestures["Gesture Manager<br/>[gesture_manager.py]"]
  node_pyheadphone["Headphone Listener"]
  node_pycursor["Python Cursor"]
  node_scroll["Scroll Controller"]
end

node_user(("User"))

node_user -->|"launches"| node_swiftapp
node_swiftapp -->|"creates"| node_appstate
node_swiftapp -->|"presents"| node_dashboard
node_appstate -->|"loads"| node_settings
node_appstate -->|"checks"| node_permissions
node_appstate -->|"starts"| node_camera
node_appstate -->|"processes"| node_landmarks
node_appstate -->|"uses"| node_headphonevision
node_appstate -->|"configures"| node_movement
node_appstate -->|"calibrates"| node_calibration
node_appstate -->|"updates"| node_gestures
node_appstate -->|"commands"| node_cursor
node_appstate -->|"queries"| node_gravity
node_appstate -->|"routes"| node_tap
node_appstate -->|"monitors"| node_hardware
node_movement -->|"filters"| node_deadzone
node_movement -->|"smooths"| node_filter
node_gestures -->|"updates"| node_dwell
node_gravity -.->|"damps"| node_movement
node_gestures -.->|"clicks"| node_cursor
node_tap -.->|"triggers clicks"| node_cursor
node_hardware -.->|"detects input"| node_tap
node_user -->|"launches"| node_pythonmain
node_pythonmain -->|"captures"| node_pycamera
node_pythonmain -->|"initializes"| node_pymotion
node_pythonmain -->|"initializes"| node_pycalibration
node_pythonmain -->|"initializes"| node_pycursor
node_pyvision -->|"estimates pose"| node_pose
node_pythonmain -.->|"processes frames"| node_pyvision
node_pythonmain -.->|"updates"| node_pygestures
node_pygestures -->|"routes clicks"| node_pycursor
node_pyheadphone -.->|"triggers clicks"| node_pycursor
node_scroll -->|"dispatches scroll"| node_pycursor
node_pymotion -.->|"sets position"| node_pycursor

click node_swiftapp "https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseApp/HeadMotionMouseApp.swift"
click node_appstate "https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/App/AppState.swift"
click node_dashboard "https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Dashboard/DashboardWindowView.swift"
click node_settings "https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Settings/SettingsStore.swift"
click node_permissions "https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Permissions/PermissionManager.swift"
click node_camera "https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Camera/CameraManager.swift"
click node_landmarks "https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Vision/FaceLandmarkProcessor.swift"
click node_pose "https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/PoseEstimation/CraniofacialPoseEstimator.swift"
click node_headphonevision "https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Vision/HeadphoneVisualTracker.swift"
click node_calibration "https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Calibration/CalibrationManager.swift"
click node_movement "https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/MotionEngine/MovementEngine.swift"
click node_deadzone "https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/MotionEngine/DeadZoneProcessor.swift"
click node_filter "https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/MotionEngine/OneEuroFilter.swift"
click node_gestures "https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Gestures/GestureEngine.swift"
click node_dwell "https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Gestures/DwellClickDetector.swift"
click node_tap "https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Gestures/HeadphoneTapDetector.swift"
click node_hardware "https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Hardware/HeadphoneConnectionMonitor.swift"
click node_gravity "https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Cursor/AccessibilityGravityEngine.swift"
click node_cursor "https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Cursor/CursorController.swift"
click node_pythonmain "https://github.com/prithvisb08/neuromouse/blob/main/python-prototype/main.py"
click node_pycamera "https://github.com/prithvisb08/neuromouse/blob/main/python-prototype/camera/camera_manager.py"
click node_pyvision "https://github.com/prithvisb08/neuromouse/blob/main/python-prototype/vision/face_landmarks.py"
click node_pymotion "https://github.com/prithvisb08/neuromouse/blob/main/python-prototype/motion/movement_mapper.py"
click node_pycalibration "https://github.com/prithvisb08/neuromouse/blob/main/python-prototype/motion/calibration.py"
click node_pygestures "https://github.com/prithvisb08/neuromouse/blob/main/python-prototype/gestures/gesture_manager.py"
click node_pyheadphone "https://github.com/prithvisb08/neuromouse/blob/main/python-prototype/gestures/headphone_listener.py"
click node_pycursor "https://github.com/prithvisb08/neuromouse/blob/main/python-prototype/cursor/cursor_controller.py"
click node_scroll "https://github.com/prithvisb08/neuromouse/blob/main/python-prototype/cursor/scroll_controller.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_swiftapp,node_appstate,node_dashboard,node_settings,node_permissions,node_pythonmain,node_user toneBlue
class node_camera,node_landmarks,node_pose,node_headphonevision,node_pycamera,node_pyvision toneAmber
class node_calibration,node_movement,node_deadzone,node_filter,node_pymotion,node_pycalibration toneMint
class node_gestures,node_dwell,node_tap,node_hardware,node_gravity,node_cursor,node_pygestures,node_pyheadphone,node_pycursor,node_scroll toneRose
```

## Components

### App Runtime

- [Swift App Entry](https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseApp/HeadMotionMouseApp.swift): `macos-app/Sources/HeadMotionMouseApp/HeadMotionMouseApp.swift`
- [App State](https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/App/AppState.swift): `macos-app/Sources/HeadMotionMouseCore/App/AppState.swift`
- [Dashboard](https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Dashboard/DashboardWindowView.swift): `macos-app/Sources/HeadMotionMouseCore/Dashboard/DashboardWindowView.swift`
- [Settings Store](https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Settings/SettingsStore.swift): `macos-app/Sources/HeadMotionMouseCore/Settings/SettingsStore.swift`
- [Permissions](https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Permissions/PermissionManager.swift): `macos-app/Sources/HeadMotionMouseCore/Permissions/PermissionManager.swift`
- [Python Entry](https://github.com/prithvisb08/neuromouse/blob/main/python-prototype/main.py): `python-prototype/main.py`

### Camera Perception

- [Camera Capture](https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Camera/CameraManager.swift): `macos-app/Sources/HeadMotionMouseCore/Camera/CameraManager.swift`
- [Face Landmarks](https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Vision/FaceLandmarkProcessor.swift): `macos-app/Sources/HeadMotionMouseCore/Vision/FaceLandmarkProcessor.swift`
- [Craniofacial Pose](https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/PoseEstimation/CraniofacialPoseEstimator.swift): `macos-app/Sources/HeadMotionMouseCore/PoseEstimation/CraniofacialPoseEstimator.swift`
- [Headphone Tracker](https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Vision/HeadphoneVisualTracker.swift): `macos-app/Sources/HeadMotionMouseCore/Vision/HeadphoneVisualTracker.swift`
- [Python Camera](https://github.com/prithvisb08/neuromouse/blob/main/python-prototype/camera/camera_manager.py): `python-prototype/camera/camera_manager.py`
- [Python Vision](https://github.com/prithvisb08/neuromouse/blob/main/python-prototype/vision/face_landmarks.py): `python-prototype/vision/face_landmarks.py`

### Motion Processing

- [Calibration](https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Calibration/CalibrationManager.swift): `macos-app/Sources/HeadMotionMouseCore/Calibration/CalibrationManager.swift`
- [Movement Engine](https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/MotionEngine/MovementEngine.swift): `macos-app/Sources/HeadMotionMouseCore/MotionEngine/MovementEngine.swift`
- [Dead Zone](https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/MotionEngine/DeadZoneProcessor.swift): `macos-app/Sources/HeadMotionMouseCore/MotionEngine/DeadZoneProcessor.swift`
- [1€ Filter](https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/MotionEngine/OneEuroFilter.swift): `macos-app/Sources/HeadMotionMouseCore/MotionEngine/OneEuroFilter.swift`
- [Movement Mapper](https://github.com/prithvisb08/neuromouse/blob/main/python-prototype/motion/movement_mapper.py): `python-prototype/motion/movement_mapper.py`
- [Python Calibration](https://github.com/prithvisb08/neuromouse/blob/main/python-prototype/motion/calibration.py): `python-prototype/motion/calibration.py`

### Cursor Interaction

- [Gesture Engine](https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Gestures/GestureEngine.swift): `macos-app/Sources/HeadMotionMouseCore/Gestures/GestureEngine.swift`
- [Dwell Detector](https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Gestures/DwellClickDetector.swift): `macos-app/Sources/HeadMotionMouseCore/Gestures/DwellClickDetector.swift`
- [Headphone Tap](https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Gestures/HeadphoneTapDetector.swift): `macos-app/Sources/HeadMotionMouseCore/Gestures/HeadphoneTapDetector.swift`
- [Headphone Monitor](https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Hardware/HeadphoneConnectionMonitor.swift): `macos-app/Sources/HeadMotionMouseCore/Hardware/HeadphoneConnectionMonitor.swift`
- [Target Gravity](https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Cursor/AccessibilityGravityEngine.swift): `macos-app/Sources/HeadMotionMouseCore/Cursor/AccessibilityGravityEngine.swift`
- [Cursor Controller](https://github.com/prithvisb08/neuromouse/blob/main/macos-app/Sources/HeadMotionMouseCore/Cursor/CursorController.swift): `macos-app/Sources/HeadMotionMouseCore/Cursor/CursorController.swift`
- [Gesture Manager](https://github.com/prithvisb08/neuromouse/blob/main/python-prototype/gestures/gesture_manager.py): `python-prototype/gestures/gesture_manager.py`
- [Headphone Listener](https://github.com/prithvisb08/neuromouse/blob/main/python-prototype/gestures/headphone_listener.py): `python-prototype/gestures/headphone_listener.py`
- [Python Cursor](https://github.com/prithvisb08/neuromouse/blob/main/python-prototype/cursor/cursor_controller.py): `python-prototype/cursor/cursor_controller.py`
- [Scroll Controller](https://github.com/prithvisb08/neuromouse/blob/main/python-prototype/cursor/scroll_controller.py): `python-prototype/cursor/scroll_controller.py`

### Other components

- **User**

## Connections

- User → Swift App Entry: launches (evidence: `README.md`)
- Swift App Entry → App State: creates (evidence: `macos-app/Sources/HeadMotionMouseApp/HeadMotionMouseApp.swift`)
- Swift App Entry → Dashboard: presents (evidence: `macos-app/Sources/HeadMotionMouseApp/HeadMotionMouseApp.swift`)
- App State → Settings Store: loads (evidence: `macos-app/Sources/HeadMotionMouseCore/App/AppState.swift`)
- App State → Permissions: checks (evidence: `macos-app/Sources/HeadMotionMouseCore/App/AppState.swift`)
- App State → Camera Capture: starts (evidence: `macos-app/Sources/HeadMotionMouseCore/App/AppState.swift`)
- App State → Face Landmarks: processes (evidence: `macos-app/Sources/HeadMotionMouseCore/App/AppState.swift`)
- App State → Headphone Tracker: uses (evidence: `macos-app/Sources/HeadMotionMouseCore/App/AppState.swift`)
- App State → Movement Engine: configures (evidence: `macos-app/Sources/HeadMotionMouseCore/App/AppState.swift`)
- App State → Calibration: calibrates (evidence: `macos-app/Sources/HeadMotionMouseCore/App/AppState.swift`)
- App State → Gesture Engine: updates (evidence: `macos-app/Sources/HeadMotionMouseCore/App/AppState.swift`)
- App State → Cursor Controller: commands (evidence: `macos-app/Sources/HeadMotionMouseCore/App/AppState.swift`)
- App State → Target Gravity: queries (evidence: `macos-app/Sources/HeadMotionMouseCore/App/AppState.swift`)
- App State → Headphone Tap: routes (evidence: `macos-app/Sources/HeadMotionMouseCore/App/AppState.swift`)
- App State → Headphone Monitor: monitors (evidence: `macos-app/Sources/HeadMotionMouseCore/App/AppState.swift`)
- Movement Engine → Dead Zone: filters (evidence: `macos-app/Sources/HeadMotionMouseCore/MotionEngine/MovementEngine.swift`)
- Movement Engine → 1€ Filter: smooths (evidence: `macos-app/Sources/HeadMotionMouseCore/MotionEngine/MovementEngine.swift`)
- Gesture Engine → Dwell Detector: updates (evidence: `macos-app/Sources/HeadMotionMouseCore/Gestures/GestureEngine.swift`)
- Target Gravity → Movement Engine: damps
- Gesture Engine → Cursor Controller: clicks
- Headphone Tap → Cursor Controller: triggers clicks
- Headphone Monitor → Headphone Tap: detects input
- User → Python Entry: launches (evidence: `README.md`)
- Python Entry → Python Camera: captures (evidence: `python-prototype/main.py`)
- Python Entry → Movement Mapper: initializes (evidence: `python-prototype/main.py`)
- Python Entry → Python Calibration: initializes (evidence: `python-prototype/main.py`)
- Python Entry → Python Cursor: initializes (evidence: `python-prototype/main.py`)
- Python Vision → Craniofacial Pose: estimates pose (evidence: `python-prototype/vision/face_landmarks.py`)
- Python Entry → Python Vision: processes frames
- Python Entry → Gesture Manager: updates
- Gesture Manager → Python Cursor: routes clicks (evidence: `python-prototype/gestures/gesture_manager.py`)
- Headphone Listener → Python Cursor: triggers clicks
- Scroll Controller → Python Cursor: dispatches scroll (evidence: `python-prototype/cursor/scroll_controller.py`)
- Movement Mapper → Python Cursor: sets position
