forked from genewildish/Mainline
David Gwilliam
ef98add0c5
Major changes: - Pipeline architecture with capability-based dependency resolution - Effects plugin system with performance monitoring - Display abstraction with multiple backends (terminal, null, websocket) - Camera system for viewport scrolling - Sensor framework for real-time input - Command-and-control system via ntfy - WebSocket display backend for browser clients - Comprehensive test suite and documentation Issue #48: ADR for preset scripting language included This commit consolidates 110 individual commits into a single feature integration that can be reviewed and tested before further refinement.
98 lines
3.1 KiB
Markdown
98 lines
3.1 KiB
Markdown
---
|
|
name: mainline-architecture
|
|
description: Pipeline stages, capability resolution, and core architecture patterns
|
|
compatibility: opencode
|
|
metadata:
|
|
audience: developers
|
|
source_type: codebase
|
|
---
|
|
|
|
## What This Skill Covers
|
|
|
|
This skill covers Mainline's pipeline architecture - the Stage-based system for dependency resolution, data flow, and component composition.
|
|
|
|
## Key Concepts
|
|
|
|
### Stage Class (engine/pipeline/core.py)
|
|
|
|
The `Stage` ABC is the foundation. All pipeline components inherit from it:
|
|
|
|
```python
|
|
class Stage(ABC):
|
|
name: str
|
|
category: str # "source", "effect", "overlay", "display", "camera"
|
|
optional: bool = False
|
|
|
|
@property
|
|
def capabilities(self) -> set[str]:
|
|
"""What this stage provides (e.g., 'source.headlines')"""
|
|
return set()
|
|
|
|
@property
|
|
def dependencies(self) -> set[str]:
|
|
"""What this stage needs (e.g., {'source'})"""
|
|
return set()
|
|
```
|
|
|
|
### Capability-Based Dependencies
|
|
|
|
The Pipeline resolves dependencies using **prefix matching**:
|
|
- `"source"` matches `"source.headlines"`, `"source.poetry"`, etc.
|
|
- `"camera.state"` matches the camera state capability
|
|
- This allows flexible composition without hardcoding specific stage names
|
|
|
|
### Minimum Capabilities
|
|
|
|
The pipeline requires these minimum capabilities to function:
|
|
- `"source"` - Data source capability
|
|
- `"render.output"` - Rendered content capability
|
|
- `"display.output"` - Display output capability
|
|
- `"camera.state"` - Camera state for viewport filtering
|
|
|
|
These are automatically injected if missing (auto-injection).
|
|
|
|
### DataType Enum
|
|
|
|
PureData-style data types for inlet/outlet validation:
|
|
- `SOURCE_ITEMS`: List[SourceItem] - raw items from sources
|
|
- `ITEM_TUPLES`: List[tuple] - (title, source, timestamp) tuples
|
|
- `TEXT_BUFFER`: List[str] - rendered ANSI buffer
|
|
- `RAW_TEXT`: str - raw text strings
|
|
- `PIL_IMAGE`: PIL Image object
|
|
|
|
### Pipeline Execution
|
|
|
|
The Pipeline (engine/pipeline/controller.py):
|
|
1. Collects all stages from StageRegistry
|
|
2. Resolves dependencies using prefix matching
|
|
3. Executes stages in dependency order
|
|
4. Handles errors for non-optional stages
|
|
|
|
### Canvas & Camera
|
|
|
|
- **Canvas** (`engine/canvas.py`): 2D rendering surface with dirty region tracking
|
|
- **Camera** (`engine/camera.py`): Viewport controller for scrolling content
|
|
|
|
Canvas tracks dirty regions automatically when content is written via `put_region`, `put_text`, `fill`, enabling partial buffer updates.
|
|
|
|
## Adding New Stages
|
|
|
|
1. Create a class inheriting from `Stage`
|
|
2. Define `capabilities` and `dependencies` properties
|
|
3. Implement required abstract methods
|
|
4. Register in StageRegistry or use as adapter
|
|
|
|
## Common Patterns
|
|
|
|
- Use adapters (engine/pipeline/adapters.py) to wrap existing components as stages
|
|
- Set `optional=True` for stages that can fail gracefully
|
|
- Use `stage_type` and `render_order` for execution ordering
|
|
- Clock stages update state independently of data flow
|
|
|
|
## Sources
|
|
|
|
- engine/pipeline/core.py - Stage base class
|
|
- engine/pipeline/controller.py - Pipeline implementation
|
|
- engine/pipeline/adapters/ - Stage adapters
|
|
- docs/PIPELINE.md - Pipeline documentation
|