Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/flext_oracle_oic/init.py
• src/flext_oracle_oic/ext_client.py
• src/flext_oracle_oic/main.py
• src/flext_oracle_oic/models.py
• src/flext_oracle_oic/settings.py
• src/flext_oracle_oic/constants.py
• src/flext_oracle_oic/services/integration_crud.py

The flext-oracle-oic project is an advanced extension library designed to provide structured, enterprise-grade interactions with Oracle Integration Cloud (OIC). It follows the FLEXT Unified Module Pattern, consolidating OIC-specific logic into a cohesive suite of services, clients, and models that emphasize railway-oriented error handling and strict Pydantic validation.

The architecture is built upon a layered approach, separating the public CLI and API surfaces from the underlying communication client and domain logic. It leverages the flext-core and flext-api frameworks to provide robust connectivity, authentication via OAuth2, and comprehensive monitoring of OIC resources such as integrations, connections, and packages.

Sources: README.md:1-15, src/flext_oracle_oic/ext_client.py:1-25, src/flext_oracle_oic/main.py:1-20

System Component Hierarchy

The project is structured into several key layers that manage different aspects of the Oracle OIC interaction lifecycle.

• CLI / Public Surface: Managed by FlextOracleOicCli, providing commands for connection testing and resource listing.
• Service Facade: The FlextOracleOicService (and its mixins like FlextOracleOicIntegrationCrudMixin) acts as the high-level orchestrator for business logic.
• Unified Client: FlextOracleOicClient handles low-level HTTP communication, authentication token management, and pagination.
• Models & Constants: FlextOracleOicModels and FlextOracleOicConstants provide the schema and fixed values used across all layers.

Component Relationship Diagram

The following diagram illustrates how the different architectural components interact to fulfill a request.

Core Client & Authentication

The FlextOracleOicClient is the central engine for API communication. It implements a unified pattern for managing authenticated sessions with OIC.

Authentication Flow

The client utilizes an OAuth2 Client Credentials flow. It encodes credentials using Base64, requests an access token from the IDCS token endpoint, and caches that token for subsequent requests via a FlextApi instance.

Key Client Methods

Method	Description	Source
get_access_token()	Executes OAuth2 client credentials flow.	ext_client.py:118
make_request()	Orchestrates authenticated HTTP calls with error handling.	ext_client.py:180
paginate_request()	Handles OIC-specific pagination (offset/limit).	ext_client.py:214

Sources: src/flext_oracle_oic/ext_client.py:118-140, src/flext_oracle_oic/ext_client.py:214-250

Data Modeling and Validation

The project uses a unified model pattern (FlextOracleOicModels) to ensure all data entering or leaving the system is valid. Models are categorized into configuration value objects and entity representations.

Domain Models

• OICAuthConfig: Validates OAuth2 parameters (client ID, secret, token URL).
• OICConnectionConfig: Manages connectivity settings like base_url, api_version, and request_timeout.
• OICIntegrationInfo: Represents the state of an OIC integration, including status, version, and integration_id.

Sources: src/flext_oracle_oic/models.py:25-100

Validation Constants

The FlextOracleOicConstants class provides regex authority and threshold values for validation.

# Example Validation Regex from constants.py
INTEGRATION_NAME_RE = re.compile(r"^[a-zA-Z0-9_\-\s]+$")
VERSION_PATTERN = re.compile(r"^\d{2}\.\d{2}\.\d{4}$")

Sources: src/flext_oracle_oic/constants.py:157-175

Service Layer & Mixins

The service layer provides the high-level API used by developers. It is composed of a base service and several mixins that provide specialized functionality.

Integration CRUD Operations

The FlextOracleOicIntegrationCrudMixin provides methods to manage the lifecycle of integrations.

Operation	Logic
Create	Validates input data, calls client.create_integration, and returns OICIntegrationInfo.
Fetch	Retrieves all integrations and filters by ID to return a single entity.
Update	Sends a PUT request to the specific integration endpoint with new configuration.
Delete	Sends a DELETE request to remove the integration resource.

Sources: src/flext_oracle_oic/services/integration_crud.py:25-120

Configuration Management

Configuration is handled by FlextOracleOicSettings, which inherits from FlextSettingsBase. It supports environment variable overrides using the FLEXT_ORACLE_OIC_ prefix.

Key Settings

Setting	Default Value	Description
base_url	https://localhost...	The OIC instance URL.
api_version	v1	Target OIC API version.
request_timeout	From c.DEFAULT_TIMEOUT_SECONDS	HTTP request timeout.
verify_ssl	True	Whether to verify SSL certificates.

Sources: src/flext_oracle_oic/settings.py:25-50

Conclusion

The architecture of flext-oracle-oic centers on a highly structured, type-safe approach to Oracle Cloud integrations. By utilizing the FLEXT Unified Module Pattern, it provides a clear separation between network communication (ext_client), business logic (services), and data integrity (models), ensuring that enterprise integration tasks are performed reliably and consistently.