| # 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 |
|
|
