1

ADR 002 Stage Based Pipeline Architecture

David Gwilliam edited this page 2026-03-17 23:35:33 -07:00

Table of Contents

• ADR-002: Stage-Based Pipeline Architecture
• Context
• Decision
• Consequences
• References

ADR-002: Stage-Based Pipeline Architecture

Date: March 2026 Status: Accepted

Context

Legacy used monolithic RenderStage that coupled fetching, rendering, and display. Hard to extend or test.

Decision

Replace with composable Stage classes, each with single responsibility:

• DataSourceStage: Wraps DataSource, provides raw items
• SourceItemsToBufferStage: Converts items to display buffer
• EffectPluginStage: Applies effects chain
• DisplayStage: Renders to display backend
• ViewportFilterStage: Filters to visible region

Each Stage implements:

• capabilities: What it provides
• dependencies: What it needs
• process(buf, ctx): Transform the buffer

Consequences

• Positive: Single responsibility - easier to test and debug
• Positive: Replace any stage without affecting others
• Positive: Pipeline introspection shows clear data flow
• Negative: More classes to maintain

References

• engine/pipeline/core.py: Stage ABC
• engine/pipeline/adapters.py: Concrete stage implementations