docs: initialize project

2026-03-24 22:27:26 +01:00
commit 4a183cdb65
1 changed files with 77 additions and 0 deletions
@@ -0,0 +1,77 @@
+# NetSynth
+
+## What This Is
+
+A Go CLI tool that captures live network traffic on an interface, clusters and classifies the packets by protocol/pattern, and synthesizes an ambient MP3 soundscape where each traffic type produces a distinct harmonic drone or tone. Run it, let it listen, hit Ctrl+C, and get an audio fingerprint of your network.
+
+## Core Value
+
+Network traffic patterns are instantly recognizable as distinct sounds — a ping sounds different from HTTPS noise, which sounds different from a port scan.
+
+## Requirements
+
+### Validated
+
+(None yet — ship to validate)
+
+### Active
+
+- [ ] Capture live packets from a specified network interface until interrupted (Ctrl+C)
+- [ ] Classify packets by known protocols (ICMP, TCP/HTTPS, DNS, SSH, etc.) using predefined rules
+- [ ] Auto-cluster unrecognized traffic patterns and assign them unique tones
+- [ ] Map each traffic class to a distinct harmonic/drone sound layer
+- [ ] Aggregate traffic into time windows to drive amplitude and tonal evolution
+- [ ] Synthesize ambient/drone audio from the layered sound mappings
+- [ ] Encode and save output as MP3 file
+- [ ] CLI interface with flags for interface selection and output file path
+
+### Out of Scope
+
+- Real-time audio playback — v1 is file output only
+- GUI or web interface — CLI only
+- Custom sound mapping configuration — predefined + auto-cluster only
+- Rhythmic/percussive output — ambient/drone style only
+
+## Context
+
+- Built in Go for single-binary distribution and performance
+- Needs packet capture (likely pcap/gopacket) — may require elevated privileges
+- Audio synthesis in Go is less common than Python; will need to evaluate libraries
+- MP3 encoding requires an encoder library or CGo bindings (e.g., LAME)
+- The "ambient/drone" style means layered sine/harmonic waves that evolve slowly based on traffic volume and mix, not discrete note triggers
+
+## Constraints
+
+- **Language**: Go — user preference, single binary output
+- **Privileges**: Packet capture requires root/CAP_NET_RAW on Linux
+- **Audio format**: MP3 output (not WAV or raw PCM)
+- **Interaction model**: Non-interactive capture (run → Ctrl+C → file saved)
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Go over Python/Rust | User preference, single binary, good perf | — Pending |
+| Ambient/drone style | Layered tones better represent continuous traffic patterns | — Pending |
+| Predefined + auto-cluster | Known protocols get recognizable sounds; unknown traffic still represented | — Pending |
+| File output only | Simpler v1, avoids real-time audio complexity | — Pending |
+
+## 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-24 after initialization*