NetworkCity

A macOS network monitor that renders live traffic as a top-down city map — remote hosts become buildings, and your traffic becomes cars driving to them (SimCity-style). This repo currently contains Phase 1: the proven data layer.

Architecture

ConnectionSource (protocol)         ← the seam: "where bytes come from"
        │
        ├─ NettopSource             ← Phase 1: shells out to /usr/bin/nettop (no privileges)
        └─ (libpcap source)         ← Phase 2: real packets (needs privilege / helper tool)
                │
                ▼
        ConnectionSnapshot          ← list of Connection, with cumulative byte counts
                │
                ▼
        SpriteKit "city" (Phase 3)  ← buildings + cars; never knows the data source

The renderer depends only on NetworkCityCore, so the data backend can be swapped without touching the visuals.

Layout

• Sources/NetworkCityCore/ — models, the ConnectionSource protocol, the nettop parser (NettopParser, pure/testable) and poller (NettopSource).
• Sources/nettop-probe/ — Phase-1 CLI proof of concept. Prints live KB/s.
• Tests/ — parser tests pinned to real captured nettop output.

Try it

swift test                  # parser tests against real fixtures
swift run nettop-probe      # live traffic, busiest external flows as KB/s

Key design facts (learned from real output)

• nettop format: process rows are Name.PID,bytes_in,bytes_out; the connection sub-rows beneath inherit that process. IPv4 ports use :, IPv6 uses . and may carry a %zone suffix.
• Rates by diffing: byte counts are lifetime-cumulative, so we keep the last snapshot and subtract. Robust to nettop quirks; works across fresh invocations.
• Process names are unreliable — nettop truncates/mangles them (it reported claude as 2.1.177). The pid is trustworthy; enrich the real name via proc_pidpath/ps keyed on pid. (Phase-2 polish.)
• isExternal filters listeners, loopback, and link-local so only real off-box destinations become buildings.

Roadmap

1. ✅ Data layer + live probe (nettop, no privileges)
2. ✅ SpriteKit city — SwiftUI window, glowing buildings, cars of light (swift run NetworkCityApp): cyan cars inbound = downloads, amber outbound = uploads; deterministic building placement; drag to pan, scroll to zoom.
3. ✅ Enrichment — real process names (proc_pidpath), reverse-DNS + a curated CIDR table so hosts group into named districts (Apple, Google, AWS, Telegram, Local Network…). PTR is primary; the CIDR table catches the no-PTR giants (all of 17.0.0.0/8 is Apple). Run with NC_DEBUG=1 to log each host→district resolution to stderr.
4. ✅ Hub-and-spoke — busy districts auto-expand into their endpoints (This Mac → OneDrive → its many servers); cars route the full two-segment path. Expansion is a pure, tested ExpansionPolicy (≥2 endpoints, top-K by bytes, TTL tail to avoid flicker). A single client downloading from a CDN pins to one IP, so fan-out is driven by apps that genuinely spread connections (sync clients, browsers).
5. ✅ Traffic differentiation — cars coloured by protocol class (DNS gold, HTTPS cyan, HTTP orange, QUIC violet, Other slate) since direction is already read from motion. Behaviour reinforces it: DNS = tiny fast sparks, QUIC = streaks, heavy flows = big slow "freight" comets. Classifier is a pure tested TrafficClass; HUD shows a legend.
6. ✅ Label anti-overlap (LayoutSolver).
7. ✅ Click-to-inspect — click a district hub to open a live panel: total down/up, every endpoint with its reverse-DNS name + per-endpoint rate + protocol-colour dot, and the owning process(es). Click empty space or ✕ to close. A pulsing ring marks the selection. Click vs drag is disambiguated by movement distance.
8. ✅ Latency as distance — distance from downtown = measured round-trip time (unprivileged TCP-connect probe, cached), not geography. GeoIP was rejected because anycast makes it assert a physical fiction; latency is measured so it can't lie. Districts glide to their true distance as probes complete; the inspector shows per-endpoint ms. Pure LatencyLayout (log curve) is tested; LatencyProber uses Network.framework. Our own pid is filtered out so we don't render our own probes.
9. MenuBarExtra shell; optional libpcap source via privileged helper.

Env flags (opt-in diagnostics)

• NC_DEBUG=1 — log host→district resolution, per-tick top districts, and fan-outs to stderr.
• NC_DEMO=1 — offline demo: feeds a synthetic 8-endpoint "OneDrive" through the real scene so the hub-and-spoke fan-out runs without nettop.