Abstraction Boundaries
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The flext-oracle-wms library is designed with strict adherence to Clean Architecture principles and the FLEXT ecosystem standards. Its abstraction boundaries are established to ensure a clear separation between the domain logic, infrastructure components, and the public-facing API gateway. This architecture facilitates enterprise-grade integration with Oracle Warehouse Management System (WMS) Cloud while maintaining compatibility with the FLEXT data integration platform.
Sources: src/README.md:15-17, src/flext_oracle_wms/README.md:65-69, AGENTS.md:345-355
Core Architectural Layers
The project implements a multi-layered abstraction model that isolates external communication from internal domain rules. This is achieved through specific module organizations and the use of the r (Railway-Oriented Programming) pattern for consistent error and result management.
Layered Structure
- Public API Gateway: The
__init__.pyfile serves as the primary entry point, exposing a type-safe interface for the entire package. - Client Interface:
client.pyprovides theFlextOracleWmsClient, which orchestrates high-level operations like entity discovery and data querying. - Domain Models:
models.pycontains the business logic and entity definitions using FLEXT Value patterns, remaining independent of the HTTP transport layer. - Infrastructure: Modules like
authentication.py,discovery.py, andcache.pyhandle technical details such as multi-method authentication and schema introspection.
Sources: src/README.md:21-36, src/flext_oracle_wms/README.md:20-43
The diagram above illustrates the vertical flow of dependencies, where the Application Layer coordinates between Infrastructure and the Domain. Sources: src/README.md:21-36, src/flext_oracle_wms/README.md:20-43
Key Integration Boundaries
The library maintains strict boundaries between its internal logic and the external FLEXT ecosystem. These integration points are defined by a Parent MRO (Method Resolution Order) chain and standardized configuration prefixes.
| Component | Responsibility | Boundary Type |
|---|---|---|
FlextOracleWmsSettings | Environment-driven configuration with Pydantic validation. | Configuration Boundary |
r Pattern | Railway-oriented programming for result/error handling. | Logic/Control Boundary |
Singer Protocol | Flattening nested structures for data pipeline compatibility. | Interface Boundary |
DI Container | Support for dependency injection via FLEXT core patterns. | Orchestration Boundary |
Sources: README.md:24-33, src/flext_oracle_wms/README.md:52-62, src/flext_oracle_wms/models.py:101-118
Domain Abstractions
The domain layer is composed of Value Objects and Entity definitions that represent WMS concepts independently of any specific WMS provider, though customized for Oracle.
Entity Model Composition
The Entity class in models.py serves as a core abstraction for any WMS object, defining its endpoint, primary keys, and replication capabilities.
class Entity(m.BaseModel):
name: Annotated[str, u.Field(min_length=1)]
endpoint: Annotated[str, u.Field(min_length=1)]
primary_key: str | None = None
supports_incremental: bool = False
Sources: src/flext_oracle_wms/models.py:41-57
Result and Error Boundaries
Instead of raising unhandled exceptions across boundaries, the system uses the p.Result (often referred to as r) to encapsulate success and failure states. This ensures that the caller always receives a structured response, preventing leakages of infrastructure errors into the application logic.
Sources: src/README.md:46-52, src/flext_oracle_wms/README.md:52-54
External Service Boundaries
Communication with Oracle WMS Cloud is abstracted through a declarative API catalog. This catalog (api_catalog.py) defines endpoints, methods, and versions, allowing the client to interact with the LGF (Legacy) API without manual URL construction.
Governance and Quality Gates
Abstraction boundaries are reinforced by quality gates and engineering laws defined in AGENTS.md. These rules mandate that:
- Tests validate boundaries: Tests must validate behavior for arbitrary valid values rather than hardcoding configured scalars.
- SSOT (Single Source of Truth): The canonical owner of configurable facts resides in settings, not hardcoded in the implementation.
- No Hidden Code: Examples and tests are treated as first-class citizens, ensuring the abstraction remains usable and documented.
Sources: AGENTS.md:15-30, AGENTS.md:345-350, pyproject.toml:130-150
Conclusion
The abstraction boundaries within flext-oracle-wms ensure that the core domain logic remains isolated from volatile infrastructure details like authentication methods and REST API quirks. By leveraging standardized FLEXT patterns and a strict layered architecture, the library provides a reliable and maintainable bridge between the Oracle WMS Cloud and enterprise data pipelines.