1

ADR 003 DataSource Abstraction

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

Table of Contents

• ADR-003: DataSource Abstraction
• Context
• Decision
• Consequences
• References

ADR-003: DataSource Abstraction

Date: March 2026 Status: Accepted

Context

Headlines, poetry, and pipeline data all had different interfaces. Pipeline stages needed consistent access.

Decision

Abstract DataSource class with get_items():

class DataSource(ABC):
    @abstractmethod
    def get_items(self) -> list[SourceItem]:
        ...

class SourceRegistry:
    def get(self, name: str) -> DataSource: ...
    def list_available(self) -> list[str]: ...

Implementations:

• HeadlinesDataSource: Static RSS feed, cached
• PoetryDataSource: Static poetry feed, cached
• ListDataSource: Wraps pre-fetched items (testing)
• PipelineDataSource: Dynamic, re-fetches each cycle

Consequences

• Positive: Consistent interface across all source types
• Positive: SourceRegistry enables discovery
• Negative: Runtime overhead for dynamic sources

References

• engine/data_sources/sources.py: DataSource, SourceRegistry
• tests/test_data_sources.py: Comprehensive tests