forked from genewildish/Mainline
David Gwilliam
b926b346ad
- Fix TerminalDisplay: add screen clear each frame (cursor home + erase down) - Fix CameraStage: use set_canvas_size instead of read-only viewport properties - Fix Glitch effect: preserve visible line lengths, remove cursor positioning - Fix Fade effect: return original line when fade=0 instead of empty string - Fix Noise effect: use input line length instead of terminal_width - Remove HUD effect from all presets (redundant with border FPS display) - Add regression tests for effect dimension stability - Add docs/ARCHITECTURE.md with Mermaid diagrams - Add mise tasks: diagram-ascii, diagram-validate, diagram-check - Move markdown docs to docs/ (ARCHITECTURE, Refactor, hardware specs) - Remove redundant requirements files (use pyproject.toml) - Add *.dot and *.png to .gitignore Closes #25
157 lines
3.5 KiB
Markdown
157 lines
3.5 KiB
Markdown
# 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)
|
|
|
|
```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
|
|
Display <|.. SixelDisplay
|
|
|
|
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)
|
|
|
|
```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)
|
|
|
|
```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
|
|
|
|
```mermaid
|
|
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
|
|
├── SixelDisplay
|
|
├── KittyDisplay
|
|
└── 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
|