Skip to content

Update PROJECT_STRUCTURE.md to reflect current codebase #95

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
NullPointerDepressiveDisorder merged 3 commits into from
Feb 3, 2026
Merged

Update PROJECT_STRUCTURE.md to reflect current codebase #95

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
62b777d
Update PROJECT_STRUCTURE.md to reflect current codebase
William-Laverty Feb 2, 2026
007d683
docs: remove redundant file reference
NullPointerDepressiveDisorder Feb 3, 2026
8c17214
docs: correct external package usage
NullPointerDepressiveDisorder Feb 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 0 additions & 109 deletions MiddleDrag/PROJECT_STRUCTURE.md
View file
Open in desktop

This file was deleted.

119 changes: 75 additions & 44 deletions PROJECT_STRUCTURE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,55 +6,76 @@ The project has been refactored from two large files into a modular, maintainabl

```
MiddleDrag/
├── Core/ # Core functionality
│ ├── MultitouchFramework.swift # Private API bindings and framework management
│ ├── GestureRecognizer.swift # Gesture detection and state management
│ └── MouseEventGenerator.swift # Mouse event generation and cursor control
├── Core/ # Core functionality
│ ├── MultitouchFramework.swift # Private API bindings and framework management
│ ├── GestureRecognizer.swift # Gesture detection and state management
│ ├── MouseEventGenerator.swift # Mouse event generation and cursor control
│ └── TouchDeviceProviding.swift # Protocol for device monitoring/dependency injection
│
├── Models/ # Data models
│ ├── TouchModels.swift # Touch data structures (MTPoint, MTTouch, etc.)
│ └── GestureModels.swift # Gesture state and configuration models
├── Models/ # Data models
│ ├── TouchModels.swift # Touch data structures (MTPoint, MTTouch, etc.)
│ └── GestureModels.swift # Gesture state and configuration models
│
├── Managers/ # Business logic managers
│ ├── MultitouchManager.swift # Main coordinator for gesture system
│ └── DeviceMonitor.swift # Device monitoring and callback management
├── Managers/ # Business logic managers
│ ├── MultitouchManager.swift # Main coordinator for gesture system
│ ├── DeviceMonitor.swift # Device monitoring and callback management
│ ├── AccessibilityMonitor.swift # Accessibility permission polling and app handling
│ └── AccessibilityWrappers.swift # Wrappers for accessibility system APIs (testability)
│
├── UI/ # User interface
│ ├── MenuBarController.swift # Menu bar UI management
│ └── AlertHelper.swift # Alert dialogs and user notifications
├── UI/ # User interface
│ ├── MenuBarController.swift # Menu bar UI management
│ └── AlertHelper.swift # Alert dialogs and user notifications
│
├── Utilities/ # Helper utilities
│ ├── PreferencesManager.swift # User preferences persistence
│ ├── LaunchAtLoginManager.swift # Launch at login functionality
│ └── AnalyticsManager.swift # Analytics and telemetry management
├── Utilities/ # Helper utilities
│ ├── PreferencesManager.swift # User preferences persistence
│ ├── LaunchAtLoginManager.swift # Launch at login functionality
│ ├── AnalyticsManager.swift # Analytics and telemetry management
│ ├── ScreenHelper.swift # Multi-monitor screen coordinate handling
│ ├── SystemGestureHelper.swift # System trackpad settings and process management
│ ├── UpdateManager.swift # App updates via Sparkle framework
│ └── WindowHelper.swift # Window detection under cursor
│
├── MiddleDragApp.swift # SwiftUI app entry point
├── AppDelegate.swift # Application delegate
├── Info.plist # App configuration
└── MiddleDrag.entitlements # App entitlements
├── MiddleDragApp.swift # SwiftUI app entry point
├── AppDelegate.swift # Application delegate
├── Info.plist # App configuration
└── MiddleDrag.entitlements # App entitlements
│
MiddleDragTests/ # Unit test target
├── GestureModelsTests.swift # Tests for gesture models
├── GestureRecognizerTests.swift # Tests for gesture recognition logic
└── TouchModelsTests.swift # Tests for touch data structures
MiddleDragTests/ # Unit test target
├── GestureModelsTests.swift # Tests for gesture models
├── GestureRecognizerTests.swift # Tests for gesture recognition logic
├── TouchModelsTests.swift # Tests for touch data structures
├── MouseEventGeneratorTests.swift # Tests for mouse event generation
├── MultitouchFrameworkTests.swift # Tests for multitouch framework bindings
├── MultitouchManagerTests.swift # Tests for main coordinator
├── DeviceMonitorTests.swift # Tests for device monitoring
├── AccessibilityMonitorTests.swift # Tests for accessibility permissions
├── MenuBarControllerTests.swift # Tests for menu bar UI
├── AlertHelperTests.swift # Tests for alert dialogs
├── PreferencesManagerTests.swift # Tests for preferences persistence
├── LaunchAtLoginManagerTests.swift # Tests for launch at login
├── AnalyticsManagerTests.swift # Tests for analytics
├── ScreenHelperTests.swift # Tests for screen coordinate handling
├── SystemGestureHelperTests.swift # Tests for system gesture settings
├── WindowHelperTests.swift # Tests for window detection
└── Mocks/ # Mock objects for testing
└── MockDeviceMonitor.swift # Mock device monitor
│
.github/ # GitHub configuration
├── workflows/ # CI/CD workflows
│ └── *.yml # GitHub Actions workflow files
├── ISSUE_TEMPLATE/ # Issue templates
└── copilot-instructions.md # Copilot configuration
.github/ # GitHub configuration
├── workflows/ # CI/CD workflows
│ └── *.yml # GitHub Actions workflow files
├── ISSUE_TEMPLATE/ # Issue templates
│
Root Files:
├── README.md # Project documentation
├── PROJECT_STRUCTURE.md # This file
├── LICENSE # MIT License
├── CODE_OF_CONDUCT.md # Community guidelines
├── CONTRIBUTING.md # Contribution guide
├── SECURITY.md # Security policy
├── build.sh # Build automation script
├── bump-version.sh # Version bump script
├── codecov.yml # Codecov configuration
└── .gitignore # Git ignore rules
├── README.md # Project documentation
├── PROJECT_STRUCTURE.md # This file
├── LICENSE # MIT License
├── CODE_OF_CONDUCT.md # Community guidelines
├── CONTRIBUTING.md # Contribution guide
├── SECURITY.md # Security policy
├── build.sh # Build automation script
├── bump-version.sh # Version bump script
├── codecov.yml # Codecov configuration
└── .gitignore # Git ignore rules
```

## Architecture Benefits
Expand Down Expand Up @@ -90,6 +111,7 @@ Root Files:
- **MultitouchFramework**: Interfaces with private Apple framework
- **GestureRecognizer**: Converts touch data into gestures
- **MouseEventGenerator**: Handles all mouse event synthesis
- **TouchDeviceProviding**: Protocol for device monitoring and dependency injection

### Model Layer
- **TouchModels**: Raw touch data structures
Expand All @@ -98,6 +120,8 @@ Root Files:
### Manager Layer
- **MultitouchManager**: Main coordinator, implements business logic
- **DeviceMonitor**: Manages device lifecycle and callbacks
- **AccessibilityMonitor**: Manages accessibility permission polling and app handling
- **AccessibilityWrappers**: Wrappers for system accessibility APIs (enables testability)

### UI Layer
- **MenuBarController**: All menu bar UI logic
Expand All @@ -107,11 +131,15 @@ Root Files:
- **PreferencesManager**: UserDefaults persistence
- **LaunchAtLoginManager**: System integration for auto-launch
- **AnalyticsManager**: Analytics and telemetry management
- **ScreenHelper**: Multi-monitor screen coordinate conversion (Cocoa ↔ Quartz)
- **SystemGestureHelper**: Trackpad settings and process management for testing
- **UpdateManager**: App updates via Sparkle framework (offline by default)
- **WindowHelper**: Detects window information under the cursor

### Test Layer
- **GestureModelsTests**: Unit tests for gesture state and configuration
- **GestureRecognizerTests**: Unit tests for gesture recognition logic including palm rejection
- **TouchModelsTests**: Unit tests for touch data structures
- Comprehensive unit tests for all components
- Mock objects for isolated testing
- Tests for gesture recognition, touch models, and UI components

## Design Patterns Used

Expand All @@ -120,6 +148,7 @@ Root Files:
3. **Observer Pattern**: Using NotificationCenter for preferences
4. **Factory Pattern**: Device creation in MultitouchFramework
5. **Strategy Pattern**: Configurable gesture recognition
6. **Protocol-Oriented Design**: For dependency injection and testability

## Adding New Features

Expand All @@ -131,11 +160,13 @@ To add a new feature, identify which layer it belongs to:
4. **New menu item?** → Add to MenuBarController
5. **New device support?** → Extend DeviceMonitor
6. **New test?** → Add to MiddleDragTests target
7. **Accessibility feature?** → Update AccessibilityMonitor
8. **Multi-monitor handling?** → Update ScreenHelper

## Dependencies

The refactored code maintains minimal dependencies:
- No external Swift packages required
- No external Swift packages required (except Sparkle for updates and Sentry for analytics/error reporting)
- Uses only system frameworks
- Private framework access isolated to one file

Expand Down