docs/ARCHITECTURE.md

iOSDiag Architecture

Overview

iOSDiag is built on a layered architecture that separates concerns and enables modularity, testability, and extensibility.

Architecture Layers

1. Transport Layer

Location: src/transport/

Handles communication with iOS devices via different protocols:

• USBMUX: Direct USB connection via usbmuxd daemon
• CoreDevice: Network-based tunnel for newer iOS versions

Key Components:

• Transport trait: Abstract interface for device communication
• IoStream trait: Abstract interface for data streams
• Protocol-specific implementations

2. Security & Pairing Layer

Location: src/security/

Manages device pairing and cryptographic operations:

• Pairing: Establish trust with devices
• Crypto: RSA/ECDSA operations, certificate handling
• PairingStore: Persistent storage of pair records

Key Components:

• PairRecord: Device pairing information
• PairingStore: Pair record management
• Cryptographic utilities

3. Service Layer

Location: src/services/

Implements iOS service clients:

• Lockdown: Device configuration and service management
• DiagnosticsRelay: Hardware diagnostics data
• CrashReport: Crash and panic logs
• Syslog: System logs

Key Components:

• Service client implementations
• Message protocol handling
• Response parsing

4. Collection Layer

Location: src/collectors/

Gathers evidence from devices:

• DeviceInfo: Device identification
• Battery: Battery health metrics
• Charging: Power path information
• NAND: Storage health
• Wi-Fi: Radio diagnostics
• Thermal: Temperature sensors
• Reboot: Restart and panic events

Key Components:

• Collector trait: Evidence gathering interface
• Collector implementations
• EvidenceItem: Standardized evidence format

5. Normalization Layer

Location: src/normalize/

Converts raw evidence to canonical format:

• CanonicalReport: Standardized data structure
• Adapters: Format conversion utilities
• Versioning: Schema versioning support

Key Components:

• CanonicalReport: Normalized data model
• JSON schema definitions
• Version management

6. Inference Layer

Location: src/inference/

Analyzes evidence and generates findings:

• InferenceEngine: Rule evaluation
• RuleDSL: Rule definition language
• Scoring: Confidence calculation

Key Components:

• InferenceEngine: Main analysis engine
• DiagnosticRule: Rule definitions
• Scorer: Confidence scoring

7. Report Layer

Location: src/report/

Generates output reports:

• JSON: Structured data export
• HTML: Human-readable reports
• PDF: Printable reports

Key Components:

• Report: Report data model
• ReportBuilder: Builder pattern for reports
• Format-specific generators

8. CLI Layer

Location: crates/iosdiag-cli/

Command-line interface:

• Device discovery
• Pairing management
• Diagnostics collection
• Report generation

Data Flow

User Input (CLI)
    ↓
Transport Selection
    ↓
Device Discovery
    ↓
Pairing/Authentication
    ↓
Service Connection
    ↓
Evidence Collection
    ↓
Data Normalization
    ↓
Inference Analysis
    ↓
Report Generation
    ↓
Output (JSON/HTML/PDF)

Module Dependencies

CLI
├── Core Library
│   ├── Transport
│   │   └── Security
│   ├── Services
│   │   └── Security
│   ├── Collectors
│   │   └── Services
│   ├── Normalize
│   │   └── Collectors
│   ├── Inference
│   │   └── Normalize
│   └── Report
│       └── Normalize
└── Knowledge Base
    └── Inference

Design Patterns

1. Trait-Based Abstraction

• Transport, IoStream, Collector traits enable pluggable implementations
• Facilitates testing with mock implementations

2. Builder Pattern

• ReportBuilder for constructing complex reports
• Fluent API for configuration

3. Strategy Pattern

• Multiple transport implementations (USBMUX, CoreDevice)
• Multiple report formats (JSON, HTML, PDF)

4. Factory Pattern

• create_transport() for transport instantiation
• generate_report() for report generation

Error Handling

Comprehensive error types:

• TransportError: Communication failures
• ProtocolError: Protocol violations
• SecurityError: Authentication/pairing issues
• ServiceError: Service-level errors
• CollectorError: Data collection failures
• InferenceError: Analysis failures

Concurrency

• Async/Await: Tokio-based async runtime
• Send + Sync: Thread-safe components
• Mutex: Protected shared state

Testing Strategy

• Unit Tests: Individual module testing
• Integration Tests: Multi-module workflows
• Fixtures: Mock data and responses
• Smoke Tests: End-to-end scenarios

Extension Points

1. New Collectors: Implement Collector trait
2. New Services: Add service client implementations
3. New Rules: Add YAML rules to knowledge base
4. New Transports: Implement Transport trait
5. New Report Formats: Add format generators

Performance Considerations

• Lazy loading of collectors
• Parallel evidence collection
• Streaming report generation
• Efficient plist parsing
• Connection pooling for services

Security Considerations

• No private key exposure
• Secure pair record storage
• TLS for network communication
• Input validation
• Cryptographic verification

---

Last Updated: 2026-02-10
Version: 1.0.0