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. The tunnel runs in proxy-only mode and configures system proxy settings to route HTTP/HTTPS through a local MITM proxy. Apps must honor the system proxy for their traffic to be captured. 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 in proxy-only mode. Configures system proxy settings and runs the local MITM proxy for HTTP/HTTPS. Handles TLS, HTTP/2, WebSocket, and SSE before writing captures to the App Group.
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 configures proxy-only VPN network settings via NEProxySettings. Starts the local MITM proxy and applies system proxy rules without routing packets. Runs in a separate process with elevated network privileges.
Proxy processing pipeline
1. Proxy configuration
Apply system proxy settings to route HTTP/HTTPS to the local MITM proxy. Start the proxy server and expose it on 127.0.0.1:8888.
2. HTTP parsing
Handle HTTP/1.1 and HTTP/2 requests and CONNECT tunnels in the proxy. Track WebSocket upgrades, SSE connections, and request-response pairs.
3. TLS interception
When the local CA is trusted and MITM is enabled, dynamically generate leaf certificates. Decrypt and re-encrypt HTTPS traffic in the proxy for inspection.
4. Storage and notifications
Persist captures to the App Group container and notify the main app. Widgets and Live Activities update from the shared storage.
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 and HTTP/2 support with complete parsing. HTTPS via TLS MITM with dynamic certificate generation. HTTP/2 stream info with HPACK table viewer.
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.
Limitations
Proxy-only mode captures HTTP/HTTPS for apps that honor system proxy settings. QUIC/HTTP/3 traffic is not captured in this mode. Apps that bypass proxy settings will not appear in captures.
Performance considerations
Proxy processing efficiency
Minimal per-connection overhead to maintain network performance. Efficient buffering reduces memory allocations under load. Parsing work is scheduled off the critical path where possible.
Memory management
Extension memory budget is limited by iOS. Aggressive cleanup of processed proxy data. Writes captures to App Group storage as JSON files. Configurable retention policy prevents unbounded growth.
Battery impact
Background processing optimized for power efficiency. Proxy handling path is lightweight. Heavy parsing done asynchronously off the 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.