path: root/web-timeplot/ARCHITECTURE.md

# TimePlot Architecture

## Overview

This document describes the clean, modular architecture for TimePlot's data visualization system.

## Design Principles

**Separation of Concerns**: Data generation, data provision, and visualization are completely separate.

- **Plots don't generate data** - They only display it
- **Data sources don't know about visualization** - They only produce data
- **Connections manage the flow** - They link sources to plots

This architecture allows you to:
- Easily swap data sources without changing visualization
- Reuse plots with different data
- Test components independently
- Support multiple data types (real-time, synthetic, replay, etc.)

## Architecture Layers

```
┌─────────────────────────────────────────────────┐
│         Application Layer (main.js)              │
│  - Manages app lifecycle                        │
│  - Creates plots and sources                    │
│  - Sets up connections                          │
└─────────────────────────────────────────────────┘
                      │
                      ├──────────────┬──────────────┐
                      ↓              ↓              ↓
         ┌────────────────┐  ┌─────────────┐  ┌─────────────┐
         │  Connections   │  │   Plots     │  │   Sources   │
         │  (Glue Layer)  │  │ (Display)   │  │  (Data)     │
         └────────────────┘  └─────────────┘  └─────────────┘
```

## Core Components

### 1. Data Generators (`test-data-generators.js`)

**Purpose**: Generate mathematical patterns for testing

**Classes**:
- `DataGenerator` - Base class with common functionality
- `SineWaveGenerator` - Classic sine waves
- `SquareWaveGenerator` - Digital square waves
- `PerlinNoiseGenerator` - Smooth noise
- `ChirpGenerator` - Frequency sweeps
- `CompositeGenerator` - Combine multiple generators
- Many more...

**Usage**:
```javascript
const generator = new SineWaveGenerator({
    frequency: 2.0,
    amplitude: 30,
    sampleRate: 100,
});

// Generate a line of points
const points = generator.generateLine(100, 800);
```

### 2. Data Sources (`data-sources.js`)

**Purpose**: Provide data to plots via events

**Key Concept**: Sources emit events when data is ready. They know *when* and *how* to provide data, but not *where* it goes.

**Base Class**:
```javascript
class DataSource extends EventEmitter {
    start()      // Begin providing data
    stop()       // Stop providing data
    emitLine()   // Emit a complete line of data
    emitPoint()  // Emit a single data point
}
```

**Events**:
- `'line'` - Complete line of data ready: `{points, timestamp, metadata}`
- `'point'` - Single data point ready: `{value, timestamp}`
- `'error'` - Error occurred: `{error}`

**Available Sources**:

- **SyntheticDataSource** - Uses test generators, emits lines periodically
- **FunctionDataSource** - Evaluates a function (x,t) => y
- **StreamingDataSource** - Emits individual points at a sample rate
- **WebSocketDataSource** - Receives real-time data from WebSocket
- **CSVDataSource** - Replays data from CSV files
- **CompositeDataSource** - Combines multiple sources

**Example**:
```javascript
// Create source
const source = new SyntheticDataSource({
    generator: new SineWaveGenerator({ frequency: 2.0 }),
    pointsPerLine: 100,
    width: 800,
    lineInterval: 100, // ms between lines
});

// Listen to events
source.on('line', (data) => {
    console.log('Received line:', data.points);
});

// Start generating
source.start();
```

### 3. Plots (`timeseries-plot.js`)

**Purpose**: Pure visualization - display data, nothing else

**Key Concept**: Plots receive data via method calls. They know *how* to display data, but not *where* it comes from.

**API**:
```javascript
class TimeSeriesPlot {
    // Data input
    addLine(points, metadata)    // Add a line of data
    addDataPoint(value, timestamp) // Add a single point
    clearData()                  // Clear all data

    // Display control
    setGridVisible(visible)
    setScrollSpeed(speed)
    setVerticalScale(scale)
    setTitle(title)

    // Frame update
    update()                     // Call every frame to scroll/render
}
```

**Example**:
```javascript
// Create plot
const plot = new TimeSeriesPlot({
    x: 0,
    y: 0,
    width: 800,
    height: 600,
    title: 'My Plot',
    showGrid: true,
});

// Add to PixiJS stage
app.stage.addChild(plot.container);

// Receive data
plot.addLine([
    {x: 0, y: 10},
    {x: 100, y: 20},
    {x: 200, y: 15},
]);

// Update every frame
app.ticker.add(() => plot.update());
```

### 4. Connections (`plot-connections.js`)

**Purpose**: Link data sources to plots

**Key Concept**: Connections subscribe to source events and forward data to plots. They handle timing, buffering, and data transformation.

**Connection Types**:

**DirectConnection** - Lines go straight from source to plot
```javascript
const connection = new DirectConnection(source, plot);
connection.connect();
```

**BufferedConnection** - Buffers individual points into lines
```javascript
const connection = new BufferedConnection(source, plot, {
    bufferSize: 100,      // Points per line
    bufferTimeout: 1000,  // Max time to wait (ms)
});
connection.connect();
```

**SynchronizedConnection** - Synchronizes multiple sources
```javascript
const connection = new SynchronizedConnection([source1, source2], plot, {
    syncMode: 'wait-for-all',
});
connection.connect();
```

**Helper Functions**:
```javascript
// Quick setup for synthetic data
const conn = connectSyntheticData(generator, plot, {
    lineInterval: 100,
});

// Quick setup for function-based
const conn = connectFunction((x, t) => Math.sin(x * 10 + t), plot);

// All-in-one setup
const {plot, source, connection} = createConnectedPlot(app, plotConfig, sourceConfig);
```

## Data Flow

### Scenario 1: Synthetic Data (Test Pattern)

```
DataGenerator           SyntheticDataSource      DirectConnection        TimeSeriesPlot
     │                         │                        │                      │
     │                         │ start()                │                      │
     │                         ├───────────────────────>│                      │
     │                         │                        │                      │
     │ generateLine()          │                        │                      │
     │<────────────────────────┤                        │                      │
     │                         │                        │                      │
     │ returns points[]        │                        │                      │
     ├────────────────────────>│                        │                      │
     │                         │                        │                      │
     │                         │ emit('line', data)     │                      │
     │                         ├───────────────────────>│                      │
     │                         │                        │                      │
     │                         │                        │ addLine(points)      │
     │                         │                        ├─────────────────────>│
     │                         │                        │                      │
     │                         │                        │                      │ update()
     │                         │                        │                      │ (scroll & render)
```

### Scenario 2: Real-Time Streaming

```
External System         WebSocketDataSource      BufferedConnection      TimeSeriesPlot
     │                         │                        │                      │
     │ WebSocket message       │                        │                      │
     ├────────────────────────>│                        │                      │
     │                         │                        │                      │
     │                         │ emit('point', value)   │                      │
     │                         ├───────────────────────>│                      │
     │                         │                        │                      │
     │                         │                        │ buffer.push(value)   │
     │                         │                        │                      │
     │                         │ emit('point')          │                      │
     │                         ├───────────────────────>│                      │
     │                         │                        │                      │
     │                         │ (continue...)          │                      │
     │                         │                        │                      │
     │                         │                        │ buffer full!         │
     │                         │                        │                      │
     │                         │                        │ flush()              │
     │                         │                        │ addLine(buffered)    │
     │                         │                        ├─────────────────────>│
```

## Usage Patterns

### Pattern 1: Simple Test Visualization

```javascript
import { TimeSeriesPlot } from './timeseries-plot.js';
import { connectSyntheticData } from './plot-connections.js';
import { TestDataFactory } from './test-data-generators.js';

// Create plot
const plot = new TimeSeriesPlot({...});
app.stage.addChild(plot.container);

// Connect data
const connection = connectSyntheticData(
    TestDataFactory.createSimpleSine(30),
    plot,
    { lineInterval: 100 }
);

// Update loop
app.ticker.add(() => plot.update());
```

### Pattern 2: Swap Data Sources

```javascript
// Start with one source
let connection = connectSyntheticData(generator1, plot);

// Later, switch to different data
connection.disconnect();
connection = connectSyntheticData(generator2, plot);
```

### Pattern 3: Multiple Plots, Different Data

```javascript
const plot1 = new TimeSeriesPlot({x: 0, y: 0, ...});
const plot2 = new TimeSeriesPlot({x: 800, y: 0, ...});

connectSyntheticData(sineGenerator, plot1);
connectSyntheticData(noiseGenerator, plot2);

app.ticker.add(() => {
    plot1.update();
    plot2.update();
});
```

### Pattern 4: Real-Time WebSocket Data

```javascript
const plot = new TimeSeriesPlot({...});

const source = new WebSocketDataSource({
    url: 'ws://localhost:8080/data'
});

const connection = new BufferedConnection(source, plot, {
    bufferSize: 100,
});
connection.connect();

app.ticker.add(() => plot.update());
```

### Pattern 5: Custom Function

```javascript
const plot = new TimeSeriesPlot({...});

const connection = connectFunction(
    (x, t) => Math.sin(x * 10 + t * 2) + Math.cos(x * 5 - t),
    plot,
    { lineInterval: 100, amplitude: 30 }
);

app.ticker.add(() => plot.update());
```

## File Organization

```
web-timeplot/src/
├── test-data-generators.js  # Math generators for test patterns
├── data-sources.js          # Data provision (events)
├── timeseries-plot.js       # Pure visualization
├── plot-connections.js      # Glue layer
├── example-usage.js         # Complete examples
├── main.js                  # Application entry point
├── state.js                 # App state management
└── waterfall.js            # (Legacy - can be replaced)
```

## Migration Path

### From Old WaterfallGraph to New Architecture

**Old way** (tightly coupled):
```javascript
const graph = new WaterfallGraph({...});
// Graph generates its own data
```

**New way** (separated):
```javascript
const plot = new TimeSeriesPlot({...});
const source = new SyntheticDataSource({...});
const connection = new DirectConnection(source, plot);
connection.connect();
```

## Extension Points

### Adding New Data Sources

Extend `DataSource` and implement:
- `start()` - Begin providing data
- `stop()` - Stop providing data
- Call `emitLine()` or `emitPoint()` when data is ready

Example:
```javascript
class MyCustomSource extends DataSource {
    start() {
        super.start();
        // Start your data provision mechanism
        this.interval = setInterval(() => {
            const points = [...]; // Generate points
            this.emitLine(points);
        }, 100);
    }

    stop() {
        super.stop();
        clearInterval(this.interval);
    }
}
```

### Adding New Connection Types

Extend `PlotConnection` and implement `setupSubscriptions()`:

```javascript
class MyCustomConnection extends PlotConnection {
    setupSubscriptions() {
        const unsub = this.source.on('line', (data) => {
            // Transform data as needed
            const transformed = this.transformData(data);
            this.plot.addLine(transformed.points);
        });
        this.subscriptions.push(unsub);
    }
}
```

## Benefits of This Architecture

1. **Testability** - Each component can be tested independently
2. **Reusability** - Plots work with any data source
3. **Flexibility** - Easy to add new data sources or visualizations
4. **Maintainability** - Clear responsibilities, easy to understand
5. **Performance** - Can optimize each layer independently
6. **Real-world ready** - Supports actual data sources (WebSocket, files, etc.)

## Next Steps

- Replace old `waterfall.js` usage with new `TimeSeriesPlot`
- Create real data sources for your application
- Add more visualization types (heatmap, spectrogram, etc.)
- Add data processing layer (filtering, FFT, etc.)