Skip to content

Architecture overview

This page summarizes how Trace captures, processes, and stores traffic on-device.

System design

Trace is split into two processes:

  • Main app: UI, configuration, and storage access
  • Network extension (TraceVPN): Packet tunnel + local MITM proxy

Communication happens through App Group storage, Darwin notifications, and NEAppMessages.

High-level flow

  1. The app enables capture and updates configuration.
  2. The VPN extension configures the system to use a local HTTP/HTTPS proxy.
  3. The proxy intercepts HTTP(S), WebSocket, and SSE traffic.
  4. Captured requests are persisted to the App Group container.
  5. The app receives notifications and updates the UI.

Data model

  • Sessions group captured requests and metadata.
  • Requests store headers, bodies, timing, and TLS details.
  • Artifacts include exports, scripts, rules, and settings snapshots.

Core components

Main app

  • TraceFeatures managers: rewrite rules, request maps, scripts, breakpoints, hosts, and favorites.
  • TraceUI views: Network list, request inspector, tools, and settings.
  • TraceCore storage: App Group container, sessions, and configuration.

Network extension (TraceVPN)

  • PacketTunnelProvider: configures NEPacketTunnelNetworkSettings and proxy settings.
  • MITMProxyServer (TraceProxy): HTTP/HTTPS proxy that performs TLS MITM when allowed.
  • TraceSecurity: certificate generation and TLS handling.
  • TraceNetworking: DNS query and response parsing, network diagnostics.
  • TraceQUIC: QUIC/HTTP3 client and MITM session orchestration via quiche FFI.

Capture modes

Proxy-only (default)

  • Uses NEProxySettings to route HTTP/HTTPS to 127.0.0.1:8888.
  • No packet routing; apps must honor system proxy settings.
  • QUIC/HTTP3 over UDP is not captured in this mode.

Full Tunnel (advanced)

  • Routes all traffic through the packet tunnel.
  • Optional SOCKS5 forwarder (uses built-in local server when empty).
  • Optional custom DNS, IPv6, and UDP forwarding mode.
  • Optional Hybrid TCP MITM for transparent decryption alongside proxy routing.
  • Supports raw PCAP capture.

Dual MITM (advanced)

  • Combines full packet-tunnel routing with transparent TCP MITM.
  • Always uses Trace's embedded local SOCKS5 forwarder; no external server needed.

Storage and IPC

  • App Group container: shared storage for requests, bodies, sessions, scripts, rules, and logs. Backed by a GRDB SQLite database. Request/response bodies above a small inline threshold are stored as separate files in the container.
  • Darwin notifications: notify the app when new data arrives from the extension.
  • Keychain: stores the Trace root CA and any signing credentials. Shared across app and extension via a keychain access group.
  • Fallback storage: used when App Group is unavailable (e.g., simulator).

Extension boundary

The network extension runs in a separate process with its own memory limits and lifecycle. Keep heavy work (parsing, persistence) efficient to avoid termination.

Security and privacy

  • On-device only: traffic stays on the device.
  • Explicit trust: HTTPS decryption only works after trusting the Trace root CA.
  • Bypass handling: certificate pinning or trust failures fall back to passthrough.

Proxy modes

Understand how capture modes differ

Learn more →

Certificates

Root CA and trust flow

Learn more →