Mainline/docs/ARCHITECTURE.md

Mainline Architecture Diagrams

These diagrams use Mermaid. Render with: npx @mermaid-js/mermaid-cli -i ARCHITECTURE.md or view in GitHub/GitLab/Notion.

Class Hierarchy (Mermaid)

classDiagram
    class Stage {
        <<abstract>>
        +str name
        +set[str] capabilities
        +set[str] dependencies
        +process(data, ctx) Any
    }
    
    Stage <|-- DataSourceStage
    Stage <|-- CameraStage
    Stage <|-- FontStage
    Stage <|-- ViewportFilterStage
    Stage <|-- EffectPluginStage
    Stage <|-- DisplayStage
    Stage <|-- SourceItemsToBufferStage
    Stage <|-- PassthroughStage
    Stage <|-- ImageToTextStage
    Stage <|-- CanvasStage
    
    class EffectPlugin {
        <<abstract>>
        +str name
        +EffectConfig config
        +process(buf, ctx) list[str]
        +configure(config) None
    }
    
    EffectPlugin <|-- NoiseEffect
    EffectPlugin <|-- FadeEffect
    EffectPlugin <|-- GlitchEffect
    EffectPlugin <|-- FirehoseEffect
    EffectPlugin <|-- CropEffect
    EffectPlugin <|-- TintEffect
    
    class Display {
        <<protocol>>
        +int width
        +int height
        +init(width, height, reuse)
        +show(buffer, border)
        +clear() None
        +cleanup() None
    }
    
    Display <|.. TerminalDisplay
    Display <|.. NullDisplay
    Display <|.. PygameDisplay
    Display <|.. WebSocketDisplay
    
    class Camera {
        +int viewport_width
        +int viewport_height
        +CameraMode mode
        +apply(buffer, width, height) list[str]
    }
    
    class Pipeline {
        +dict[str, Stage] stages
        +PipelineContext context
        +execute(data) StageResult
    }
    
    Pipeline --> Stage
    Stage --> Display

Data Flow (Mermaid)

flowchart LR
    DataSource[Data Source] --> DataSourceStage
    DataSourceStage --> FontStage
    FontStage --> CameraStage
    CameraStage --> EffectStages
    EffectStages --> DisplayStage
    DisplayStage --> TerminalDisplay
    DisplayStage --> BrowserWebSocket
    DisplayStage --> SixelDisplay
    DisplayStage --> NullDisplay

Effect Chain (Mermaid)

flowchart LR
    InputBuffer --> NoiseEffect
    NoiseEffect --> FadeEffect
    FadeEffect --> GlitchEffect
    GlitchEffect --> FirehoseEffect
    FirehoseEffect --> Output

Note: Each effect must preserve buffer dimensions (line count and visible width).

Stage Capabilities

flowchart TB
    subgraph "Capability Resolution"
        D[DataSource<br/>provides: source.*]
        C[Camera<br/>provides: render.output]
        E[Effects<br/>provides: render.effect]
        DIS[Display<br/>provides: display.output]
    end

---

Legacy ASCII Diagrams

Stage Inheritance

Stage(ABC)
├── DataSourceStage
├── CameraStage  
├── FontStage
├── ViewportFilterStage
├── EffectPluginStage
├── DisplayStage
├── SourceItemsToBufferStage
├── PassthroughStage
├── ImageToTextStage
└── CanvasStage

Display Backends

Display(Protocol)
├── TerminalDisplay
├── NullDisplay
├── PygameDisplay
├── WebSocketDisplay
└── MultiDisplay

Camera Modes

Camera
├── FEED       # Static view
├── SCROLL     # Horizontal scroll
├── VERTICAL   # Vertical scroll
├── HORIZONTAL # Same as scroll
├── OMNI       # Omnidirectional
├── FLOATING   # Floating particles
└── BOUNCE     # Bouncing camera