Facades and Namespaces

Relevant source files

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

• src/flext/init.py
• libs/init.py
• AGENTS.md
• examples/advanced_processing_example.py
• codex.md

Facades and namespaces in the FLEXT ecosystem serve as the foundational architecture for typed, validated, and reusable enterprise data integration. This system enforces a strict Method Resolution Order (MRO) namespace pattern, where project-specific logic is accessed through standardized aliases. The primary goal is to eliminate ad-hoc helper inflation and ensure a single canonical owner for every system concern.

The architecture relies on high-level facades—specifically c, m, t, p, and u—which represent Constants, Models, Typings, Protocols, and Utilities respectively. These facades are implemented across the monorepo packages, ensuring that every package inherits from a consistent architectural baseline while maintaining clear boundaries between production source, tests, and examples.

Sources: AGENTS.md:273-280, AGENTS.md:307-313

Core Facade Architecture

The FLEXT system uses a centralized facade pattern where core logic is exported via single-letter aliases. This pattern is enforced to ensure that abstractions are layered correctly by project boundaries. The standard exports are defined in package initialization files and are often implemented using lazy loading to optimize performance.

Standardized Aliases

The following table describes the canonical aliases used throughout the FLEXT workspace:

Alias	Component	Description
c	Constants	Static configuration and immutable values.
m	Models	Pydantic v2 models and data structures.
t	Typings	Complex type definitions and JSON-safe mappings.
p	Protocols	Structural typing and interface definitions.
u	Utilities	Shared helper functions and field definitions.
r	Result	Railway pattern implementation for fallible paths.
e	Exceptions	Project-specific error types.
x	Mixins	Reusable logic composed via MRO.

Sources: AGENTS.md:315-322, src/flext/init.py:12-22, libs/init.py:17-27

Implementation via Lazy Loading

FLEXT utilizes install_lazy_exports and build_lazy_import_map to manage these facades. This ensures that heavy dependencies or complex model trees are only loaded when accessed via the facade.

The diagram above shows how consumer code interacts with the facade map rather than importing internal modules directly.
Sources: src/flext/init.py:23-53, libs/init.py:36-54

Namespace Governance

The FLEXT engineering law mandates strict adherence to the namespace pattern to prevent "bypass" or "hardcode" scenarios. Developers are prohibited from creating ad-hoc helpers without proving that a canonical owner is missing.

Rules of Engagement

1. Single Owner: Every concern must have one canonical class or namespace owner.
2. MRO over Duplication: Composing via MRO and Mixins (x) is preferred over duplicating utility functions.
3. Export-Only Init: __init__.py files must remain export-only, serving as the clean interface for the package facades.
4. No Direct Framework Imports: Consumer projects should not import framework libraries directly; they must go through the provided FLEXT abstractions.

Sources: AGENTS.md:300-305, AGENTS.md:308-313, codex.md:12-14

Railway Pattern Integration

Fallible application paths must return a Result type r[T] from the r facade. This avoids ad-hoc error dictionaries or raw exception handling for control flow, maintaining type safety across the namespace.

Usage in Processing Pipelines

Facades are extensively used in advanced processing examples to manage complex data flows and parallel execution. The AdvancedProcessingExample demonstrates using the m, p, r, t, and u facades to build a declarative pipeline.

Pipeline Stage Logic

Pipelines are constructed using a sequence of operations that take a JSON mapping and return a r[PipelineStageData].

Component	Facade Usage	Purpose
ItemDict	t.JsonMapping	Type-safe dictionary for data items.
PipelinePayload	m.BaseModel	Structured data container for pipeline state.
execute()	p.Result	Interface for pipeline execution return.
u.Field	u.Field	Pydantic field definitions for metadata.

Sources: examples/advanced_processing_example.py:46-70, examples/advanced_processing_example.py:108-120

Example: Declarative Pipeline Execution

In the following snippet, the pipeline determines the function to run by looking up keys in a map, with all types governed by the t (Typings) and p (Protocols) facades.

def execute(self) -> p.Result[PipelineStageData]:
    stage_functions: t.MappingKV[str, Callable[[t.JsonMapping], p.Result[PipelineStageData]]] = {
        "validate": self._validate_batch,
        "process": self._process_parallel,
        "analyze": self._analyze_results,
    }
    # ... logic to iterate stages and return r.ok() or r.fail()

Sources: examples/advanced_processing_example.py:108-115

Summary of Constraints

Facades and Namespaces are the primary mechanism for enforcing FLEXT's "North Star" goal: ensuring integration is built on primitives that are typed and validated.

• Zero Bypass: Using direct tool invocations or raw imports that bypass the facades is considered a governance violation.
• SSOT (Single Source of Truth): Config-owned values must be read from the same typed SSOT production reads, usually accessed via the m facade.
• Refactor Resilience: The facade pattern allows for broad workspace-wide updates (e.g., renaming a public member) to be carried out in a single batch because consumers rely on the stable facade aliases rather than internal paths.

Sources: AGENTS.md:21-25, AGENTS.md:275-280, AGENTS.md:243-248