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**
```python
# 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**
```python
# 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**
```css
/* 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.