Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The flext-oracle-wms library is an enterprise-grade integration module designed to connect the FLEXT data integration platform with Oracle Warehouse Management System (WMS) Cloud. It follows Clean Architecture principles, ensuring a strict separation between core domain logic, infrastructure concerns, and external API communication. The system is built to support high-volume data processing with a focus on type safety, performance through intelligent caching, and resilience via Railway-Oriented Programming (ROP).
The architecture is primarily organized around a declarative API catalog and dynamic discovery mechanisms that allow it to adapt to different Oracle WMS environments (supporting versions such as LGF V10). It integrates deeply with the FLEXT ecosystem, utilizing standard patterns for configuration, logging, and dependency injection.
Sources: src/README.md:28-40, src/flext_oracle_wms/README.md:65-71
Core Component Structure
The repository is structured into distinct layers that handle specific responsibilities, from the public-facing API gateway to the underlying infrastructure components.
Module Organization
The project adheres to a modular structure that separates the public interface from the internal machinery:
| Layer | Files / Modules | Responsibility |
|---|---|---|
| Public API | __init__.py, client.py | Gateway for all operations; primary client interface. |
| Core Logic | models.py, types.py, constants.py | Domain models, type definitions, and WMS constants. |
| API & Discovery | api_catalog.py, discovery.py, dynamic.py | Declarative endpoint management and schema introspection. |
| Infrastructure | authentication.py, settings.py, exceptions.py | Multi-method auth, Pydantic settings, and error hierarchy. |
| Performance | cache.py, filtering.py, flattening.py | TTL-based caching, advanced querying, and data transformation. |
Sources: src/README.md:30-45, src/flext_oracle_wms/README.md:21-47
Component Relationship
The following diagram illustrates how the core components interact to process a user request through the system.
This diagram shows the flow from the initial client initialization to the eventual communication with the Oracle WMS Cloud REST API, mediated by internal discovery and caching layers.
Sources: src/README.md:30-45, src/flext_oracle_wms/README.md:53-63
Key Architectural Patterns
Railway-Oriented Programming (ROP)
A defining feature of the architecture is the use of the FlextResult (often aliased as r) pattern. Instead of raising exceptions for business logic failures, functions return a result object that explicitly tracks success or failure. This ensures a consistent error-handling flow across the entire module.
Sources: src/README.md:50-55, src/flext_oracle_wms/README.md:66-70
Declarative API Catalog
The system utilizes a declarative API catalog to manage Oracle WMS endpoints. This approach abstracts the complexities of different WMS versions (e.g., LGF API V10) and allows the client to perform operations like health checks, entity data retrieval, and record updates through a unified interface.
# API Catalog facilitates category-based access
for api_name, api_info in FlextOracleWmsApi.FLEXT_ORACLE_WMS_APIS.items():
category = api_info.category
# Logical grouping of endpoints
Sources: examples/03_complete_functionality_showcase.py:126-135, src/flext_oracle_wms/README.md:41-45
Dynamic Entity and Schema Discovery
The architecture supports automatic introspection of the Oracle WMS environment. The Discovery module can scan for over 320+ potential entities and generate Singer-compatible schemas on the fly.
The discovery flow focuses on high-priority entities (like company, facility, item, inventory) first to provide rapid system orientation.
Sources: tests/unit/oracle_wms_optimized_discovery.py:53-85, src/flext_oracle_wms/README.md:53-57
Data Flow and Transformation
The data flow within the library is designed for high-volume extraction and compatibility with modern data pipelines (Singer Protocol).
Request Pipeline
- Configuration:
FlextOracleWmsSettingsvalidates credentials and connection parameters using Pydantic. - Authentication: The
Authenticatorgenerates required headers (Basic, Bearer, or API Key). - Querying:
filtering.pyapplies advanced filters and handles pagination to respect API limits. - Transformation:
flattening.pyprocesses nested structures from Oracle into flat formats suitable for downstream consumers. - Output: Data is wrapped in a
FlextResultand returned to the caller or pushed to a Singer-compatible stream.
Sources: src/README.md:85-100, src/flext_oracle_wms/README.md:46-52
Entity Mapping logic
The following table describes how the architecture maps specific Oracle WMS data concepts to integration types.
| Oracle Concept | Implementation | Logic Source |
|---|---|---|
| ID Fields | *_id or id | Identified as primary keys in schemas. |
| Timestamps | *_ts, timestamp, *_at | Formatted as ISO-8601 date-time. |
| Codes | *_code, *_cd, *_nbr | Mapped as unique identifiers/codes. |
| Nested Objects | Flattening utility | Converted to flat key-value pairs. |
Sources: tests/unit/oracle_wms_focused_discovery.py:202-235, tests/unit/oracle_wms_optimized_discovery.py:228-265
Integration and Quality Gates
The architecture is governed by strict FLEXT ecosystem standards:
- Type Safety: MyPy strict mode is enforced, targeting 95%+ coverage across the codebase.
- Performance: Enterprise-grade connection pooling (via HTTPX) and exponential backoff retry logic.
- Testing: A three-tier strategy including unit tests, integration tests (using a mock server), and end-to-end tests with real Oracle connections.
- Observability: Integrated structured logging with correlation IDs for cross-system tracking.
Sources: src/README.md:120-135, pyproject.toml:343-380, AGENTS.md:50-70
Conclusion
The flext-oracle-wms architecture provides a robust, type-safe bridge between the FLEXT ecosystem and Oracle WMS Cloud. By leveraging declarative catalogs and dynamic discovery, it minimizes the manual configuration required for complex WMS integrations while maintaining high performance through optimized data handling and caching.