🏗️ Technical Architecture

Project Structure

PrivacyInsights/
├── Services/           # Business logic
│   ├── URLScannerService.swift
│   ├── DomainSecurityCheckerService.swift
│   ├── DeviceSecurityCheckerService.swift
│   ├── NetworkScannerService.swift
│   ├── IPDeviceAnalyzerService.swift
│   ├── GeoIPService.swift
│   ├── TracerouteEngine.swift
│   ├── BluetoothDiscoveryService.swift
│   ├── TrackerMonitoringService.swift
│   ├── QRCodeScannerService.swift
│   ├── CookieInspectorService.swift
│   ├── ContentBlockerService.swift
│   ├── PrivacyLeakDetectorService.swift
│   ├── ThreatIntelligenceService.swift
│   ├── LongRunningTaskManager.swift    # Screen lock & state restoration
│   ├── SpeechTranscriptionService.swift
│   ├── AdaptiveLMSFilter.swift         # Audio noise cancellation
│   ├── ExtendedProfiling/              # Photo analysis services
│   │   ├── ExtendedProfilingService.swift
│   │   ├── PhotoFilterService.swift
│   │   ├── SmartSamplingService.swift
│   │   ├── ActivityDetectionService.swift
│   │   ├── SocialPatternService.swift
│   │   ├── LifeEventService.swift
│   │   ├── VehicleDetectionService.swift
│   │   ├── FoodDetectionService.swift
│   │   ├── SensitiveDocumentService.swift
│   │   ├── HomeAnalysisService.swift
│   │   ├── WorkAnalysisService.swift
│   │   └── ExtendedCacheService.swift
│   └── ...
├── Views/              # SwiftUI views
│   ├── ContentView.swift
│   ├── OverviewView.swift
│   ├── ToolsView.swift
│   ├── LearnView.swift
│   ├── ProtectView.swift
│   ├── DeviceSecurityCheckerView.swift
│   ├── BluetoothDiscoveryView.swift
│   ├── TrackerMonitoringView.swift
│   ├── BluetoothLocationHistoryMapView.swift
│   ├── InterruptedTasksView.swift
│   ├── SpeechTranscriptionView.swift
│   ├── MeetingTranscriptionView.swift
│   ├── ExtendedProfiling/              # Photo analysis views
│   │   ├── ExtendedProfilingView.swift
│   │   ├── ScopeSelectionView.swift
│   │   ├── ExtendedDashboardView.swift
│   │   └── ExtendedAnalysisProgressView.swift
│   └── ...
├── Models/             # Data models
│   ├── ExtendedProfilingModels.swift
│   ├── BluetoothHistoryModels.swift
│   ├── TranscriptionModels.swift
├── Utilities/          # Helper functions
│   ├── AsyncContentView.swift
│   ├── DeferredView.swift
│   └── ...
├── Resources/          # Databases and configuration
│   ├── bluetooth_database.json    # 170+ Bluetooth SIG Company IDs
│   ├── oui_database.json          # MAC address to manufacturer
│   ├── country_coordinates.json   # Country coordinates for map
│   └── geoip_city.bin             # GeoIP binary database
├── PrivacyInsightsContentBlocker/ # Safari Content Blocker
│   └── blockerList.json           # Standard blocking rules
└── PrivacyInsightsSafariExtension/ # Safari Web Extension
    ├── SafariWebExtensionHandler.swift  # Native messaging
    └── Resources/
        ├── background.js          # Service worker with caching
        ├── popup.js               # Extension popup logic
        └── popup.html             # Extension UI

Architecture Pattern

MVVM with Services Layer

Services Layer

• Business logic and data processing
• Network operations and API calls
• Device security checks
• Data persistence and caching

Views Layer

• SwiftUI views for UI presentation
• User interaction handling
• State management with @State, @StateObject, @ObservedObject

Models Layer

• Data structures and types
• Codable conformance for serialization
• Business domain models

Technology Stack

Language & Platform

• Swift 6.2 with strict concurrency checking
• iOS 26.0+ deployment target
• SwiftUI for UI framework
• Xcode project at PrivacyInsights/PrivacyInsights.xcodeproj

Key Frameworks

• CoreBluetooth - Bluetooth device discovery
• Network - Network scanning and connections
• CoreLocation - GPS tracking for monitoring
• AVFoundation - Camera for QR scanning, audio capture
• Speech - On-device speech recognition
• Vision - Image classification and OCR
• Photos - Photo library access and metadata
• WebKit - Cookie inspection and web content
• Security - SSL/TLS certificate validation
• LocalAuthentication - Biometric checks

Safari Extensions

• Content Blocker - Declarative blocking rules
• Web Extension - Dynamic rules with JavaScript
• Native Messaging - Communication between app and extension

Data Storage

App Group

group.com.privacyinsights.shared

• Shares data between main app and Safari Extension
• customBlockerRules.json for custom blocking rules

JSON-Based Databases

• bluetooth_database.json - Loaded dynamically at startup
• oui_database.json - MAC address lookup
• country_coordinates.json - Geographic data
• Fallback to hardcoded values if JSON not found

Binary Databases

• geoip_city.bin - Memory-mapped GeoIP database
• Binary format v2 with city-level resolution
• O(log n) lookup via binary search
• LRU cache for repeated lookups

UserDefaults

• @AppStorage for user preferences
• Terms of use acceptance
• App settings and configuration

SwiftUI Best Practices

Modern APIs

• NavigationStack instead of NavigationView
• LazyVStack for scrollable lists
• .foregroundStyle() instead of .foregroundColor()
• .clipShape() instead of .cornerRadius()
• .task modifier for async loading
• sheet(item:) for robust state handling

Concurrency

• @MainActor for all UI-related classes
• async/await for asynchronous operations
• Task { } for async operations in views
• nonisolated for delegate methods

State Management

• @StateObject for view-owned services
• @ObservedObject for injected services
• @State for view-local state
• @AppStorage for persistent preferences

Performance Optimizations

Memory Management

• Memory-mapped files for large databases (GeoIP)
• LRU caching for repeated lookups
• Lazy loading of resources
• Weak references in delegates and closures

Network Optimization

• Connection pooling with NWConnection
• Timeout configuration for network requests
• Parallel scanning with TaskGroup
• Cancel tasks when views disappear

UI Performance

• Extract subviews to prevent unnecessary redraws
• Use LazyVStack for large lists
• Avoid computed properties in body
• Batch UI updates with MainActor.run

Long-Running Task Management

Service: LongRunningTaskManager

Centralised management for tasks that require extended execution time.

Features

• Screen Lock Prevention - Keeps screen on during active tasks
• State Persistence - Saves task progress when app goes to background
• Task Restoration - Offers to resume interrupted tasks on app restart
• Background Task Handling - Requests extra time when app is suspended

Integrated Services

• ExtendedProfilingService - Photo analysis
• SpeechTranscriptionService - Speech transcription
• MeetingTranscriptionView - Meeting recording
• BluetoothDiscoveryService - Bluetooth scanning
• TrackerMonitoringService - Tracker monitoring and locating

Security & Privacy

Data Protection

• No logging of sensitive data
• Secure storage with Keychain (when needed)
• Clear sensitive data from memory
• Validate all external input

Network Security

• HTTPS for all network requests
• SSL certificate validation
• Handle certificate errors gracefully
• Escape special characters in URLs

iOS Sandbox

• Respects iOS security boundaries
• Cannot access other apps' data
• Limited to app-specific permissions
• App Group for extension communication