Architecture

PortZero is structured as a Cargo workspace with multiple crates, each responsible for a distinct concern.

Crate overview

Crate	Purpose
`portzero-core`	Core library: proxy, router, recorder, process manager, mock engine, network sim, schema inference
`portzero-cli`	CLI binary (`portzero` command)
`portzero-api`	HTTP API server (axum) + WebSocket for real-time events
`portzero-mcp`	MCP server for AI agent integration
`portzero-desktop`	Tauri v2 desktop app

Crate dependency graph

Core components

The portzero-core crate is the heart of the system. It exports:

Router -- Maps subdomains to local ports
Recorder -- Captures request/response pairs to SQLite
ProcessManager -- Spawns, monitors, and restarts child processes
MockEngine -- Matches requests against mock rules and returns synthetic responses
NetworkSim -- Applies latency, loss, and bandwidth limits per-app
SchemaInference -- Builds OpenAPI schemas from observed traffic
TunnelManager -- Manages public tunnels via LocalUp
Store -- SQLite persistence layer (WAL mode, r2d2 pool)
WsHub -- WebSocket event broadcast hub

Proxy engine

PortZero uses Cloudflare Pingora as its proxy engine. Pingora is a battle-tested, multi-threaded async proxy framework used in production at Cloudflare. It provides:

HTTP/1.1 and HTTP/2 support
Native WebSocket upgrade handling
Connection pooling and keep-alive
Graceful shutdown and reload

Data flow

Request lifecycle through the proxy

State management

All persistent state is stored in SQLite using WAL (Write-Ahead Logging) mode for concurrent read performance. The database is managed via rusqlite with an r2d2 connection pool.

Stored data includes:

Captured request/response records
Mock rules
App registrations and status
Process logs
Inferred API schemas

Learn more

For the full 1300+ line architecture document, see ARCHITECTURE.md in the repository.