Home & Introduction
Relevant source files
The following files were used as context for generating this wiki page:
The flext-oracle-wms library is an enterprise-grade client designed for seamless integration with Oracle Warehouse Management System (WMS) Cloud within the FLEXT data integration platform. It provides a type-safe, declarative interface for interacting with Oracle WMS APIs, supporting automated entity discovery, multi-method authentication, and Singer protocol compatibility for high-volume data pipelines.
The project is architected following Clean Architecture principles and Railway-Oriented Programming (ROP) patterns. It ensures robustness through comprehensive error handling (using the r result pattern), structured logging, and enterprise-level features such as connection pooling, exponential backoff retries, and intelligent caching.
Sources: README.md:1-10, src/README.md:23-28, src/flext_oracle_wms/README.md:73-82
Core Architecture and Module Organization
The codebase is organized into several distinct layers that separate domain logic, infrastructure, and public interfaces. The primary entry point is the FlextOracleWmsClient, which orchestrates discovery and data operations.
Module Map
| Component | File/Path | Description |
|---|---|---|
| Public API Gateway | src/flext_oracle_wms/__init__.py | Central export point for all major library components. |
| Primary Client | src/flext_oracle_wms/client.py | Main interface for WMS operations and state management. |
| API Catalog | src/flext_oracle_wms/api_catalog.py | Declarative definitions of WMS Cloud REST endpoints. |
| Entity Discovery | src/flext_oracle_wms/discovery.py | Logic for automatic schema introspection and entity detection. |
| Authentication | src/flext_oracle_wms/authentication.py | Multi-method support (Basic, Bearer, API Key). |
| Configuration | src/flext_oracle_wms/settings.py | Pydantic-driven settings management with validation. |
Sources: src/README.md:32-47, src/flext_oracle_wms/README.md:28-56
High-Level System Flow
The following diagram illustrates the interaction between a user application, the FLEXT Oracle WMS Client, and the Oracle WMS Cloud service during a typical data retrieval operation.
The diagram shows the sequence from initialization and authentication through to data retrieval via the declarative API catalog.
Sources: src/README.md:32-47, src/flext_oracle_wms/README.md:95-125
Key Features
The library is built to satisfy enterprise requirements for performance, reliability, and ease of integration.
Oracle WMS Cloud Integration
- Dynamic Entity Discovery: Automatically identifies available entities (e.g., Inventory, Orders, Shipping) from the Oracle WMS Cloud REST API.
- Type-Safe Operations: Strict MyPy adoption and comprehensive Pydantic validation ensure data integrity.
- Declarative API Catalog: Centralized management of endpoints, supporting versioning (e.g., LGF API v10).
FLEXT Ecosystem Synergy
- Railway-Oriented Programming: Uses the
randppatterns fromflext-corefor consistent, exception-free error management. - Singer Protocol Compatibility: Includes components like
flattening.pyto prepare nested WMS data for Singer-compliant data pipelines. - Observability: Integrated with FLEXT observability for structured logging, correlation IDs, and metrics.
Sources: src/README.md:52-70, src/flext_oracle_wms/README.md:65-90
Configuration Management
Configuration is handled via environment variables with the FLEXT_ORACLE_WMS_ prefix. Settings are validated at runtime using Pydantic.
Core Settings Parameters
| Setting | Env Variable | Default | Description |
|---|---|---|---|
base_url | FLEXT_ORACLE_WMS_BASE_URL | N/A | The Oracle WMS Cloud instance URL. |
username | FLEXT_ORACLE_WMS_USERNAME | N/A | API Authentication username. |
password | FLEXT_ORACLE_WMS_PASSWORD | N/A | API Authentication password. |
auth_method | FLEXT_ORACLE_WMS_AUTH_METHOD | basic | Support for basic, bearer, or api_key. |
timeout | FLEXT_ORACLE_WMS_TIMEOUT | 30 | Connection timeout in seconds. |
retry_attempts | FLEXT_ORACLE_WMS_RETRY_ATTEMPTS | 3 | Max retry attempts for failed requests. |
Sources: src/README.md:94-105, examples/README.md:73-81, src/flext_oracle_wms/README.md:40-42
Technical Reliability Standards
The project enforces strict quality gates to maintain its "Production Ready" status.
- Test Coverage: A minimum of 90% overall coverage is required, with unit tests for core modules aiming for 95%.
- Type Safety: MyPy strict mode is mandatory for all production code.
- Performance: Entity discovery operations are optimized to respond in under 2 seconds, supporting 100+ concurrent connections.
- Security: No hardcoded credentials; the library relies on secure environment variable injection or FLEXT container-managed secrets.
Sources: src/README.md:126-140, src/flext_oracle_wms/README.md:158-175, AGENTS.md:10-25
Conclusion
The flext-oracle-wms module serves as a robust bridge between Oracle WMS Cloud and the FLEXT ecosystem. By combining a declarative API approach with strict architectural patterns like Clean Architecture and ROP, it provides developers with a predictable and performant toolset for complex logistics and warehouse data integrations.
Sources: README.md:7-10, src/README.md:23-28