345 lines
11 KiB
Markdown
345 lines
11 KiB
Markdown
---
|
|
source: ~/DuckDuckGo/apple-browsers.git/main/.cursor/rules/project-structure.mdc
|
|
confidence: 0.9
|
|
namespace: work
|
|
last_synced: 2026-04-28
|
|
alwaysApply: false
|
|
---
|
|
|
|
# Project Structure & Organization
|
|
|
|
## Workspace Structure
|
|
|
|
### Root Level
|
|
```
|
|
DuckDuckGo.xcworkspace/ # Main workspace (ALWAYS open this)
|
|
├── iOS/ # iOS app target
|
|
├── macOS/ # macOS app target
|
|
├── SharedPackages/ # Cross-platform Swift packages
|
|
├── fastlane/ # CI/CD automation
|
|
└── README.md # Main project documentation
|
|
```
|
|
|
|
### iOS App Structure
|
|
```
|
|
iOS/
|
|
├── DuckDuckGo/ # Main iOS app
|
|
│ ├── AppDelegate.swift # App lifecycle
|
|
│ ├── MainViewController.swift # Primary browser interface
|
|
│ ├── BrowserTab.swift # Tab state and WebKit integration
|
|
│ ├── AIChat/ # AI chat integration
|
|
│ ├── AppLifecycle/ # App lifecycle management
|
|
│ ├── Autofill/ # Form autofill features
|
|
│ ├── Bookmarks/ # Bookmark management
|
|
│ ├── BrowsingMenu/ # Browser menu UI
|
|
│ ├── Configuration/ # App configuration
|
|
│ ├── DataImport/ # Data import utilities
|
|
│ ├── HealthKitReporting/ # Health data reporting
|
|
│ ├── MainWindow/ # Main window controllers
|
|
│ ├── Subscription/ # Premium features
|
|
│ ├── SyncPrompt/ # Sync feature prompts
|
|
│ ├── TabSwitcher/ # Tab switching UI
|
|
│ └── WebView/ # Web view management
|
|
├── Core/ # iOS-specific shared utilities
|
|
├── AutofillCredentialProvider/ # Password autofill extension
|
|
├── PacketTunnelProvider/ # VPN network extension
|
|
├── OpenAction/ # Share sheet integration
|
|
├── Widgets/ # Home screen widgets
|
|
└── Configuration/ # Build configurations
|
|
```
|
|
|
|
### macOS App Structure
|
|
```
|
|
macOS/
|
|
├── DuckDuckGo/ # Main macOS app
|
|
│ ├── AppDelegate.swift # App lifecycle
|
|
│ ├── MainWindow.swift # Primary window controller
|
|
│ ├── BrowserTabViewController.swift # Web view management
|
|
│ ├── AIChat/ # AI chat integration
|
|
│ ├── Autofill/ # Form autofill features
|
|
│ ├── Bookmarks/ # Bookmark management UI
|
|
│ ├── Downloads/ # Download handling
|
|
│ ├── NavigationBar/ # URL bar and navigation
|
|
│ ├── NetworkProtection/ # VPN integration
|
|
│ ├── Preferences/ # Settings and preferences
|
|
│ ├── Subscription/ # Premium features
|
|
│ ├── SyncPrompt/ # Sync feature prompts
|
|
│ ├── TabBar/ # Tab management UI
|
|
│ └── WebView/ # Web view management
|
|
├── DuckDuckGoVPN/ # Standalone VPN app
|
|
├── NetworkProtectionSystemExtension/ # System-level VPN
|
|
├── DuckDuckGoDBPBackgroundAgent/ # Data Broker Protection
|
|
├── DuckDuckGoNotifications/ # System notifications
|
|
└── Configuration/ # Build configurations
|
|
```
|
|
|
|
## Dependencies and Packages
|
|
|
|
### Primary Dependency: BrowserServicesKit
|
|
```swift
|
|
// ✅ CORRECT - Always use BrowserServicesKit for shared functionality
|
|
import BrowserServicesKit
|
|
|
|
// Features provided by BrowserServicesKit:
|
|
// - Content blocking and privacy protection
|
|
// - Bookmarks and history management
|
|
// - Secure credential storage
|
|
// - Autofill functionality
|
|
// - Navigation handling
|
|
// - User script injection
|
|
// - Privacy configuration
|
|
// - Sync functionality
|
|
```
|
|
|
|
### Shared Packages
|
|
```
|
|
SharedPackages/
|
|
├── AIChat/ # AI chat functionality
|
|
├── BrowserServicesKit/ # Core browser services
|
|
├── DataBrokerProtectionCore/ # Data broker protection
|
|
├── DesignResourcesKitIcons/ # Shared icon resources
|
|
├── Onboarding/ # User onboarding experience
|
|
├── UIComponents/ # Reusable UI components
|
|
└── VPN/ # VPN functionality
|
|
```
|
|
|
|
### Package Dependencies
|
|
```swift
|
|
// ✅ CORRECT - Use shared packages for cross-platform features
|
|
import DesignResourcesKitIcons
|
|
import UIComponents
|
|
import BrowserServicesKit
|
|
|
|
// ❌ INCORRECT - Don't duplicate functionality across platforms
|
|
// Keep platform-specific code in iOS/ and macOS/ directories only
|
|
```
|
|
|
|
## Build Configuration
|
|
|
|
### Xcode Workspace Setup
|
|
```swift
|
|
// ✅ CORRECT - Always open workspace, not individual projects
|
|
// Open: DuckDuckGo.xcworkspace
|
|
// Don't open: iOS/DuckDuckGo-iOS.xcodeproj or macOS/DuckDuckGo-macOS.xcodeproj
|
|
```
|
|
|
|
### Build Requirements
|
|
```
|
|
iOS:
|
|
- Xcode 15.0 or later
|
|
- Swift 5.9 or later
|
|
- iOS 15.0+ deployment target
|
|
- Valid Apple Developer account
|
|
- Provisioning profiles for extensions
|
|
|
|
macOS:
|
|
- Xcode 15.0 or later
|
|
- Swift 5.9 or later
|
|
- macOS 11.4+ deployment target
|
|
- Developer ID certificate (for notarization)
|
|
- System extension entitlements
|
|
```
|
|
|
|
### Configuration Files
|
|
```
|
|
iOS/Configuration/
|
|
├── Configuration.xcconfig # Base configuration
|
|
├── Configuration-Alpha.xcconfig # Alpha build settings
|
|
├── Configuration-Debug.xcconfig # Debug build settings
|
|
└── BuildNumber.xcconfig # Build number management
|
|
|
|
macOS/Configuration/
|
|
├── Base.xcconfig # Base configuration
|
|
├── Debug.xcconfig # Debug build settings
|
|
├── Release.xcconfig # Release build settings
|
|
└── AppStore.xcconfig # App Store specific
|
|
```
|
|
|
|
## Development Setup
|
|
|
|
### Initial Setup
|
|
```bash
|
|
# ✅ CORRECT - Development setup steps
|
|
# 1. Open workspace at root level
|
|
open DuckDuckGo.xcworkspace
|
|
|
|
# 2. Install Ruby dependencies (for Fastlane)
|
|
bundle install
|
|
|
|
# 3. Ensure all certificates and provisioning profiles are installed
|
|
# 4. SwiftLint is enforced - run before committing
|
|
```
|
|
|
|
### Key Technologies
|
|
```swift
|
|
// iOS Stack
|
|
// - Language: Swift 5.9+
|
|
// - UI: UIKit with SwiftUI components
|
|
// - Architecture: MVVM with AppDependencyProvider
|
|
// - Web Engine: WebKit with privacy enhancements
|
|
|
|
// macOS Stack
|
|
// - Language: Swift 5.9+
|
|
// - UI: AppKit with SwiftUI components
|
|
// - Architecture: MVVM with Combine
|
|
// - Web Engine: WebKit with privacy enhancements
|
|
// - System Integration: Native macOS features
|
|
```
|
|
|
|
## App Extensions and System Integration
|
|
|
|
### iOS Extensions
|
|
```swift
|
|
// ✅ CORRECT - iOS extension organization
|
|
// AutofillCredentialProvider/ - Password autofill
|
|
// PacketTunnelProvider/ - VPN network extension
|
|
// OpenAction/ - Share sheet integration
|
|
// Widgets/ - Home screen widgets
|
|
```
|
|
|
|
### macOS Extensions
|
|
```swift
|
|
// ✅ CORRECT - macOS extension organization
|
|
// NetworkProtectionSystemExtension/ - System-level VPN
|
|
// DuckDuckGoDBPBackgroundAgent/ - Background data protection
|
|
// DuckDuckGoNotifications/ - System notifications
|
|
// VPNProxyExtension/ - VPN proxy functionality
|
|
```
|
|
|
|
## Testing Structure
|
|
|
|
### iOS Testing
|
|
```
|
|
iOS/
|
|
├── DuckDuckGoTests/ # Unit tests
|
|
├── IntegrationTests/ # Integration tests
|
|
├── PerformanceTests/ # Performance benchmarks
|
|
├── UITests/ # UI automation tests
|
|
├── SharedTestUtils/ # Shared test utilities
|
|
└── WebViewUnitTests/ # WebKit-specific tests
|
|
```
|
|
|
|
### macOS Testing
|
|
```
|
|
macOS/
|
|
├── UnitTests/ # Unit test suite
|
|
├── IntegrationTests/ # Integration testing
|
|
├── UITests/ # UI automation tests
|
|
└── SyncE2EUITests/ # End-to-end sync tests
|
|
```
|
|
|
|
## Important Files and Entry Points
|
|
|
|
### iOS Key Files
|
|
```swift
|
|
// Core Application Files
|
|
AppDelegate.swift # App lifecycle and initialization
|
|
MainViewController.swift # Primary browser interface
|
|
BrowserTab.swift # Tab state management
|
|
TabsBarViewController.swift # Tab bar UI (iPad)
|
|
BookmarksViewController.swift # Bookmarks management
|
|
PrivacyDashboardViewController.swift # Privacy protection UI
|
|
```
|
|
|
|
### macOS Key Files
|
|
```swift
|
|
// Core Application Files
|
|
AppDelegate.swift # App lifecycle management
|
|
MainWindow.swift # Primary window controller
|
|
BrowserTabViewController.swift # Web view management
|
|
NavigationBarViewController.swift # URL bar and controls
|
|
PreferencesViewController.swift # Settings interface
|
|
BookmarksBarViewController.swift # Bookmarks toolbar
|
|
```
|
|
|
|
## Common Development Tasks
|
|
|
|
### Running the Apps
|
|
```swift
|
|
// ✅ CORRECT - Running applications
|
|
// iOS: Select "iOS Browser" scheme and simulator/device
|
|
// macOS: Select "DuckDuckGo" scheme and click Run
|
|
```
|
|
|
|
### Adding New Features
|
|
```swift
|
|
// ✅ CORRECT - Feature development flow
|
|
// 1. Determine if feature belongs in:
|
|
// - BrowserServicesKit (shared functionality)
|
|
// - Platform-specific code (iOS/ or macOS/)
|
|
// 2. Use appropriate dependency injection patterns
|
|
// 3. Follow existing architecture patterns
|
|
// 4. Write comprehensive tests
|
|
```
|
|
|
|
### Debugging and Testing
|
|
```swift
|
|
// ✅ CORRECT - Testing and debugging
|
|
// - Run tests: Cmd+U or Test navigator
|
|
// - Use Safari Web Inspector for web content debugging
|
|
// - Enable verbose logging in Debug builds
|
|
// - Use Instruments for performance profiling
|
|
```
|
|
|
|
## Build Schemes and Configurations
|
|
|
|
### iOS Build Schemes
|
|
```
|
|
- DuckDuckGo (iOS) - Main app
|
|
- iOS Browser - Browser-specific build
|
|
- Alpha - Alpha testing build
|
|
- Debug - Development build
|
|
```
|
|
|
|
### macOS Build Schemes
|
|
```
|
|
- DuckDuckGo - Main app
|
|
- Debug - Development build
|
|
- Release - Release build
|
|
- Review - Review build
|
|
```
|
|
|
|
## Platform-Specific Considerations
|
|
|
|
### iOS-Specific Features
|
|
```swift
|
|
// iOS-specific implementations
|
|
// - iPad-specific UI adaptations
|
|
// - iPhone-specific layouts
|
|
// - iOS system integration
|
|
// - App Store requirements
|
|
```
|
|
|
|
### macOS-Specific Features
|
|
```swift
|
|
// macOS-specific implementations
|
|
// - Menu bar integration
|
|
// - Touch Bar support (MacBook Pro)
|
|
// - Dock integration
|
|
// - System extensions
|
|
// - Universal Binary (Intel + Apple Silicon)
|
|
// - Notarization requirements
|
|
```
|
|
|
|
## Development Best Practices
|
|
|
|
### Code Organization
|
|
```swift
|
|
// ✅ CORRECT - Follow established patterns
|
|
// - Use dependency injection via AppDependencyProvider
|
|
// - Keep platform-specific code in appropriate directories
|
|
// - Share common functionality through BrowserServicesKit
|
|
// - Follow MVVM architecture patterns
|
|
```
|
|
|
|
### Performance Considerations
|
|
```swift
|
|
// ✅ CORRECT - Performance optimization
|
|
// - Native Apple Silicon support
|
|
// - Efficient memory management
|
|
// - Hardware acceleration
|
|
// - Optimized content blocking
|
|
```
|
|
|
|
This structure ensures maintainable, testable code while providing comprehensive browser functionality across both iOS and macOS platforms.
|