tcptop/.planning/milestones/v1.0-phases/01-data-pipeline/01-CONTEXT.md

Phase 1: Data Pipeline - Context

Gathered: 2026-03-21 Status: Ready for planning

## Phase Boundary

eBPF-based kernel data collection with platform abstraction, delivering real per-connection stats on Linux. Running tcptop prints streaming per-connection data to stdout as proof-of-life. The interactive TUI, CSV logging, and macOS backend are separate phases.

## Implementation Decisions

Proof-of-life output format

• D-01: Streaming lines to stdout — each connection update prints a new line (like tail -f). No screen clearing or cursor manipulation.
• D-02: Human-readable sizes by default (1.2 MB, 340 KB/s). Show raw value alongside when it fits cleanly without noise (e.g., 1258291 (1.2M)). If too noisy, drop to human-readable only.
• D-03: Full detail per connection — all fields: local/remote addr+port, PID, process name, TCP state, bytes in/out, packets in/out, RTT, bandwidth rate.
• D-04: Output is assumed throwaway scaffolding. Build it simple; decide whether to keep as --batch mode when TUI lands in Phase 2.

UDP flow definition

• D-05: Full 4-tuple grouping — (src IP, src port, dst IP, dst port) = one flow. Most granular.
• D-06: 5-second idle timeout — UDP flows disappear 5s after last packet. Should be tunable via flag in the future (not Phase 1).
• D-07: No synthesized state for UDP — show - or UDP in the state column. Don't pretend UDP has connection states.
• D-08: Flat bidirectional flow tracking — count bytes/packets in each direction, no request/response inference.

Privilege error experience

• D-09: Minimal error message on missing privileges: error: tcptop requires root privileges. Run with sudo. No explanations, no offers to re-exec.
• D-10: If Linux capabilities (CAP_BPF, CAP_PERFMON) are present, proceed without root. But don't suggest or document capability setup in the error message.
• D-11: Exit code 77 on privilege failure (distinguishable from generic errors for scripting).

Connection lifecycle

• D-12: Closed TCP connections linger for one display/refresh cycle, then are removed. Duration scales with refresh rate.
• D-13: Visual distinction for new and closing connections — new connections get a brief highlight/marker, closing connections shown differently (dimmed, color change). Exact styling deferred to Phase 2.
• D-14: Connection close events print a line in streaming output: [CLOSED] 192.168.1.1:443 → ... so the full lifecycle is visible in the stream.
• D-15: Pre-existing connections (started before tcptop) are shown, sourced from /proc/net/tcp on startup. Marked so the user knows byte/packet counts are partial (started from zero, missed earlier traffic).

Claude's Discretion

• eBPF hook point selection (kprobes vs tracepoints)
• Platform abstraction trait design and boundaries
• Ring buffer vs perf event array for kernel-to-userspace transport
• RTT estimation implementation approach
• Exact format/layout of streaming output lines
• /proc/net/tcp parsing strategy for pre-existing connections
• Internal data structures and concurrency model

## Specific Ideas

• Human-readable vs raw byte display should eventually be toggleable (keypress or flag) — not required in Phase 1, but keep the formatting logic separable so it's easy to add later.
• The streaming output should feel like tail -f for network connections — familiar to anyone who monitors logs.

<canonical_refs>

Canonical References

No external specs — requirements are fully captured in decisions above and in:

• .planning/REQUIREMENTS.md — DATA-01 through DATA-07, PLAT-01, PLAT-03, OPS-01, OPS-02
• .planning/ROADMAP.md §Phase 1 — success criteria and plan structure
• CLAUDE.md §Technology Stack — Aya, tokio, recommended stack and version pins

</canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

• None — greenfield project, no code exists yet

Established Patterns

• None yet — Phase 1 establishes the foundational patterns (workspace structure, eBPF build pipeline, platform abstraction trait)

Integration Points

• Phase 2 (TUI) will consume the data structures and collection trait defined here
• Phase 4 (macOS) will implement the platform abstraction trait defined here

</code_context>

## Deferred Ideas

• UDP flow idle timeout should be user-configurable via CLI flag — capture for Phase 2 or 3
• Protocol hint column for well-known UDP ports (DNS, NTP, etc.) — future enhancement, not v1
• Toggle between human-readable and raw byte display via keypress — Phase 2 TUI feature
• --batch or --once mode if proof-of-life output proves useful — evaluate after Phase 2

---

Phase: 01-data-pipeline Context gathered: 2026-03-21