# 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