Protocols & SOLID Interfaces
Relevant source files
The following files were used as context for generating this wiki page:
The flext-tap-oracle-wms project utilizes protocols and structured interfaces to ensure strict adherence to SOLID principles, particularly the Dependency Inversion Principle (DIP). By defining clear boundaries through abstract interfaces, the module facilitates integration between the Singer SDK, the FLEXT ecosystem, and the Oracle Warehouse Management System (WMS) API. This architecture promotes high testability via mocking and supports the long-term goal of reducing complexity from a 26-file over-engineered state to a streamlined 6-8 file core.
The primary purpose of these interfaces is to decouple core business logic—such as entity discovery, authentication, and data extraction—from concrete HTTP client implementations. This allows for the injection of collaborators (Dependency Injection) and ensures that the tap remains compliant with the Singer protocol while being extensible within the broader FLEXT infrastructure.
Sources: src/flext_tap_oracle_wms/README.md:120-135, AGENTS.md:92-105, src/flext_tap_oracle_wms/__init__.py:38-70
Architectural Foundation
The project's engineering conduct is governed by the Universal Agent Law, which mandates the use of SSOT (Single Source of Truth) and SOLID principles. The architecture is designed to prevent "fat interfaces" and "god-objects," favoring granular protocols that define specific behaviors.
Dependency Injection & Inversion
The system relies on Dependency Injection (DI) and the Dependency Inversion Principle (DIP). Business logic does not depend on hard-wired construction; instead, it depends on abstractions (protocols) and receives its collaborators at runtime.
This diagram illustrates how core classes like the Tap and Stream depend on abstract interfaces rather than concrete implementations, enabling flexible component swapping.
Sources: AGENTS.md:92-105, src/flext_tap_oracle_wms/README.md:65-75
Key Interface Components
The project exposes several high-level interfaces through its public API surface. These are organized into functional areas including discovery, mapping, and services.
Core Protocol Exports
The module initialization facilitates access to these interfaces through structured lazy exports.
| Interface Reference | Category | Purpose |
|---|---|---|
FlextTapOracleWmsProtocols | Foundations | Defines abstract contracts for internal component interaction. |
FlextTapOracleWmsService | Domain | Orchestrates WMS-specific business processes. |
FlextTapOracleWmsModels | Data | Structured domain entities and Pydantic validation models. |
FlextTapOracleWmsSettings | Configuration | Pydantic-based configuration interface for environment and tap settings. |
Sources: src/flext_tap_oracle_wms/__init__.py:38-70, src/flext_tap_oracle_wms/README.md:38-45
Integration with FLEXT Ecosystem
The protocols within this tap are designed to align with the flext-core foundation patterns. This includes standardized logging, result handling, and observability.
Inheritance and Compliance
The tap follows a specific inheritance chain to maintain compliance with both the Singer SDK and FLEXT standards:
- Singer SDK: Inherits from
singer_sdk.Tapandsinger_sdk.streams.RESTStream. - FLEXT Core: Uses
flext_core.u.fetch_logger()and implementsrpatterns (Result types) for consistent error handling. - MRO Chain: The Method Resolution Order (MRO) is encoded in the facade classes, ensuring that FLEXT patterns cascade through the implementation.
Sources: src/flext_tap_oracle_wms/README.md:76-85, README.md:25-30, pyproject.toml:35-42
Testing and Mocking Interfaces
Strict interface definitions are critical for the project's testing strategy, as 27% of the test suite is currently dependent on mocking to bypass external WMS dependencies.
Mock Usage Pattern
Tests leverage the defined interfaces to create isolated unit tests. By mocking the FlextOracleWmsClient or authentication protocols, developers can validate logic without network side effects.
The sequence diagram shows the interaction between unit tests and component interfaces using injected mocks.
Sources: tests/README.md:120-140, tests/unit/README.md:105-125
SOLID Implementation Guidelines
Developers contributing to the repository must follow these strict typing and architectural rules:
- Strict, Most-Restrictive Typing: Use the most specific types possible.
Anyand bareobjectare prohibited. - Interface Segregation: God-objects are considered defects; interfaces must be lean and purpose-specific.
- YAGNI (You Ain't Gonna Need It): Avoid speculative parameters or single-implementation abstractions that do not currently serve a purpose.
- SSOT: Reference one authoritative source for facts rather than restating them across different interfaces.
Sources: AGENTS.md:88-105, src/flext_tap_oracle_wms/README.md:115-125
Conclusion
The use of Protocols and SOLID interfaces in flext-tap-oracle-wms provides the necessary abstraction to handle the complexity of Oracle WMS integrations. While the current architecture is identified as over-engineered, the existing interface boundaries provide the framework needed to refactor the code significantly—targeting a 90% reduction in code volume—without breaking the external contracts required by the Singer protocol and the FLEXT ecosystem.
Sources: src/flext_tap_oracle_wms/README.md:58-65, src/flext_tap_oracle_wms/README.md:130-145