What is FLEXT?
Relevant source files
The following files were used as context for generating this wiki page:
FLEXT is an enterprise-grade, multi-package Python workspace and platform designed for data integration, platform tooling, and operational connectors. It provides a foundation of typed, validated, and reusable primitives to ensure that all integrations are built without ad-hoc code, following strict architectural standards governed by a central core.
The platform is built on Python 3.13+ and leverages a "railway pattern" for functional error handling, ensuring type safety and resilience across complex data pipelines. It encompasses a wide range of capabilities, from authentication and observability to domain-specific connectors for Oracle and LDAP systems.
Sources: README.md:1-5, AGENTS.md:194-199, pyproject.toml:22-30
Core Architecture and Workspace Structure
FLEXT is organized as a monorepo workspace containing multiple specialized packages. All packages within the ecosystem inherit from flext-core, which acts as the single source of truth (SSOT) for the platform's architecture.
Workspace Components
The workspace is categorized into four primary tiers:
| Tier | Packages |
|---|---|
| Platform Core | flext-core, flext-infra, flext-tests, flext-quality |
| Capabilities | flext-cli, flext-api, flext-auth, flext-web, flext-grpc, flext-observability, flext-plugin, flext-meltano |
| Domain | flext-ldap, flext-ldif, flext-db-oracle, flext-oracle-wms, flext-oracle-oic |
| Integration | flext-tap-*, flext-target-*, flext-dbt-* |
Sources: README.md:14-19, AGENTS.md:194-199
Logical Architecture Flow
The following diagram illustrates how core primitives flow into specialized domain and integration packages.
The flow ensures that every integration uses validated primitives and canonical facades (c/m/t/p/u) defined in the core.
Sources: README.md:14-19, AGENTS.md:237-241, src/flext/init.py:12-16
Technical Standards and Patterns
The Railway Pattern
FLEXT utilizes the Railway Pattern for error handling. Instead of traditional exception-based control flow, operations return a result type r[T]. This creates a type-safe pipeline where execution continues on the "success track" or diverts to a "failure track" upon the first error.
Facade Naming Conventions
To maintain consistency across the large workspace, FLEXT uses standardized aliases for platform components:
c: Constantsm: Models (Pydantic)t: Typingsp: Protocolsu: Utilitiesr: Result containers (Railway pattern)
Sources: AGENTS.md:237-241, src/flext/init.py:11-30
Data Processing and Parallelism
FLEXT provides advanced processing capabilities designed for enterprise data loads. This includes declarative pipelines with automatic parallel execution using ThreadPoolExecutor.
Pipeline Execution Flow
A typical advanced processing pipeline in FLEXT follows a structured sequence of validation, parallel processing, and analysis.
Implementation Example: Parallel Processing
The FlextLdifProcessingPipeline class demonstrates how parallel tasks are managed within the result framework.
# From examples/advanced_processing_example.py:173-196
def _process_parallel(self, data: t.JsonMapping) -> p.Result[PipelineStageData]:
items_to_process = _json_mapping_sequence(data.get("items", []))
processed_items: MutableSequence[ItemDict] = []
with ThreadPoolExecutor(max_workers=4) as executor:
future_to_item = {
executor.submit(process_single_item, item): item
for item in items_to_process
}
for future in as_completed(future_to_item):
result = future.result()
if result is not None:
processed_items.append(result)
return r[PipelineStageData].ok(PipelineStageData(data=payload))
Sources: examples/advanced_processing_example.py:173-196
Docker and Infrastructure Management
FLEXT enforces a centralized Docker infrastructure to ensure environment parity and test reliability. All Docker artifacts are consolidated within the docker/ directory, and project-local Dockerfiles are prohibited.
Centralized Container Types
The platform manages three primary container types for testing and development:
| Container Name | Port | Purpose | Fixture |
|---|---|---|---|
flext-oracle-db-test | 1522 | Standard Oracle Database testing | oracle_container |
flext-flext-oud-test | 3389 | OUD migration and LDAP simulation | flext_oud_container |
flext-openldap-test | 3390 | Generic LDAP/LDIF testing | ldap_container |
Sources: docker/README.md:104-125
Lifecycle Management with tk
The tk API (Toolkit) manages the lifecycle of containers, including "dirty state" management. If a test fails, the container is marked as dirty and automatically recreated from scratch in the next run to prevent state pollution.
Sources: docker/README.md:173-195
Engineering Law and Governance
FLEXT operates under a strict "Canonical Engineering Law" codified in AGENTS.md. This governance governs every agent action in every session.
- P0 - Tests Validate Changes: Tests must never hardcode or freeze configuration values; they must read from the same SSOT as production.
- Continuous Green: The tree must be importable and collectable at every instant. No PR is merged unless all gates (Ruff, Pyrefly, Pyright, Mypy, Pytest) are green.
- No Blame/Fix Forward: Destructive discards of work are prohibited; agents must re-read the tree and integrate concurrent changes.
- Root Cause Only: Bypasses, shims, or "old-and-new" coexistence are forbidden. Fixes must be applied at the canonical owner.
Sources: AGENTS.md:7-45, AGENTS.md:150-165
Conclusion
FLEXT represents a highly disciplined approach to enterprise Python development. By centralizing infrastructure, enforcing strict typing via Pydantic, and utilizing functional patterns like the Railway Pattern, it provides a robust framework for scalable data integration. The platform's success is measured by its ability to reduce ad-hoc code through reusable, validated primitives while maintaining a "continuous green" state across a complex multi-package workspace.