Getting Started & Onboarding
Relevant source files
The following files were used as context for generating this wiki page:
The flext-dbt-oracle-wms project provides a specialized integration layer for transforming Oracle Warehouse Management System (WMS) data using dbt (data build tool). It is built on the FLEXT ecosystem, leveraging flext-core, flext-meltano, and flext-oracle-wms to facilitate robust data pipelines from extraction through to business-ready analytical models.
Sources: README.md:1-10, pyproject.toml:21-30
Environment Setup & Requirements
The project is designed for Python 3.13+ and utilizes hatchling as its build backend. Dependencies are managed via pyproject.toml, including core integration libraries like flext-meltano for workflow execution and flext-oracle-wms for direct WMS API communication.
Sources: pyproject.toml:13-30
Core Dependencies
| Dependency | Purpose |
|---|---|
flext-core | Base framework utilities and lazy loading |
flext-meltano | Orchestration of dbt transformations and Meltano runners |
flext-oracle-wms | Domain-specific logic for Oracle WMS interaction |
click | CLI interface implementation |
Sources: pyproject.toml:21-30
Quality Gates
Onboarding developers must adhere to the "Make Contract" for validating changes. Canonical commands include:
make check: Linting and static analysis (Ruff, Pyright, Mypy).make test: Execution of unit and integration tests.make docs: Generation of API reference and project documentation.
Sources: README.md:40-45, AGENTS.md:120-130
Architecture & Data Flow
The system follows a multi-layered architecture that separates raw data extraction from logical business transformations. The orchestration logic is centralized in the FlextDbtOracleWmsClient, which coordinates the flow between the Oracle WMS API and the dbt transformation engine.
Operational Pipeline Flow
The following diagram illustrates the lifecycle of a data transformation request, from initial discovery to dbt execution.
Logic Components
- WMS Client: Handles authentication and health checks via the
test_oracle_wms_connectionmethod. - Workflow Runner: Orchestrates the sequential execution of discovery, extraction, and transformation.
- dbt Transformer: Executes dbt models using the
FlextMeltanoLibraryRunnerto process data into staging, mart, and metric layers.
Sources: src/flext_dbt_oracle_wms/_utilities/client.py:102-125, src/flext_dbt_oracle_wms/_utilities/client.py:127-152
Configuration & dbt Project Structure
The project implements a 5-layer dbt architecture designed to eliminate configuration duplication and ensure consistent data quality across environments.
Project Layout
| Component | Path | Materialization |
|---|---|---|
| Staging | models/staging/ | View |
| Marts | models/marts/ | Table |
| Metrics | models/metrics/ | View |
| Snapshots | snapshots/ | Timestamp-based |
| Seeds | seeds/ | Table |
Sources: dbt_project.yml:25-65, dbt_project_migrated.yml:25-50
Environment Profiles
The profiles.yml defines different backend targets for development and production:
- dev: Uses
duckdbfor fast local iterations. - staging/prod: Uses
postgresfor persistent, shared environments. - ci: Uses in-memory
duckdbfor automated testing.
Sources: profiles.yml:8-55
Command Line Interface (CLI)
The CLI serves as the primary entry point for manual operations. It is accessed via the flext-dbt-oracle-wms command.
Common CLI Commands
discover: Lists all available entities from the Oracle WMS instance.extract [entity]: Fetches raw data for a specific entity (defaults toinventoryif none provided).pipeline: Runs the full end-to-end workflow (Extract -> Validate -> Transform).
# Example CLI Entry Point Configuration
[project.scripts]
flext-dbt-oracle-wms = "flext_dbt_oracle_wms.cli:main"
Sources: pyproject.toml:135-136, src/flext_dbt_oracle_wms/_simple_api_workflow.py:27-35
Summary & Developer Guidance
New contributors should prioritize understanding the FlextDbtOracleWmsClient for backend logic and the dbt_project.yml for transformation logic. All changes must be verified through the canonical quality gates and must not violate the "Universal Agent Engineering Core" regarding single source of truth (SSOT) for configuration.
Sources: README.md:15-30, AGENTS.md:15-40