Skip to content

Architecture Overview

Jump to bottom
Simone Martorelli edited this page Mar 4, 2026 · 3 revisions

IBM Data Shift Architecture Overview

Introduction

IBM Data Shift is a native macOS application built with SwiftUI that enables secure, peer-to-peer migration of files, applications, and preferences between Mac devices. This document provides an architectural overview for developers, technical administrators, and anyone interested in understanding how the application works.

High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        GitHub Repository                        │
│                   (Source Code & Releases)                      │
└──────────────────────────────┬──────────────────────────────────┘
                               │ Download / Updates
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                         macOS Device                            │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │          IBM Data Shift (SwiftUI Native App)            │    │
│  │─────────────────────────────────────────────────────────│    │
│  │  - Runs entirely locally on macOS                       │    │
│  │  - No external servers required                         │    │
│  │  - Open-source executable                               │    │
│  │  - Peer-to-peer network architecture                    │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
                               ║
                               ║ Encrypted Peer-to-Peer Network
                               ║ (Bonjour Discovery + TLS 1.2+ PSK)
                               ║
┌──────────────────────────────▼───────────────────────────────────┐
│                    Second macOS Device                           │
│              (Source or Destination Device)                      │
│                                                                  │
│  - Same IBM Data Shift app running in opposite mode              │
│  - Direct peer-to-peer connection via local network              │
│  - TLS-encrypted data transfer (AES-256-GCM)                     │
│  - Passcode-authenticated connection                             │
│  - No internet or external servers required                      │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

Application Layers

1. Application Layer

Components:

  • MigratorApp (SwiftUI): App lifecycle management, window configuration, menu commands
  • MainView (SwiftUI): Page navigation controller and migration workflow orchestration
  • AppContext: Configuration management, UserDefaults integration, MDM profile settings

Responsibilities:

  • Managing the application lifecycle
  • Coordinating the migration workflow
  • Handling user interface navigation
  • Managing configuration and preferences

2. Controller Layer

Key Controllers:

MigrationController (Singleton)

  • Central migration orchestration
  • State management (discovery → completion)
  • Operating mode management (server/browser)
  • Progress tracking and reporting

Network Controllers

  • NetworkServer: Listener, Bonjour service, passcode authentication
  • NetworkBrowser: Discovery, Bonjour browsing, peer-to-peer discovery
  • NetworkConnection: Data transfer, framing protocol, protocol handling

Other Controllers

  • ArchitectureDetector: Checks application compatibility (Intel vs. Apple Silicon)
  • DeviceManagementHelper: Verifies MDM enrollment status
  • JamfReconManager: Manages Jamf inventory updates
  • MigrationReportController: Generates migration reports

3. Security & Encryption Layer

TLS 1.2+ with Pre-Shared Key (PSK)

  • Passcode-derived symmetric key (CryptoKit)
  • HMAC-SHA384 authentication
  • TLS_PSK_WITH_AES_256_GCM_SHA384 cipher
  • Build-unique PSK identity
  • All data transfer encrypted end-to-end
  • No certificates or PKI required

For detailed security information, see the Security Architecture page.

4. Model Layer

Core Models:

  • MigrationItem: Represents items to be migrated
  • MigrationOption: Migration mode selection (Lite, Complete, Advanced)
  • MigratorFile: File metadata and attributes
  • DiscoveredApplication: Application information and compatibility
  • MigratorPage: Page navigation state

Network Protocol Models:

  • MigratorNetworkProtocol: Custom protocol implementation
  • MigratorMessageType: Message type enumeration
  • DeviceInfoMessage: Device information exchange
  • FileMessage: File data transfer
  • DefaultsMessage: User defaults transfer
  • SymbolicLinkMessage: Symbolic link handling

Device Management Models:

  • ManagedEnvironment: MDM environment configuration
  • DeviceManagementState: Device management status

5. View Layer

Migration Workflow Views:

  • WelcomeView: Initial screen with device role selection
  • BrowserView: Discover source device (on destination)
  • ServerView: Wait for connection (on source)
  • CodeVerificationView: Passcode entry
  • MigrationSetupView: Select migration options
  • RecapView: Migration summary (optional)
  • MigrationView: Migration progress
  • AppleIDView: Apple ID login check (optional)
  • JamfReconView: Inventory update (optional)
  • RebootView: Reboot countdown (optional)
  • FinalView: Completion screen

Common UI Components:

  • CardButton, CustomAlertView, MigratorFileView
  • DeviceListRow, ScrollingTextView
  • CustomizableIconView (v1.3.0+)

Key Features

Peer-to-Peer Architecture

IBM Data Shift uses a direct peer-to-peer connection model:

  1. No Central Server: Devices communicate directly without intermediary servers
  2. Local Network: Discovery and transfer occur on the local network
  3. Bonjour/mDNS: Service discovery using Apple's Bonjour protocol
  4. Multiple Transports: Supports both Wi-Fi and Thunderbolt connections

Migration Modes

Lite Migration

  • Desktop and Documents folders only
  • Fast and simple
  • Ideal for basic data transfer

Complete Migration

  • All applications
  • User preferences
  • Entire User folder (excluding most of Library)
  • Application Support and Preferences from Library
  • Comprehensive migration experience

Advanced Selection

  • Manual selection of files and applications
  • Fine-grained control
  • User preferences and Application Support not migrated for selected apps

Architecture Compatibility (v1.4.0+)

  • Automatic detection of application architecture (Intel vs. Apple Silicon)
  • Warns users about incompatible applications
  • Options to ignore, review, or migrate anyway
  • Prevents issues with architecture-specific applications

Configuration Management

Compile-Time Configuration:

  • Defined in AppContext.swift
  • Requires recompilation to change
  • Includes default values and fallbacks

Runtime Configuration:

  • Deployed via MDM configuration profiles
  • UserDefaults-based settings
  • Can be updated without recompiling
  • Supports organization-specific customization

macOS System Integration

Frameworks Used

  • Foundation: File operations and system APIs
  • Network: Bonjour, peer-to-peer networking
  • AppKit: System integration and native UI elements
  • SwiftUI: Modern declarative UI framework
  • Combine: Reactive programming for state management
  • CryptoKit: Cryptographic operations

System Services

  • FileManager: File system access and operations
  • UserDefaults: Preferences and configuration
  • Bonjour/mDNS: Service discovery
  • Network.framework: Peer-to-peer connections
  • Launch Agents: Post-reboot app restart (when needed)

Optional MDM Integration

  • Jamf Pro: Inventory updates via recon
  • Configuration Profiles: Custom settings deployment
  • Managed Preferences: Organization-specific configuration
  • PPPC Profiles: Privacy permissions management

Data Flow

Discovery Phase

  1. User launches app on both devices
  2. User selects device role (old/new)
  3. New device starts NetworkServer (listener)
  4. Old device starts NetworkBrowser (discovery)
  5. Bonjour advertises/discovers services
  6. User selects target device from list

Connection Phase

  1. User enters passcode from new device
  2. PSK derived from passcode
  3. TLS connection established
  4. Devices exchange information
  5. Connection verified and ready

Migration Phase

  1. User selects migration mode
  2. App scans source device for files/apps
  3. Architecture compatibility check (v1.4.0+)
  4. User reviews and confirms selection
  5. Files transferred over encrypted connection
  6. Progress tracked on both devices
  7. Completion verified

Post-Migration Phase

  1. Apple ID login check (optional)
  2. System reboot (for Complete migration)
  3. Jamf inventory update (optional)
  4. Migration report generation (optional)
  5. Completion screen

Customization Points

Branding

  • App name and bundle identifier
  • App icons and page icons
  • Organization name
  • Copyright information

Behavior

  • MDM environment checking
  • Post-migration steps (Apple ID, Jamf recon)
  • Migration summary page visibility
  • Terms & Conditions acceptance

Migration Scope

  • URL exclusion list (with regex support v1.4.0+)
  • Explicit allow list (with regex support v1.4.0+)
  • Excluded file extensions
  • Excluded file prefixes
  • Duplicate file handling policy

User Interface

  • Custom page icons (v1.3.0+)
  • Welcome page information display
  • Legal document links (T&C, Privacy Policy, Third Party Notices)

For complete customization options, see the App Custom Settings guide.

Performance Considerations

Memory Optimization (v1.2.0+)

  • 90-95% reduction in RAM usage compared to v1.1.x
  • Optimized file discovery algorithms
  • Efficient memory management for large migrations

Network Optimization

  • TCP keepalive for connection stability
  • No delay option for reduced latency
  • Retry logic with exponential backoff
  • Timeout protection for operations

File Processing

  • Streaming file transfer (no full file buffering)
  • Efficient file attribute preservation
  • Optimized file parser
  • Parallel processing where applicable

Development and Build Process

Build-Time Code Generation

IBM Data Shift uses GYB (Generate Your Boilerplate) for build-time code generation:

  • BuildIdentity.generated.swift.gyb: Generates unique PSK identity per build
  • Ensures build isolation and security
  • Executed during Xcode build process

Testing

  • Xcode Unit Tests
  • UI Tests
  • SwiftLint for code quality
  • Pre-commit hooks for code standards

Distribution

  1. Archive in Xcode
  2. Sign with Developer ID Application certificate
  3. Submit to Apple notarization service
  4. Export notarized app
  5. Distribute via MDM or other channels

For detailed distribution instructions, see Sign, Notarize and Distribute the App.

Related Documentation

Technical Resources

For developers and contributors:

Last Updated: 2026-02-20
Document Version: 1.0
Based on IBM Data Shift v1.4.0

Clone this wiki locally