yoloyolo/.planning/ROADMAP.md

Roadmap: NetSynth

Overview

NetSynth is built in four phases ordered by technical risk. Phase 1 validates the hardest foundation: live packet capture and protocol classification without any audio code. Phase 2 builds the synthesis and encoding engine in isolation against synthetic inputs, resolving audio-specific pitfalls before integration. Phase 3 wires the two pipelines together with coordinated Ctrl+C shutdown and auto-clustering, delivering the complete v1 MVP. Phase 4 adds power-user features (BPF filter, offline pcap input) that extend the core without blocking it.

Phases

Phase Numbering:

• Integer phases (1, 2, 3): 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: Capture and Classification - Live packet capture, protocol identification, and CLI scaffolding — no audio yet
• Phase 2: Audio Synthesis Engine - Oscillators, EMA amplitude smoothing, mixing, and MP3 encoding against synthetic inputs
• Phase 3: Pipeline Integration and MVP - Wire capture into synthesis, Ctrl+C with valid MP3 output, auto-clustering of unknown traffic
• Phase 4: Power User Features - BPF capture filter, offline pcap file input

Phase Details

Phase 1: Capture and Classification

Goal: Users can run the CLI against a live interface and see a live protocol classification summary — the full capture-to-classify pipeline validated without audio Depends on: Nothing (first phase) Requirements: CAPT-01, CAPT-02, CAPT-04, CLAS-01, CLAS-03, CLAS-04 Success Criteria (what must be TRUE):

1. User can run netsynth -i eth0 and see packets being classified live to stderr
2. User can run netsynth --list-interfaces and see all available network interfaces listed
3. User running without root/CAP_NET_RAW sees a clear error message with a sudo hint — not a panic or silent failure
4. On exit, user sees a per-protocol packet count summary printed to stderr
5. User can pass --verbose and see per-window protocol activity lines on stderr Plans: 1/4 plans executed

Plans:

• 01-01-PLAN.md — Go 1.24 setup, module init, shared types, config-driven classifier with tests
• 01-02-PLAN.md — Capture package: OpenCapture, ListInterfaces, privilege error handling
• 01-03-PLAN.md — Aggregation: time-windowed accumulator, exit summary, verbose output
• 01-04-PLAN.md — CLI wiring: Cobra commands, signal handling, pipeline assembly, smoke test

Phase 2: Audio Synthesis Engine

Goal: The synthesis and encoding stack produces a valid MP3 from synthetic WindowSnapshot inputs — audio pipeline fully validated before any real traffic flows through it Depends on: Phase 1 Requirements: SYNTH-01, SYNTH-02, SYNTH-03, OUT-01, OUT-02, OUT-03 Success Criteria (what must be TRUE):

1. Given synthetic traffic snapshots, the tool produces an MP3 file that passes ffprobe validation
2. Each traffic class (ICMP, DNS, TCP/443, TCP/other, UDP, SSH) produces a perceptually distinct drone tone
3. Drone layer amplitude rises and falls with traffic volume over time — sustained traffic sounds louder, quiet periods fade
4. User can specify output path via -o flag; it defaults to netsynth-<timestamp>.mp3 when omitted
5. An empty (zero-packet) input produces a clear error message instead of a corrupt or zero-byte MP3 Plans: TBD UI hint: no

Phase 3: Pipeline Integration and MVP

Goal: Live capture flows end-to-end into audio synthesis — the complete v1 MVP: run, capture, Ctrl+C, get an MP3 Depends on: Phase 2 Requirements: CAPT-03, CLAS-02 Success Criteria (what must be TRUE):

1. User runs netsynth -i eth0 -o out.mp3, generates traffic, presses Ctrl+C, and receives a valid playable MP3 at out.mp3
2. Unrecognized traffic patterns are automatically assigned distinct drone tones — unknown traffic is not silent or merged into a single undifferentiated layer
3. The MP3 audio reflects the actual traffic mix — a session with mostly DNS sounds different from one with mostly HTTPS Plans: TBD

Phase 4: Power User Features

Goal: Users can scope capture with BPF expressions and sonify historical pcap files Depends on: Phase 3 Requirements: CAPT-05, CAPT-06 Success Criteria (what must be TRUE):

1. User can run netsynth -i eth0 --filter "port 53" and only DNS traffic is captured and sonified
2. User can run netsynth --read capture.pcap -o out.mp3 against an existing pcap file and receive a valid MP3
3. An invalid BPF filter expression produces a clear error message before any capture begins Plans: TBD

Progress

Execution Order: Phases execute in numeric order: 1 → 2 → 3 → 4

Phase	Plans Complete	Status	Completed
1. Capture and Classification	1/4	In Progress
2. Audio Synthesis Engine	0/?	Not started	-
3. Pipeline Integration and MVP	0/?	Not started	-
4. Power User Features	0/?	Not started	-