StreamLens/TEXTUAL_ARCHITECTURE.md

Textual TUI Architecture Design

Migration Strategy

Current State: Curses-based TUI

• Manual character positioning and formatting
• Complex manual layout calculations
• Difficult column alignment issues
• No responsive design capabilities
• Manual event handling with key codes

Target State: Textual-based TUI

• Widget-based reactive components
• Automatic layout management with CSS-like styling
• Built-in responsive design
• Rich data table widgets with automatic formatting
• Event-driven programming with proper handlers

Architecture Overview

Core Application Structure

StreamLensApp (Textual App)
├── HeaderWidget (shows connection status, summary stats)
├── TabbedContent
│   ├── FlowAnalysisTab (DataTable + DetailPanel)
│   ├── PacketDecoderTab (3-column layout)
│   └── StatisticalAnalysisTab (charts + metrics)
└── StatusBar (shows help, shortcuts)

Key Components

1. StreamLensApp (Main Application)

• Inherits from textual.app.App
• Manages global state and analyzer integration
• Handles live data updates via reactive attributes
• Provides theme and styling configuration

2. FlowAnalysisWidget

• Uses textual.widgets.DataTable for hierarchical flow display
• Reactive data binding for real-time updates
• Built-in sorting, filtering, and selection
• Custom cell renderers for enhanced flows (colored indicators)
• Sub-row expansion for protocol/frame type breakdown

3. PacketDecoderWidget

• Uses textual.containers.Horizontal for 3-panel layout
• Left: Flow summary with textual.widgets.Tree
• Center: Packet list with DataTable
• Right: Field details with textual.widgets.Tree or custom widget

4. StatisticalAnalysisWidget

• Uses textual.widgets.TabbedContent for analysis modes
• Custom chart widgets using Rich's console rendering
• Reactive metrics display with textual.widgets.Static

Advantages Over Current Curses Implementation

1. Automatic Layout Management

# Current curses: Manual positioning
stdscr.addstr(current_y + display_row, 4, flow_line, attr)

# Textual: Declarative layout
class FlowTable(DataTable):
    def compose(self):
        self.add_columns("Flow", "Source", "Proto", "Destination", ...)

2. Responsive Design

• Automatic terminal resize handling
• Dynamic column width distribution
• No manual width calculations needed

3. Rich Data Display

• Built-in data table with sorting, filtering
• Hierarchical trees for protocol breakdown
• Syntax highlighting for packet data
• Progress bars, sparklines, charts

4. Event System

# Current: Manual key code handling
elif key == ord('1'):
    self.current_view = ViewMode.FLOW_ANALYSIS

# Textual: Declarative actions
class StreamLensApp(App):
    BINDINGS = [("1", "show_flows", "Flow Analysis")]
    
    def action_show_flows(self):
        self.query_one(TabbedContent).active = "flows"

5. Styling & Theming

/* streamlens.tcss */
FlowTable {
    height: 1fr;
}

FlowTable .enhanced-flow {
    background: $success;
    color: $text;
}

.metrics-panel {
    border: solid $primary;
    padding: 1;
}

Implementation Plan

Phase 1: Core Infrastructure

1. Create TextualTUIInterface class inheriting from textual.app.App
2. Implement basic 3-tab layout structure
3. Add global keybindings and navigation
4. Integrate with existing analyzer backend

Phase 2: Flow Analysis Tab

1. Replace manual formatting with DataTable widget
2. Implement hierarchical rows for protocol breakdown
3. Add reactive data updates for live analysis
4. Custom cell renderers for enhanced flow indicators

Phase 3: Packet Decoder Tab

1. 3-panel layout with Horizontal container
2. Flow tree widget for navigation
3. Packet list with detailed field display
4. Hex dump viewer with syntax highlighting

Phase 4: Statistical Analysis Tab

1. Metrics dashboard with reactive widgets
2. Chart widgets for timing analysis
3. Real-time outlier detection display
4. Export functionality

Phase 5: Advanced Features

1. Mouse support for interactive selection
2. Search and filtering capabilities
3. Configurable themes and layouts
4. Web browser support via textual serve

File Structure

analyzer/
├── tui/
│   ├── textual/                    # New Textual-based TUI
│   │   ├── __init__.py
│   │   ├── app.py                  # Main StreamLensApp
│   │   ├── widgets/
│   │   │   ├── flow_table.py       # Enhanced DataTable for flows
│   │   │   ├── packet_viewer.py    # 3-panel packet analysis
│   │   │   ├── metrics_dashboard.py # Statistics widgets
│   │   │   └── charts.py           # Custom chart widgets
│   │   ├── screens/
│   │   │   ├── flow_analysis.py    # Flow analysis screen
│   │   │   ├── packet_decoder.py   # Packet decoding screen  
│   │   │   └── statistics.py       # Statistical analysis screen
│   │   └── styles/
│   │       └── streamlens.tcss     # Textual CSS styling
│   ├── curses/                     # Existing curses TUI (preserved)
│   │   ├── interface.py            # Classic TUI (--classic flag)
│   │   └── ...
│   └── interface.py                # TUI selection logic

Migration Benefits

1. Reduced Code Complexity: ~60% less code for layout management
2. Better Maintainability: Declarative widgets vs manual positioning
3. Enhanced User Experience: Mouse support, responsive design, better visual feedback
4. Future-Proof: Web browser support, theme customization, extensible widgets
5. Professional Appearance: Rich styling capabilities, consistent spacing
6. Developer Experience: Better debugging tools, reactive programming model

The Textual migration will transform StreamLens from a basic terminal interface into a modern, professional TUI application while maintaining all existing functionality and adding significant new capabilities.