Overall Architecture & MRO Cascade

Relevant source files

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

• src/README.md
• README.md
• AGENTS.md
• pyproject.toml
• tests/unit/test_services.py
• tests/unit/test_api.py

The flext-db-oracle library is an enterprise-grade Oracle database integration module built on Clean Architecture principles. It facilitates high-level database operations, schema introspection, and DDL generation within the FLEXT ecosystem. The architecture is designed to be extensible through a plugin system while maintaining strict type safety and SOLID principles.

Central to the project's design is the Method Resolution Order (MRO) Cascade, which defines how facade classes inherit functionality from parent library abstractions. This cascade ensures that the public API remains consistent while delegating specialized logic to infrastructure and domain layers.

Sources: src/README.md:1-24, README.md:24-28, tests/unit/test_api.py:17-30

Clean Architecture Layers

The library is organized into four distinct layers that separate concerns from low-level foundation to high-level application logic.

Core Components Summary

Layer	Primary Modules	Description
Application	api.py, cli.py	Main service providing high-level Oracle operations and terminal access.
Domain	metadata.py, types.py	Defines Oracle schema models, DDL logic, and Pydantic-based domain entities.
Infrastructure	settings.py, connection.py	Manages connection pooling, performance monitoring, and configuration validation.
Foundation	constants.py, exceptions.py	Core system constants, base library initialization, and specific error types.

Sources: src/README.md:27-44

MRO Cascade & Inheritance

The project leverages a specific Method Resolution Order (MRO) cascade to integrate with FLEXT Core patterns. Facade classes, such as FlextDbOracleServices, inherit behavior from base abstractions to provide a unified interface for connection management, SQL building, and metadata extraction.

Implementation of SOLID Principles

• Single Responsibility: Modules like connection.py focus exclusively on resource management, while metadata.py handles introspection.
• Interface Segregation: Specific interfaces are provided for metadata operations vs. query execution.
• Dependency Inversion: High-level API logic depends on abstractions (e.g., FlextContainer) rather than specific database drivers.

Sources: src/README.md:67-75

Operation & Data Flow

Database operations follow a Railway-Oriented Programming (r[T]) pattern for error handling. Every major operation returns a result container rather than raising unhandled exceptions, ensuring predictable state management.

Data Models & Constraints

The architecture enforces strict technical constraints based on Oracle-specific requirements and FLEXT standards.

Component	Constraints / Rules	Source File
Identifiers	Max length 30 (or MAX_IDENTIFIER_LENGTH), must be escaped.	tests/unit/test_utilities.py:126-150
Data Types	Mapping for Singer JSON Schema (e.g., string -> VARCHAR2(4000)).	tests/unit/test_services.py:100-120
Error Handling	Uses r[T] pattern; "not connected" failures are handled via Result.failure.	tests/unit/test_api.py:146-160
Settings	Pydantic validation for host, port (1-65535), username, and service_name.	tests/unit/test_models.py:270-300

Governance & Engineering Law

The architecture is governed by the Universal Agent Law defined in AGENTS.md. This requires that all architectural changes maintain a "Zero-Debt Baseline" and respect the Single Source of Truth (SSOT). Any modification to the MRO chain or the facade inheritance must be validated through the canonical make verbs (check, test, val).

Sources: AGENTS.md:12-45, README.md:24-34

Summary

The Overall Architecture & MRO Cascade of flext-db-oracle provides a robust, layered approach to database integration. By utilizing a clear MRO cascade for its facade classes and adhering to Clean Architecture principles, the library ensures that complex Oracle operations—from DDL generation to connection pooling—are handled with type safety and consistent error management via the FLEXT Core result patterns.

Sources: src/README.md:144-149