tcptop/.planning/milestones/v1.0-ROADMAP.md

Roadmap: tcptop

Overview

tcptop is built in three phases that follow the data flow: first, get real connection data flowing from the kernel to userspace (the hardest engineering); second, build the interactive TUI that makes that data useful; third, add output modes, packaging, and test coverage to make it distributable on Linux. Each phase delivers a verifiable capability -- Phase 1 proves the data pipeline works, Phase 2 delivers a usable Linux tool, Phase 3 makes it installable and complete.

Phases

Phase Numbering:

• Integer phases (1, 2, 3, 4): Planned milestone work
• Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

• Phase 1: Data Pipeline - eBPF-based kernel data collection with platform abstraction, delivering real per-connection stats on Linux
• Phase 2: Interactive TUI - Real-time sortable connection table with filtering, keyboard controls, and summary header
• Phase 3: Output & Distribution - CSV logging, documentation, packaging, and test coverage (completed 2026-03-22)

Phase Details

Phase 1: Data Pipeline

Goal: Real connection data flows from the Linux kernel to userspace with per-connection stats available for consumption Depends on: Nothing (first phase) Requirements: DATA-01, DATA-02, DATA-03, DATA-04, DATA-05, DATA-06, DATA-07, PLAT-01, PLAT-03, OPS-01, OPS-02 Success Criteria (what must be TRUE):

1. Running tcptop on Linux with root prints per-connection byte and packet counts to stdout (proof of life)
2. Each connection row shows local/remote addresses, PID, process name, TCP state, and RTT estimate
3. UDP flows appear as synthesized connections (grouped by src/dst tuple) alongside TCP connections
4. Running without root produces a clear error message with instructions, not a Rust backtrace
5. The data collection imposes negligible overhead on the host (no heavy polling, eBPF ring buffer based) Plans: 3 plans

Plans:

• 01-01-PLAN.md -- Workspace scaffold, shared types, platform trait, privilege check
• 01-02-PLAN.md -- eBPF kernel programs and Linux collector
• 01-03-PLAN.md -- Aggregator, output formatter, and main event loop

Phase 2: Interactive TUI

Goal: Users can monitor and investigate network connections in real time through a polished terminal interface Depends on: Phase 1 Requirements: DISP-01, DISP-02, DISP-03, DISP-04, DISP-05, DISP-06, DISP-07, DISP-08, FILT-01, FILT-02, FILT-03, FILT-04 Success Criteria (what must be TRUE):

1. User sees a live-updating table of connections with a summary header showing total connections and aggregate bandwidth
2. User can sort the table by any column using keyboard shortcuts and filter the live view with '/' search
3. User can launch with --port, --pid/--process, --interface, or --tcp/--udp flags to see only matching connections
4. Connections are color-coded by bandwidth usage and the display refreshes at a configurable interval (--interval)
5. User can quit cleanly with 'q' or Ctrl-C and the terminal restores to its previous state Plans: 2 plans

Plans:

• 02-01-PLAN.md -- TUI module scaffold, App state, rendering (header/table/status bar), terminal lifecycle, clap CLI
• 02-02-PLAN.md -- Sort/filter/keyboard polish, CLI filter flags, human verification on Linux VM

Phase 3: Output & Distribution

Goal: tcptop is a complete, installable Linux tool with CSV logging, documentation, and test coverage Depends on: Phase 2 Requirements: OUTP-01, OUTP-02, OUTP-03, OUTP-04, OPS-03, OPS-05 Success Criteria (what must be TRUE):

1. User can run tcptop --log output.csv and get a CSV file with header row and periodic snapshots of all connections
2. User can run tcptop --help and see clear usage documentation; a man page is available
3. User can install via cargo install tcptop and via Homebrew
4. Core data processing and display logic have automated test coverage Plans: 3 plans

Plans:

• 03-01-PLAN.md -- CSV writer module, headless event loop, --log flag, CSV tests
• 03-02-PLAN.md -- Man page, package metadata, .deb/.rpm configuration
• 03-03-PLAN.md -- Expanded test coverage (aggregator + filtering), Linux VM verification

Progress

Execution Order: Phases execute in numeric order: 1 -> 2 -> 3

Phase	Plans Complete	Status	Completed
1. Data Pipeline	3/3	Complete	-
2. Interactive TUI	2/2	Complete	-
3. Output & Distribution	3/3	Complete	2026-03-22