Architecture
A deep look at how Trace works under the hood. Understanding the technical foundation and design decisions.
System overview
Trace is built on iOS Network Extension framework, specifically implementing NEPacketTunnelProvider. This architecture enables system-level network visibility without requiring apps to route traffic through a local proxy. The system consists of three primary components that communicate via shared App Group container.
Main application
SwiftUI-based interface for viewing captured traffic, managing filters, and configuring settings. Reads data from shared App Group container and provides real-time updates. Handles export, search, replay, modification tools, and built-in utilities.
Network extension (TraceVPN)
Separate process running NEPacketTunnelProvider that captures IP packets. Implements MITM proxy with TLS handling and HTTP/2/WebSocket parsing. Writes captured data to shared App Group container.
Widget extension
WidgetKit bundle with standard widget, control widget, and Live Activity. Real-time network statistics and quick actions. Shares data through App Group container.
Network flow
Trace uses a VPN-based proxy mode to capture HTTP/HTTPS traffic. All captured traffic stays on-device and flows through a local MITM proxy server.
Network extension implementation
NEPacketTunnelProvider
Core component that implements virtual network interface. Receives all IP packets destined for network, allowing inspection before forwarding. Runs in separate process with elevated network privileges.
Packet processing pipeline
1. Packet capture
Intercept IP packets via packetFlow.readPackets(). Parse IP headers to identify protocol and endpoints. Forward packets to maintain connectivity while copying for analysis.
2. TCP reconstruction
Track TCP connections by five-tuple (src IP, src port, dst IP, dst port, protocol). Reassemble TCP segments in correct sequence order. Handle retransmissions, out-of-order delivery, and connection state.
3. HTTP parsing
Parse HTTP/1.1, HTTP/2, and HTTP/3 transactions from TCP stream. Extract method, path, headers, and body with protocol-specific features. Track WebSocket upgrades, SSE connections, and request-response pairs.
4. TLS interception
Intercept TLS handshakes on port 443. Present dynamically generated certificate to client. Establish separate TLS connection to actual server. Decrypt, inspect, and re-encrypt traffic transparently.
Certificate management
On-device certificate authority generates root CA on first launch. User installs root certificate via Settings → General → VPN & Device Management. Extension dynamically generates leaf certificates matching intercepted domains. Private keys never leave device.
Data storage and IPC
App Groups
Shared container enables communication between main app and extension. Both processes can read and write to shared directory. Used for configuration, captured traffic data, and coordination.
group.com.trace.network-debuggerPersistent storage
Structured storage for captured requests, responses, and configuration. Shared data accessible from app, extension, and widgets through App Group. Efficient querying and filtering with support for search and presets. Automatic cleanup with configurable retention policy.
Real-time updates
Extension writes new captures to shared storage. Main app observes data changes for UI updates. Widgets receive notifications for Live Activity updates. Minimal latency between capture and display across all components.
Protocol support
HTTP/HTTPS
Full HTTP/1.1, HTTP/2, and HTTP/3 support with complete parsing. HTTPS via TLS MITM with dynamic certificate generation. HTTP/2 stream info with HPACK table viewer and HTTP/3 protocol markers.
WebSocket
Detects WebSocket upgrade handshake. Captures and parses individual frames. Distinguishes text and binary frames. Tracks connection lifecycle.
Server-Sent Events
Recognizes SSE Content-Type header. Parses event stream format. Displays individual events with timing. Tracks connection duration.
TCP
Low-level TCP flow monitoring. Connection state tracking. Raw data inspection for non-HTTP protocols. Useful for debugging custom protocols.
Performance considerations
Packet processing efficiency
Minimal per-packet overhead to maintain network performance. Efficient buffer management reduces memory allocations. Parallel processing where possible without compromising order.
Memory management
Extension memory budget is limited by iOS. Aggressive cleanup of processed packets. Streaming write to Core Data instead of buffering in memory. Configurable retention policy prevents unbounded growth.
Battery impact
Background processing optimized for power efficiency. Packet forwarding path is lightweight. Heavy parsing done asynchronously off critical path. Extension can be disabled when not actively debugging.
Security model
On-device only
All traffic capture and analysis happens locally. No data transmission to external servers. No telemetry or analytics collection.
Root certificate trust
TLS interception requires explicit user action to trust root CA. Certificate installation flow clearly explains implications. Users maintain full control over certificate trust.
Data isolation
Captured data stored in app sandbox. No access from other apps without explicit export. Optional encryption for sensitive captured data.
Code transparency
Entire codebase is open source and auditable. No obfuscation or hidden functionality. Build from source to verify binary integrity.
Built with
Modern iOS frameworks and APIs.