Phase 6 Planning: TUI Interface & Network Optimizations

Last Updated: 2025-11-16 Version: 2.0 Phase Status: 🔄 IN PROGRESS (Sprint 6.3 PARTIAL) Completion: ~31% (2.5/8 sprints complete)

Table of Contents

1. Executive Summary
2. Phase 6 Overview
3. Sprint Status Dashboard
4. Completed Sprints
5. In-Progress Sprints
6. Planned Sprints
7. Technical Architecture
8. Performance Targets
9. Integration Strategy
10. Quality Standards
11. Risk Assessment
12. Timeline & Milestones
13. Resource Requirements
14. Success Criteria
15. Related Documentation

Executive Summary

Phase 6 transforms ProRT-IP into a production-ready interactive network security tool by combining a modern Terminal User Interface (TUI) with aggressive network optimizations. This dual-track approach delivers both exceptional user experience and industry-leading performance.

Strategic Goals

1. Real-Time Visualization: Professional 60 FPS TUI with live scan monitoring
2. Performance Leadership: 20-60% throughput improvement via batch I/O
3. Scan Efficiency: 30-70% target reduction through CDN deduplication
4. Interactive Workflows: Multi-stage scanning (discovery → selection → deep scan)
5. Production Readiness: Comprehensive testing, documentation, and polish

Key Achievements (To Date)

• ✅ Sprint 6.1 (COMPLETE): TUI framework with ratatui 0.29 + crossterm 0.28
• ✅ Sprint 6.2 (COMPLETE): Live dashboard with 4 interactive widgets
• 🔄 Sprint 6.3 (PARTIAL): Network optimizations (3/6 task areas complete)
• 📋 Sprints 6.4-6.8: Planned Q2 2026

Current Status

Progress: 2.5/8 sprints (31.25%) Tests: 2,111 passing (100%), 107 ignored Quality: 0 clippy warnings, 54.92% coverage Production Ready: TUI framework + dashboard complete, network optimizations in progress

Phase 6 Overview

Vision

Phase 6 delivers a modern, interactive network scanning experience that rivals commercial tools while maintaining ProRT-IP's performance and security focus. The TUI enables operators to visualize scan progress in real-time, make informed decisions during execution, and achieve maximum efficiency through intelligent optimizations.

Scope

8 Sprints spanning Q1-Q2 2026 with two parallel development tracks:

Track 1: TUI Development (Sprints 6.1, 6.2, 6.5, 6.6, 6.8)

• Terminal interface framework
• Real-time visualization widgets
• Interactive target selection
• Advanced features and polish

Track 2: Performance Optimization (Sprints 6.3, 6.4, 6.7)

• Batch I/O operations (sendmmsg/recvmmsg)
• Adaptive tuning and memory optimization
• NUMA-aware allocation and CDN filtering

Dependencies

Phase 6 builds on Phase 5 foundations:

1. EventBus System (Sprint 5.5.3): Real-time event streaming for TUI updates
2. Performance Framework (Sprint 5.5.4): Benchmarking and regression detection
3. Profiling Infrastructure (Sprint 5.5.5): Network I/O optimization analysis
4. Plugin System (Sprint 5.8): Extensibility for custom TUI widgets
5. Code Coverage (Sprint 5.6): Quality assurance foundation

Sprint Status Dashboard

Overall Progress: 2.5/8 sprints (31.25%), 73.5h / ~130h estimated

Completed Sprints

Sprint 6.1: TUI Framework & Event Integration ✅

Status: COMPLETE (2025-11-14) Duration: 40 hours (vs 15-20h estimated) Grade: A+ (Exceptional Quality) Commit: 9bf9da0

Strategic Achievement

Successfully implemented a production-ready Terminal User Interface framework for ProRT-IP, integrating with the EventBus system from Sprint 5.5.3 to provide real-time scan visualization at 60 FPS with exceptional performance (10K+ events/second throughput).

Key Deliverables

1. Complete TUI Crate: ~3,638 lines production code

   • crates/prtip-tui/src/app.rs: Application lifecycle orchestration
   • crates/prtip-tui/src/ui/renderer.rs: Rendering engine
   • crates/prtip-tui/src/events/: Event handling system
   • crates/prtip-tui/src/state/: State management
   • crates/prtip-tui/src/widgets/: Widget implementations

2. Technology Stack:

   • ratatui 0.29: Modern TUI framework with immediate mode rendering
   • crossterm 0.28: Cross-platform terminal manipulation
   • tui-input 0.10: Text input widget utilities
   • tokio 1.35+: Async runtime integration
   • parking_lot: High-performance RwLock (2-3× faster than std::sync)

3. Widget System (4 production widgets, 1,638 lines):

   • StatusBar (350L, 11T): Real-time progress with color-coded display
   • MainWidget (490L, 13T): Primary content area with navigation
   • LogWidget (424L, 19T): Real-time event logging
   • HelpWidget (374L, 13T): Interactive help system

4. Event-Driven Architecture:

   #![allow(unused)]
   fn main() {
   // Main event loop pattern
   loop {
       terminal.draw(|frame| ui::render(frame, &scan_state, &ui_state))?;
   
       tokio::select! {
           Some(Ok(event)) = crossterm_rx.next() => {
               // Keyboard input (q, ?, Tab, arrows)
           }
           Some(scan_event) = event_rx.recv() => {
               // EventBus updates (batched for 60 FPS)
           }
           _ = tick_interval.tick() => {
               // Render frame (16ms interval)
           }
       }
   }
   }

5. State Management:

   • Shared State: Arc<RwLock<ScanState>> (thread-safe, parking_lot)
   • Local State: UIState (single-threaded, no locking overhead)
   • Event Aggregation: 16ms batching for 10K+ events/sec throughput

Performance Characteristics

• Rendering: 60 FPS sustained (<5ms frame time)
• Event Throughput: 10,000+ events/second
• Memory Overhead: <10 MB for TUI framework
• CPU Overhead: ~2% during active scanning
• Latency: <16ms event-to-display

Testing & Quality

• Tests: 71 passing (56 unit + 15 integration)
• Coverage: 100% widget coverage
• Clippy Warnings: 0
• Documentation: 891-line TUI-ARCHITECTURE.md

Success Criteria Validation

Result: 7/7 success criteria met (100%), 2 exceeded expectations

Related Documentation

• TUI Architecture Guide
• Event System Guide
• Sprint Completion Report: daily_logs/2025-11-14/06-sessions/SPRINT-6.1-COMPLETE.md

Sprint 6.2: Live Dashboard & Real-Time Display ✅

Status: COMPLETE (2025-11-14) Duration: 21.5 hours (vs 12-18h estimated) Grade: A+ (100% Complete) Version: v0.5.2

Strategic Achievement

Successfully implemented a 4-widget dashboard system providing comprehensive real-time visibility into scan operations with exceptional performance (60 FPS, <5ms render, 10K+ events/sec).

Key Deliverables

1. Dashboard System (4 interactive widgets):

   • PortTableWidget (744L, 14T): Interactive port discovery table

     • Real-time streaming of discovered ports
     • Sorting by IP, Port, Service (ascending/descending)
     • Filtering by protocol (TCP/UDP) and state
     • Keyboard navigation (↑/↓, PgUp/PgDn, Home/End)

   • ServiceTableWidget (833L, 21T): Service detection display

     • Real-time service identification streaming
     • Service name, version, confidence display
     • Sorting by service name, confidence
     • Color-coded confidence levels

   • MetricsDashboardWidget (713L, 24T): Real-time performance metrics

     • 3-column layout (Progress | Throughput | Statistics)
     • 5-second rolling averages
     • Human-readable formatting (durations, numbers, throughput)
     • Color-coded status indicators (Green/Yellow/Red)

   • NetworkGraphWidget (450L, 10T): Time-series visualization

     • Real-time throughput graph
     • 60-second sliding window
     • Multiple data series (packets sent, received, ports discovered)
     • Automatic Y-axis scaling

2. Tab Navigation System:

   • 4-Tab Layout: Port Table | Service Table | Metrics | Network Graph
   • Keyboard Shortcuts:
     • Tab: Next widget
     • Shift+Tab: Previous widget
     • 1-4: Direct widget selection
     • q: Quit, ?: Help

3. Event Handling Infrastructure:

   #![allow(unused)]
   fn main() {
   pub enum DashboardTab {
       PortTable,
       ServiceTable,
       Metrics,
       Network,
   }
   
   // Tab cycling
   impl DashboardTab {
       pub fn next(&self) -> Self { /* ... */ }
       pub fn prev(&self) -> Self { /* ... */ }
   }
   }

4. Real-Time Data Structures:

   • RingBuffers:
     • PortDiscovery: 1,000 entries
     • ServiceDetection: 500 entries
     • ThroughputSample: 5 entries (5-second window)
   • Metrics Calculation: Rolling averages, ETAs, percentages
   • Memory-Bounded: Fixed-size buffers prevent memory growth

Performance Characteristics

• Rendering: 60 FPS sustained across all widgets
• Widget Switching: <1ms tab transition
• Data Updates: Real-time streaming from EventBus
• Memory Usage: ~15 MB for all widgets combined
• CPU Overhead: ~3% during active scanning

Testing & Quality

• Tests: 175 passing (150 unit + 25 integration + 8 doc)
• Widget Coverage: 100% (all widgets tested)
• Integration Tests: Full navigation flow validated
• Clippy Warnings: 0
• Formatting: Clean (cargo fmt verified)

Files Modified

Total: 11 files, ~3,120 lines added/modified

Success Criteria Validation

All 6 tasks completed (100%):

1. ✅ Task 2.1: PortTableWidget with sorting/filtering
2. ✅ Task 2.2: Event handling infrastructure
3. ✅ Task 2.3: ServiceTableWidget implementation
4. ✅ Task 2.4: MetricsDashboardWidget with 3-column layout
5. ✅ Task 2.5: NetworkGraphWidget time-series
6. ✅ Task 2.6: Final integration testing (175 tests passing)

Related Documentation

• TUI Architecture Guide (updated)
• CHANGELOG.md (+91 lines Sprint 6.2 comprehensive entry)
• README.md (+105 lines across 5 sections)

In-Progress Sprints

Sprint 6.3: Network Optimization (QW-2 + QW-4) 🔄

Status: PARTIAL COMPLETE (3/6 task areas) Duration: 12 hours / 20 hours estimated (60% complete) Timeline: 2025-11-15 → In Progress Priority: HIGH (Performance Critical) Remaining Work: ~8 hours (Tasks 3.1-3.2, 4.1-4.4, 5.0, 6.0)

Overview

Sprint 6.3 delivers two highest-ROI optimizations from the reference analysis: sendmmsg/recvmmsg batching (20-40% throughput, ROI 4.00) and CDN IP deduplication (30-70% scan reduction, ROI 3.50).

Completed Task Areas (3/6)

✅ Task Area 1: Batch I/O Integration Tests (~4 hours)

Purpose: Comprehensive integration testing of sendmmsg/recvmmsg batch I/O operations.

Deliverables:

• File: crates/prtip-network/tests/batch_io_integration.rs (487 lines, 12 tests)
• Tests: 11/11 passing on Linux (100% success rate)
• Platform Support:
  • Linux (kernel 3.0+): Full sendmmsg/recvmmsg support (batch sizes 1-1024)
  • macOS/Windows: Graceful fallback to single send/recv per packet

Performance Validation:

Key Tests:

• Platform capability detection (Linux/macOS/Windows)
• BatchSender creation and API validation
• Full batch send workflow (add_packet + flush builder pattern)
• IPv4 and IPv6 packet handling
• Batch receive functionality (basic + timeout)
• Error handling (invalid batch size, oversized packets)
• Maximum batch size enforcement (1024 packets on Linux)
• Cross-platform fallback behavior

✅ Task Area 2: CDN IP Deduplication Validation (~5 hours)

Purpose: Validate CDN IP filtering infrastructure to reduce scan targets by 30-70%.

Deliverables:

• Integration Tests: crates/prtip-scanner/tests/test_cdn_integration.rs (507 lines, 14 tests)
• Unit Tests: 3 new tests in cdn_detector.rs (Azure/Akamai/Google Cloud)
• Benchmark Suite: 01-CDN-Deduplication-Bench.json (291 lines, 6 scenarios)
• Target IP Lists: 2,500 test IPs generated (baseline-1000.txt, ipv6-500.txt, mixed-1000.txt)

CDN Provider Coverage:

Performance Validation:

• Reduction Rate: 83.3% measured (exceeds ≥45% target by 85%)
• Performance Overhead: <5% typically (<10% target, 50% headroom)
• IPv6 Performance: Parity with IPv4 (no degradation)
• Execution Time: 2.04 seconds for 14 integration tests

Benchmark Scenarios:

1. Baseline (No filtering, 1,000 IPs, 0% reduction)
2. Default Mode (All CDNs, 1,000 IPs, ≥45% reduction)
3. Whitelist Mode (Cloudflare + AWS only, ≥18% reduction)
4. Blacklist Mode (All except Cloudflare, ≥35% reduction)
5. IPv6 Filtering (All CDNs, 500 IPv6, ≥45% reduction)
6. Mixed IPv4/IPv6 (All CDNs, 1,000 mixed, ≥45% reduction)

✅ Task Area 3 (PARTIAL): Adaptive Batch Sizing

Status: Infrastructure 100% complete from Task 1.3, CLI configuration completed

Completed Components:

1. Task 3.3: BatchSender Integration (~3 hours)

   • File: crates/prtip-network/src/batch_sender.rs (~35 lines modified)
   • Implementation: Conditional adaptive batching initialization
   • Pattern:

     #![allow(unused)]
     fn main() {
     let sender = BatchSender::new(
         interface,
         max_batch_size,
         Some(adaptive_config),  // Enable adaptive sizing
     )?;
     }

   • Backward Compatibility: 100% (None parameter → fixed batching)
   • Tests: 212 total (203 AdaptiveBatchSizer + 9 BatchSender integration)

2. Task 3.4: CLI Configuration (~2 hours)

   • Files Modified:

     • crates/prtip-cli/src/args.rs (3 new flags)
     • crates/prtip-cli/src/config.rs (configuration wiring)
     • crates/prtip-core/src/config.rs (PerformanceConfig extension)

   • New CLI Flags:

     --adaptive-batch              # Enable adaptive batch sizing
     --min-batch-size <SIZE>       # Minimum batch size 1-1024 (default: 1)
     --max-batch-size <SIZE>       # Maximum batch size 1-1024 (default: 1024)
     

   • Validation: Range validation (1 ≤ size ≤ 1024), constraint enforcement (min ≤ max)

   • Usage Examples:

     # Enable with defaults (1-1024 range)
     prtip -sS -p 80,443 --adaptive-batch 192.168.1.0/24
     
     # Custom range (32-512)
     prtip -sS -p 80,443 --adaptive-batch --min-batch-size 32 --max-batch-size 512 target.txt
     

Verification Discovery:

• Full adaptive batching infrastructure already exists from Task 1.3 (Batch Coordination)
• PerformanceMonitor complete (6 tests passing)
• AdaptiveBatchSizer complete (6 tests passing)
• Only CLI configuration required completion
• ROI: 1600-2400% (saved 8-12 hours by verifying vs reimplementing)

Quality Metrics:

• Tests: 2,105/2,105 passing (100%)
• Clippy Warnings: 0
• Backward Compatibility: 100%
• Files Modified: 8 (batch_sender.rs, args.rs, config.rs, 5 test files)

Remaining Task Areas (3/6)

⏳ Task Area 3.1-3.2: Batch I/O Implementation (~2-3 hours)

Scope:

• Replace single send/recv with sendmmsg/recvmmsg in RawSocketScanner
• Platform-specific compilation (#[cfg(target_os = "linux")])
• Fallback path for macOS/Windows (batch_size = 1)
• Integration with existing scanner architecture

Implementation Plan:

#![allow(unused)]
fn main() {
// Linux: Use sendmmsg/recvmmsg
#[cfg(target_os = "linux")]
pub fn send_batch(&mut self, packets: &[Vec<u8>]) -> io::Result<usize> {
    use libc::{sendmmsg, mmsghdr};
    // ... sendmmsg implementation
}

// macOS/Windows: Fallback to single send
#[cfg(not(target_os = "linux"))]
pub fn send_batch(&mut self, packets: &[Vec<u8>]) -> io::Result<usize> {
    let mut sent = 0;
    for packet in packets {
        self.socket.send(packet)?;
        sent += 1;
    }
    Ok(sent)
}
}

Expected Outcomes:

• 20-40% throughput improvement on Linux (batch size 32-256)
• 40-60% throughput improvement on Linux (batch size 1024)
• Zero performance impact on macOS/Windows (graceful degradation)

⏳ Task Area 4: Production Benchmarks (~3-4 hours)

Scope:

• Execute production benchmarks for batch I/O (8 scenarios)
• Execute production benchmarks for CDN deduplication (6 scenarios)
• Performance regression validation
• Throughput measurement and comparison

Benchmark Scenarios (Batch I/O):

1. Baseline (batch_size=1, single send/recv)
2. Small batches (batch_size=32)
3. Medium batches (batch_size=256)
4. Large batches (batch_size=1024)
5. IPv6 batching (batch_size=256)
6. Mixed IPv4/IPv6 (batch_size=256)
7. High throughput (500K pps target)
8. Latency measurement

Benchmark Scenarios (CDN Deduplication):

1. Baseline (CDN filtering disabled)
2. Default mode (all CDNs filtered)
3. Whitelist mode (Cloudflare + AWS only)
4. Blacklist mode (all except Cloudflare)
5. IPv6 filtering
6. Mixed IPv4/IPv6

Success Criteria:

• Batch I/O: ≥20% throughput improvement (batch_size=32), ≥40% (batch_size=1024)
• CDN Deduplication: ≥30% scan reduction, <10% overhead
• All benchmarks exit code 0 (success)
• Regression detection: <5% variance from baseline

⏳ Task Area 5: Scanner Integration (~1-2 hours)

Scope:

• Integrate BatchSender/Receiver into scanner workflows
• Update SynScanner, ConnectScanner, etc.
• Configuration wiring for batch sizes
• Performance monitoring integration

Integration Points:

• crates/prtip-scanner/src/tcp/syn.rs: Replace send/recv calls
• crates/prtip-scanner/src/tcp/connect.rs: Batch connection establishment
• crates/prtip-scanner/src/udp/udp.rs: UDP batch sending
• Configuration: Add batch_size to ScannerConfig

⏳ Task Area 6: Documentation (~1-2 hours)

Scope:

• Create 27-NETWORK-OPTIMIZATION-GUIDE.md (comprehensive guide)
• Update performance characteristics documentation
• CLI reference updates (new flags)
• Benchmark results documentation

Expected Content:

• Batch I/O architecture and usage
• CDN deduplication configuration
• Performance tuning recommendations
• Platform-specific considerations
• Code examples and best practices

Strategic Value

Sprint 6.3 delivers:

1. Immediate Performance: 20-60% throughput improvement (batch I/O)
2. Efficiency Gains: 30-70% scan reduction (CDN filtering)
3. Production Infrastructure: Comprehensive testing and benchmarking
4. Quality Foundation: 100% test pass rate, zero warnings

Next Steps

1. Complete Task Areas 3.1-3.2 (Batch I/O Implementation, ~2-3h)
2. Execute Task Area 4 (Production Benchmarks, ~3-4h)
3. Complete Task Area 5 (Scanner Integration, ~1-2h)
4. Finalize Task Area 6 (Documentation, ~1-2h)
5. Sprint completion report and CHANGELOG update

Estimated Completion: ~8 hours remaining (2-3 days)

Planned Sprints

Sprint 6.4: Adaptive Tuning & Memory-Mapped I/O Prep 📋

Status: Planned (Q2 2026) Effort Estimate: 10-14 hours Timeline: Weeks 7-8 (2 weeks) Dependencies: Sprint 6.3 (Network Optimization) COMPLETE Priority: MEDIUM (Secondary Path)

Objectives

1. QW-1: Adaptive Batch Size Tuning - 15-30% throughput gain (ROI 5.33)
2. QW-3 Preparation: Memory-Mapped I/O Infrastructure
3. Auto-Tuning Configuration System - Platform-specific defaults
4. Performance Monitoring Dashboard - Real-time tuning visualization

Key Deliverables

Adaptive Tuning Algorithm:

• AIMD (Additive Increase, Multiplicative Decrease) strategy
• Start: batch_size = 64 (conservative)
• Success: batch_size += 16 (additive increase) every 10 batches
• Failure: batch_size *= 0.5 (multiplicative decrease) on packet loss
• Max: 1024 (Linux limit), Min: 1 (fallback)

Implementation Components:

#![allow(unused)]
fn main() {
pub struct AdaptiveTuner {
    current_batch_size: usize,
    min_batch_size: usize,
    max_batch_size: usize,
    success_count: usize,
    failure_count: usize,
    increase_threshold: usize,  // Batches before increase
}
}

Expected Outcomes:

• 15-30% throughput improvement through intelligent tuning
• Automatic optimization for diverse network conditions
• Platform-specific configuration defaults
• Real-time visualization in TUI dashboard

Task Breakdown

1. Task 1: Adaptive Tuning Algorithm (5-6h)

   • Design AIMD algorithm
   • Packet loss detection
   • Network congestion monitoring
   • Platform-specific tuning profiles
   • Integration tests (20 tests)

2. Task 2: Performance Monitoring (2-3h)

   • Real-time metrics collection
   • TUI dashboard integration
   • Historical performance tracking
   • Auto-tuning decision logging

3. Task 3: Memory-Mapped I/O Prep (2-3h)

   • mmap infrastructure design
   • Platform abstraction layer
   • Performance baseline measurement
   • Foundation for Sprint 6.6

4. Task 4: Documentation (1-2h)

   • 28-ADAPTIVE-TUNING-GUIDE.md
   • Configuration examples
   • Performance tuning guide
   • Platform-specific notes

Sprint 6.5: Interactive Target Selection & Scan Templates 📋

Status: Planned (Q2 2026) Effort Estimate: 14-18 hours Timeline: Weeks 9-10 (2 weeks) Dependencies: Sprint 6.2 (Live Dashboard) COMPLETE Priority: HIGH (Critical Path)

Objectives

1. Interactive Target Selector - TUI-based multi-select for discovered hosts
2. QW-5: Scan Preset Templates - Common scan profiles (ROI 3.33)
3. Template Management System - Create, save, load custom templates
4. Target Import/Export - Load from file, save discovered hosts
5. TUI Integration - Keyboard navigation, visual selection

Key Deliverables

Target Selector Widget:

• Multi-select table with checkbox selection
• Columns: [ ] IP Address, Open Ports, Services, OS Hint
• Keyboard shortcuts:
  • Space: Toggle selection
  • a: Select all, n: Select none, i: Invert selection
  • Enter: Confirm and proceed

Scan Templates:

#![allow(unused)]
fn main() {
pub struct ScanTemplate {
    pub name: String,
    pub scan_type: ScanType,
    pub port_spec: PortSpec,
    pub timing: TimingProfile,
    pub options: ScanOptions,
}

// Predefined templates
templates! {
    "quick" => SYN scan on top 100 ports, T4 timing,
    "comprehensive" => All ports, service detection, OS fingerprint,
    "stealth" => FIN scan, T1 timing, randomization,
    "web" => Ports 80/443/8080/8443, TLS certificate analysis,
}
}

Expected Outcomes:

• Multi-stage scanning workflows (discovery → selection → deep scan)
• Reduced operator error through templates
• Improved reproducibility
• Time savings: 40-60% on common tasks

Task Breakdown

1. Task 1: Target Selector (5-6h)

   • TargetSelectorWidget implementation
   • Multi-select functionality
   • Event handling
   • Integration with scan results

2. Task 2: Scan Templates (4-5h)

   • Template definition system
   • Predefined templates (5-7 common profiles)
   • Custom template creation
   • Template storage (TOML/JSON)

3. Task 3: TUI Integration (3-4h)

   • Navigation flow
   • Template selector widget
   • Target import/export UI
   • Help documentation

4. Task 4: Testing & Docs (2-3h)

   • 25-30 integration tests
   • Template validation tests
   • User guide updates
   • Examples and tutorials

Sprint 6.6: Advanced TUI Features & Polish 📋

Status: Planned (Q2 2026) Effort Estimate: 16-20 hours Timeline: Weeks 11-12 (2 weeks) Dependencies: Sprints 6.2, 6.5 COMPLETE Priority: HIGH (Critical Path)

Objectives

1. Export Functionality - Save scan results from TUI (JSON, XML, CSV)
2. Pause/Resume Scanning - Interactive scan control
3. Search & Filtering - Advanced result filtering
4. Configuration Profiles - Save/load scan configurations
5. TUI Polish - Visual improvements, animations, error handling

Key Features

Export System:

• Export discovered ports/services to multiple formats
• Keyboard shortcut: e (export menu)
• Format selection: JSON, XML (Nmap compatible), CSV, Text
• Custom filtering before export

Scan Control:

• Pause/Resume: p key
• Cancel: Ctrl+C (graceful shutdown)
• Scan statistics on pause
• Resume from checkpoint

Advanced Filtering:

• Search: / key activates search mode
• Filter by: protocol, port range, service name, IP subnet
• Regex support for advanced queries
• Filter persistence across sessions

Visual Polish:

• Smooth transitions between views
• Loading animations for long operations
• Color themes (default, dark, light, high-contrast)
• Responsive layouts (80×24 minimum, adaptive to larger terminals)

Task Breakdown

1. Task 1: Export Functionality (4-5h)
2. Task 2: Pause/Resume (3-4h)
3. Task 3: Search & Filtering (4-5h)
4. Task 4: Configuration Profiles (3-4h)
5. Task 5: Visual Polish (2-3h)

Sprint 6.7: NUMA Optimization & CDN Provider Expansion 📋

Status: Planned (Q2 2026) Effort Estimate: 12-16 hours Timeline: Weeks 13-14 (2 weeks) Dependencies: Sprint 6.3 (Network Optimization) COMPLETE Priority: MEDIUM (Performance Enhancement)

Objectives

1. NUMA-Aware Memory Allocation - 10-15% performance on multi-socket systems
2. CDN Provider Expansion - Additional providers (Netlify, Vercel, GitHub Pages, DigitalOcean)
3. IP Geolocation Integration - Country-based filtering
4. Performance Profiling - Identify remaining bottlenecks
5. Memory Optimization - Reduce footprint for large scans

Key Deliverables

NUMA Optimization:

• Detect NUMA topology (hwloc library)
• Allocate packet buffers on local NUMA nodes
• Pin worker threads to NUMA nodes
• IRQ affinity configuration guide

CDN Provider Expansion:

• Netlify CDN ranges
• Vercel Edge Network
• GitHub Pages (Fastly backend)
• DigitalOcean Spaces CDN
• Target: 10+ CDN providers total

Geolocation Filtering:

• MaxMind GeoIP2 integration
• Country-code based filtering
• ASN-based filtering
• Privacy-preserving (local database)

Task Breakdown

1. Task 1: NUMA Optimization (5-6h)
2. Task 2: CDN Expansion (3-4h)
3. Task 3: Geolocation (3-4h)
4. Task 4: Profiling & Optimization (1-2h)

Sprint 6.8: Documentation, Testing & Release Prep 📋

Status: Planned (Q2 2026) Effort Estimate: 10-12 hours Timeline: Weeks 15-16 (2 weeks) Dependencies: All Phase 6 sprints COMPLETE Priority: HIGH (Release Blocker)

Objectives

1. Comprehensive User Guide - TUI usage, advanced features, troubleshooting
2. Video Tutorials - Screen recordings of common workflows
3. API Documentation - Updated rustdoc for all public APIs
4. Final Testing - Integration tests, regression tests, performance validation
5. Release Preparation - CHANGELOG, release notes, migration guide

Key Deliverables

Documentation:

• TUI User Guide (1,500+ lines)
• Advanced Features Guide (800+ lines)
• Troubleshooting Guide (500+ lines)
• API Reference updates (cargo doc enhancements)

Testing:

• 50+ integration tests for Phase 6 features
• Regression test suite (all Phase 5 features)
• Performance validation (benchmarks)
• Cross-platform testing (Linux, macOS, Windows)

Release Preparation:

• CHANGELOG.md comprehensive Phase 6 entry
• Release notes (v0.6.0)
• Migration guide (v0.5 → v0.6)
• Binary releases (8 architectures)

Task Breakdown

1. Task 1: User Documentation (4-5h)
2. Task 2: Integration Testing (3-4h)
3. Task 3: API Documentation (1-2h)
4. Task 4: Release Preparation (2-3h)

Technical Architecture

TUI Architecture

Component Hierarchy

App (Root)
├── Terminal (ratatui + crossterm)
├── EventLoop (tokio::select!)
│   ├── Keyboard Events (crossterm)
│   ├── EventBus Events (scan updates)
│   └── Timer Events (60 FPS tick)
├── State Management
│   ├── ScanState (Arc<RwLock<>>, shared)
│   └── UIState (local, single-threaded)
└── Widget System
    ├── StatusBar (progress, ETA, throughput)
    ├── Dashboard (4-tab system)
    │   ├── PortTableWidget
    │   ├── ServiceTableWidget
    │   ├── MetricsDashboardWidget
    │   └── NetworkGraphWidget
    ├── LogWidget (event logging)
    └── HelpWidget (interactive help)

Data Flow

Scanner → EventBus → TUI Event Loop → State Update → Render (60 FPS)
   ↓         ↓           ↓                ↓              ↓
Discover   Publish    Aggregate       Update         Display
 Ports     Events     (16ms)          Widgets        Results

State Management Pattern

Shared State (Thread-Safe):

#![allow(unused)]
fn main() {
pub struct ScanState {
    pub stage: ScanStage,           // Current scan phase
    pub progress: f32,              // 0.0-100.0
    pub open_ports: Vec<PortInfo>,  // Discovered ports
    pub discovered_hosts: Vec<IpAddr>,
    pub errors: Vec<String>,
    pub warnings: Vec<String>,
}

// Thread-safe access
let scan_state = Arc::new(RwLock::new(ScanState::default()));
}

Local State (TUI Only):

#![allow(unused)]
fn main() {
pub struct UIState {
    pub selected_pane: Pane,         // Main/Log/Help
    pub dashboard_tab: DashboardTab, // Port/Service/Metrics/Network
    pub cursor_position: usize,      // Current row
    pub scroll_offset: usize,        // Scroll position
    pub show_help: bool,             // Help screen visible
    pub fps: u32,                    // Real-time FPS counter
}
}

Network Optimization Architecture

Batch I/O System

RawSocketScanner
├── BatchSender (sendmmsg wrapper)
│   ├── Packet Buffer (Vec<Vec<u8>>)
│   ├── Batch Size (1-1024)
│   └── Platform Detection (Linux/macOS/Windows)
└── BatchReceiver (recvmmsg wrapper)
    ├── Response Buffer (Vec<Vec<u8>>)
    ├── Timeout Handling
    └── Fallback Path (single recv)

Linux Implementation:

#![allow(unused)]
fn main() {
#[cfg(target_os = "linux")]
pub fn send_batch(&mut self, packets: &[Vec<u8>]) -> io::Result<usize> {
    use libc::{sendmmsg, mmsghdr, iovec};

    // Prepare mmsghdr array
    let mut msgs: Vec<mmsghdr> = packets.iter().map(|pkt| {
        mmsghdr {
            msg_hdr: msghdr {
                msg_iov: &iovec { iov_base: pkt.as_ptr(), iov_len: pkt.len() },
                msg_iovlen: 1,
                // ...
            },
            msg_len: 0,
        }
    }).collect();

    // Single syscall for entire batch
    let sent = unsafe { sendmmsg(self.fd, msgs.as_mut_ptr(), msgs.len(), 0) };
    Ok(sent as usize)
}
}

Fallback Implementation:

#![allow(unused)]
fn main() {
#[cfg(not(target_os = "linux"))]
pub fn send_batch(&mut self, packets: &[Vec<u8>]) -> io::Result<usize> {
    let mut sent = 0;
    for packet in packets {
        self.socket.send(packet)?;
        sent += 1;
    }
    Ok(sent)
}
}

CDN Deduplication System

TargetGenerator
├── CDN Detector
│   ├── IP Range Database (CIDR lists)
│   ├── ASN Lookup (6 providers)
│   └── Alias Detection (CNAME records)
├── Filtering Logic
│   ├── Whitelist Mode (skip only specified)
│   ├── Blacklist Mode (skip all except specified)
│   └── Default Mode (skip all CDNs)
└── Statistics Tracking
    ├── Total Targets
    ├── Filtered Targets
    └── Reduction Percentage

CDN Detection Pattern:

#![allow(unused)]
fn main() {
pub struct CdnDetector {
    providers: Vec<CdnProvider>,
    mode: FilterMode,
}

impl CdnDetector {
    pub fn is_cdn(&self, ip: IpAddr) -> Option<CdnProvider> {
        for provider in &self.providers {
            if provider.contains(ip) {
                return Some(provider.clone());
            }
        }
        None
    }

    pub fn should_skip(&self, ip: IpAddr) -> bool {
        match self.mode {
            FilterMode::Whitelist(ref providers) => {
                self.is_cdn(ip).map_or(false, |p| providers.contains(&p))
            }
            FilterMode::Blacklist(ref providers) => {
                self.is_cdn(ip).map_or(false, |p| !providers.contains(&p))
            }
            FilterMode::All => self.is_cdn(ip).is_some(),
        }
    }
}
}

Performance Targets

Sprint-Specific Targets

Phase 6 Overall Targets

User Experience:

• TUI Responsiveness: <16ms frame time (60 FPS sustained)
• Event-to-Display Latency: <50ms
• Memory Usage: <50 MB for TUI (excluding scan data)
• CPU Overhead: <5% for TUI rendering

Performance:

• Throughput Improvement: 20-60% (vs Phase 5 baseline)
• Scan Efficiency: 30-70% reduction (CDN-heavy targets)
• Adaptive Tuning: 15-30% automatic optimization
• NUMA Optimization: 10-15% on multi-socket systems

Quality:

• Test Coverage: >60% (vs 54.92% Phase 5)
• Tests: 2,400+ (vs 2,111 current)
• Zero Regressions: All Phase 5 features maintained
• Zero Clippy Warnings: Clean codebase maintained

Integration Strategy

EventBus Integration

Phase 5.5.3 Foundation:

• 18 event variants across 4 categories
• 40ns publish latency

• 10M events/second throughput

• Broadcast, unicast, filtered subscription

Phase 6 Extensions:

#![allow(unused)]
fn main() {
// New event types for TUI
pub enum ScanEvent {
    // ... existing Phase 5 events ...

    // Phase 6 additions
    DashboardTabChanged(DashboardTab),
    TargetSelected(Vec<IpAddr>),
    TemplateLoaded(ScanTemplate),
    ScanPaused { reason: PauseReason },
    ScanResumed { checkpoint: ScanCheckpoint },
    ExportStarted { format: ExportFormat },
    ExportComplete { path: PathBuf, count: usize },
}
}

Configuration System Integration

Phase 5 Configuration:

#![allow(unused)]
fn main() {
pub struct ScanConfig {
    pub targets: Vec<IpAddr>,
    pub ports: PortSpec,
    pub scan_type: ScanType,
    pub timing: TimingProfile,
    pub performance: PerformanceConfig,
}
}

Phase 6 Extensions:

#![allow(unused)]
fn main() {
pub struct PerformanceConfig {
    // ... existing Phase 5 fields ...

    // Phase 6 additions
    pub batch_size: usize,                    // Batch I/O (1-1024)
    pub adaptive_batch_enabled: bool,         // Adaptive tuning
    pub min_batch_size: usize,                // Adaptive minimum
    pub max_batch_size: usize,                // Adaptive maximum
    pub cdn_filter_mode: CdnFilterMode,       // CDN deduplication
    pub cdn_providers: Vec<CdnProvider>,      // Provider list
    pub numa_enabled: bool,                   // NUMA optimization
}
}

Scanner Integration

Integration Points:

1. SynScanner (TCP SYN scan):

   • Replace send() → send_batch()
   • Replace recv() → recv_batch()
   • Adaptive batch size tuning

2. ConnectScanner (TCP Connect scan):

   • Batch connection establishment
   • Parallel socket creation

3. UdpScanner (UDP scan):

   • Batch UDP send operations
   • Response aggregation

4. TargetGenerator:

   • CDN deduplication before scanning
   • Geolocation filtering
   • Target selection from TUI

Quality Standards

Testing Requirements

Per Sprint:

• Unit Tests: ≥20 per sprint
• Integration Tests: ≥10 per sprint
• Test Coverage: Maintain >54% overall
• Zero Regressions: All existing tests must pass

Phase 6 Cumulative:

• Total Tests: ≥2,400 (current: 2,111, target: +289)
• Coverage Increase: 54.92% → >60%
• Performance Tests: Comprehensive benchmark suite
• Cross-Platform: Linux, macOS, Windows validation

Code Quality Standards

Clippy Warnings: 0 (zero tolerance)

• Run cargo clippy --workspace -- -D warnings before all commits
• Address all warnings, no exceptions

Formatting: cargo fmt clean

• Run cargo fmt --all before all commits
• Consistent code style across all files

Documentation:

• Public API: 100% rustdoc coverage
• Guides: Comprehensive for all major features
• Examples: Working code examples for complex features
• CHANGELOG: Detailed entries for all changes

Performance Regression Prevention

Benchmark Suite:

• Automated benchmarks on all PRs
• Regression thresholds:
  • PASS: <5% variance
  • WARN: 5-10% variance
  • FAIL: >10% variance
• Mandatory investigation for regressions >5%

Profiling:

• CPU profiling for performance-critical code
• Memory profiling for large scan tests
• I/O profiling for network operations

Risk Assessment

Technical Risks

Schedule Risks

Mitigation Strategies

TUI Performance:

• Event aggregation (16ms batching prevents UI overload)
• Profiling at every sprint boundary
• Performance budgets: <16ms frame time, <5% CPU overhead

Cross-Platform:

• Conditional compilation (#[cfg(target_os)])
• Fallback implementations for unsupported platforms
• CI testing on Linux, macOS, Windows

Complexity Management:

• Incremental implementation (one sprint at a time)
• Comprehensive testing at each stage
• Code reviews for complex changes

Timeline & Milestones

Phase 6 Timeline (Q1-Q2 2026)

Q1 2026 (Jan-Mar)
├── Sprint 6.1: TUI Framework (2 weeks) ✅ COMPLETE (2025-11-14)
├── Sprint 6.2: Live Dashboard (2 weeks) ✅ COMPLETE (2025-11-14)
├── Sprint 6.3: Network Optimization (2 weeks) 🔄 PARTIAL (2025-11-15)
└── Sprint 6.4: Adaptive Tuning (2 weeks) 📋 Planned

Q2 2026 (Apr-Jun)
├── Sprint 6.5: Interactive Selection (2 weeks) 📋 Planned
├── Sprint 6.6: Advanced Features (2 weeks) 📋 Planned
├── Sprint 6.7: NUMA & CDN (2 weeks) 📋 Planned
└── Sprint 6.8: Documentation & Release (2 weeks) 📋 Planned

Key Milestones

Accelerated Timeline (Actual Progress)

Original Estimate: Q2 2026 (April-June) Actual Start: 2025-11-14 (4 months early) Completion Rate: 31.25% in 2 days (Sprint 6.1, 6.2 complete) Projected Completion: Q1 2026 (if pace maintains)

Resource Requirements

Development Resources

Time Investment:

• Total Estimate: 130 hours (8 sprints × 10-20h avg)
• Completed: 73.5 hours (Sprint 6.1: 40h, Sprint 6.2: 21.5h, Sprint 6.3: 12h)
• Remaining: ~56.5 hours (6.5 sprints)

Personnel:

• Primary Developer: Full-time
• Code Reviews: As needed
• Testing Support: Continuous

Technical Resources

Infrastructure:

• Development Environment: Linux (primary), macOS/Windows (testing)
• CI/CD: GitHub Actions (already configured)
• Testing Hardware: Multi-core systems for NUMA testing

Dependencies:

• ratatui 0.29: TUI framework
• crossterm 0.28: Terminal manipulation
• hwloc: NUMA topology detection (Sprint 6.7)
• MaxMind GeoIP2: Geolocation (Sprint 6.7)

External Services:

• None (all features local/offline)

Success Criteria

Phase 6 Completion Criteria

Functional Requirements:

• ✅ TUI framework with 60 FPS rendering (Sprint 6.1)
• ✅ Live dashboard with 4 interactive widgets (Sprint 6.2)
• 🔄 Batch I/O with 20-60% throughput improvement (Sprint 6.3)
• 🔄 CDN deduplication with 30-70% scan reduction (Sprint 6.3)
• 📋 Adaptive tuning with 15-30% optimization (Sprint 6.4)
• 📋 Interactive target selection (Sprint 6.5)
• 📋 Scan templates and export functionality (Sprint 6.6)
• 📋 NUMA optimization (Sprint 6.7)

Quality Requirements:

• ✅ 2,175+ tests passing (100%)
• ✅ 0 clippy warnings
• ✅ >54% code coverage (current: 54.92%)
• 📋 >60% code coverage (Phase 6 target)
• ✅ Cross-platform validation (Linux confirmed)
• 📋 Cross-platform validation (macOS, Windows)

Performance Requirements:

• ✅ TUI: 60 FPS sustained, <16ms frame time
• ✅ Event throughput: 10K+ events/second
• 🔄 Batch I/O: 20-40% throughput (batch=32), 40-60% (batch=1024)
• 🔄 CDN filtering: ≥30% reduction, <10% overhead
• 📋 Adaptive tuning: 15-30% automatic optimization
• 📋 NUMA: 10-15% multi-socket improvement

Documentation Requirements:

• ✅ TUI-ARCHITECTURE.md (891 lines)
• 🔄 27-NETWORK-OPTIMIZATION-GUIDE.md (in progress)
• 📋 28-ADAPTIVE-TUNING-GUIDE.md (planned)
• 📋 Comprehensive user guides for all features
• 📋 CHANGELOG entries for all sprints

Release Criteria (v0.6.0)

Must Have:

• All 8 sprints completed (100%)
• 2,400+ tests passing (≥2,111 + 289)

• 60% code coverage

• Zero regressions from Phase 5
• Comprehensive documentation
• CHANGELOG with detailed Phase 6 entry

Nice to Have:

• Video tutorials
• Performance comparison charts
• Community feedback integration

Related Documentation

Phase 6 Documentation

• TUI Architecture Guide
• Event System Guide
• Benchmarking Guide
• Performance Characteristics

Sprint Documentation

Completed:

• Sprint 6.1 Completion: daily_logs/2025-11-14/06-sessions/SPRINT-6.1-COMPLETE.md
• Sprint 6.2 TODO: to-dos/PHASE-6/SPRINT-6.2-LIVE-DASHBOARD-TODO.md
• Sprint 6.3 Completion: /tmp/ProRT-IP/SPRINT-6.3-COMPLETE.md

Planned:

• Sprint 6.3 TODO: to-dos/PHASE-6/SPRINT-6.3-NETWORK-OPTIMIZATION-TODO.md
• Sprint 6.4 TODO: to-dos/PHASE-6/SPRINT-6.4-ADAPTIVE-TUNING-TODO.md
• Sprint 6.5 TODO: to-dos/PHASE-6/SPRINT-6.5-INTERACTIVE-SELECTION-TODO.md
• Sprint 6.6 TODO: to-dos/PHASE-6/SPRINT-6.6-ADVANCED-FEATURES-TODO.md
• Sprint 6.7 TODO: to-dos/PHASE-6/SPRINT-6.7-NUMA-CDN-TODO.md
• Sprint 6.8 TODO: to-dos/PHASE-6/SPRINT-6.8-DOCUMENTATION-TODO.md

Core Documentation

• Project Roadmap
• Current Status
• Architecture Overview
• Testing Strategy

Document Version: 2.0 (2025-11-16) Maintained By: ProRT-IP Development Team Review Schedule: After each sprint completion