tcptop/.planning/PROJECT.md

tcptop

What This Is

A polished command-line utility that provides a real-time, top-like TUI for layer 4 (TCP/UDP) network statistics. It shows per-connection data — bytes, packets, latency, and state — in a sortable table with an aggregate summary header. It also supports CSV logging for offline analysis. Built in Rust using eBPF for kernel-level connection tracing on Linux.

Core Value

Live, accurate, per-connection network visibility from the terminal — the network equivalent of top.

Requirements

Validated

• eBPF-based kernel-level data collection for accurate, low-overhead tracing — v1.0
• Per-connection stats: bytes in/out, packets in/out, RTT/latency estimates, connection state — v1.0
• TCP and UDP protocol support — v1.0
• Real-time TUI with summary header (total connections, aggregate bandwidth) and sortable connection table — v1.0
• Filter by port (e.g., --port 443) — v1.0
• Filter by process (PID or process name) — v1.0
• CSV file logging mode (--log output.csv) — v1.0
• Installable distribution (cargo install, .deb/.rpm) — v1.0
• Man page / CLI help documentation — v1.0
• Test coverage for core functionality — v1.0

Active

(None — all v1 requirements shipped. Define next milestone requirements with /gsd:new-milestone.)

Out of Scope

• GUI or web interface — this is a terminal tool
• Layer 7 / application protocol inspection — stays at L4
• Historical data storage or built-in graphing — CSV export covers offline analysis
• Windows support — Linux only for v1
• macOS support — PKTAP packet capture provides degraded data fidelity vs Linux eBPF; not worth the complexity for v1
• JSON log format — CSV is sufficient for v1

Context

• Shipped v1.0 with 2,846 LOC Rust across 3 crates (tcptop, tcptop-ebpf, tcptop-common)
• Tech stack: Aya (eBPF), Ratatui (TUI), Tokio (async), clap (CLI), serde/csv (logging)
• 5 eBPF kernel programs: kprobes for tcp/udp send/recv + tracepoint for TCP state changes
• 15 automated tests covering aggregator, filtering, and CSV output
• Platform abstraction trait (NetworkCollector) exists for future cross-platform work
• macOS support dropped for v1 — PKTAP would provide degraded data fidelity vs eBPF

Constraints

• Privileges: Requires root/elevated permissions for kernel tracing — must handle gracefully when not root
• Platform: Linux-only for v1. Platform abstraction trait exists for future cross-platform work
• Language: Rust (preferred for performance, safety, and eBPF ecosystem)
• Overhead: Must be low-impact on the system being observed — no heavy polling

Key Decisions

Decision	Rationale	Outcome
Rust as implementation language	Best eBPF ecosystem (Aya), performance, safety	Confirmed — v1.0
eBPF for data collection	Most accurate, lowest overhead kernel-level tracing	Confirmed — v1.0
CSV for log format	Simple, universal, easy to import into analysis tools	Confirmed — v1.0
Summary + table TUI layout	Matches top mental model, provides both overview and detail	Confirmed — v1.0
macOS dropped for v1	PKTAP provides degraded fidelity vs eBPF; not worth complexity	Confirmed — v1.0

Evolution

This document evolves at phase transitions and milestone boundaries.

After each phase transition (via /gsd:transition):

1. Requirements invalidated? → Move to Out of Scope with reason
2. Requirements validated? → Move to Validated with phase reference
3. New requirements emerged? → Add to Active
4. Decisions to log? → Add to Key Decisions
5. "What This Is" still accurate? → Update if drifted

After each milestone (via /gsd:complete-milestone):

1. Full review of all sections
2. Core Value check — still the right priority?
3. Audit Out of Scope — reasons still valid?
4. Update Context with current state

---

Last updated: 2026-03-22 after v1.0 milestone — all 29 requirements shipped, 3 phases complete