Complete Integration Workflow

Relevant source files

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

• examples/ex_11_complete_integration.py
• examples/ex_12_pydantic_driven_cli.py
• examples/ex_01_getting_started.py
• examples/README.md
• tests/unit/_cases/test_examples_smoke/testsflextcliexamplessmoke_part_04.py
• AGENTS.md

The Complete Integration Workflow in flext-cli represents the standardized architectural approach for building production-ready, type-safe CLI applications. It leverages a "Railway Pattern" for error handling, Pydantic 2 for robust data validation, and a public facade (cli) for consistent interaction with terminal output, user prompts, and file persistence. This workflow ensures that all features—ranging from typed settings to interactive data management—work seamlessly together in a singleton-driven consistency model.

Sources: examples/ex_11_complete_integration.py:1-25, examples/README.md:1-20

Core Architectural Patterns

The integration workflow is built upon several foundational pillars that define how data flows and how errors are managed within the CLI environment.

The Railway Pattern

Every fallible operation within the workflow returns a p.Result[T] object. This allows for chaining operations where the failure of one step bypasses subsequent logic, ensuring that the CLI fails "honestly" with descriptive error messages rather than crashing.

Public Facade Interaction

Applications interact with the library through the cli facade. This provides a unified interface for:

• Output: Using cli.print with standardized styles (e.g., MessageStyles.GREEN, BOLD_RED).
• Input: Gathering user data via cli.prompt.
• Persistence: Reading and writing JSON/YAML files using typed adapters.

Sources: examples/ex_11_complete_integration.py:34-95, examples/ex_12_pydantic_driven_cli.py:55-100, examples/README.md:38-55

Data Flow Overview

The following diagram illustrates the typical data flow in a complete integration, moving from user input or file loading through validation to final persistence.

Key Components and Logic

1. Data Management and Persistence

The workflow utilizes a central manager (e.g., DataManagerCLI) to orchestrate state. Data is typically stored as a t.JsonMapping and persisted via cli.write_json_file.

Component	Responsibility	Relevant Methods
DataManagerCLI	Orchestrates the full lifecycle of data.	run_workflow(), add_entry()
JSON Facade	Handles typed file I/O operations.	cli.read_json_file(), cli.write_json_file()
Prompt Surface	Interacts with the user for runtime data.	cli.prompt(), cli.configure()

Sources: examples/ex_11_complete_integration.py:34-95, tests/unit/_cases/test_examples_smoke/testsflextcliexamplessmoke_part_04.py:22-45

2. Pydantic-Driven Validation

Integration involves converting raw CLI arguments or JSON payloads into validated Pydantic models. This provides auto-generated help text, IDE autocomplete, and strict type checking.

def convert_and_validate_with_pydantic(
    data: t.JsonMapping,
) -> p.Result[m.Examples.AdvancedDatabaseConfig]:
    """Convert raw data to validated Pydantic model."""
    try:
        return r[m.Examples.AdvancedDatabaseConfig].ok(
            m.Examples.AdvancedDatabaseConfig.model_validate(data)
        )
    except c.ValidationError as error:
        return r[m.Examples.AdvancedDatabaseConfig].fail(f"Validation failed: {error}")

Sources: examples/ex_12_pydantic_driven_cli.py:126-138, examples/ex_01_getting_started.py:32-40

3. Integrated Workflow Execution

The sequence diagram below details the interaction between the CLI manager, the public facade, and the underlying file system during a standard data entry task.

Validation and Error Resilience

A critical part of the integration workflow is its resilience to environment failures. Tests validate that the workflow handles:

• Missing Files: Returns a failure result instead of throwing a FileNotFoundError.
• Invalid Formats: Surfaces Pydantic or JSON parsing errors through the result contract.
• Unwritable Paths: Correctly reports OS-level permissions or directory issues.

Sources: tests/unit/_cases/test_examples_smoke/testsflextcliexamplessmoke_part_04.py:47-73, AGENTS.md: P0 — Tests validate config changes

Summary

The Complete Integration Workflow provides a robust blueprint for CLI development by combining the Railway Pattern for error handling, Pydantic for schema enforcement, and the cli facade for standardized interaction. By centralizing these patterns, the project ensures that developers can build complex tools that remain maintainable, testable, and user-friendly.

Sources: examples/ex_11_complete_integration.py:1-20, examples/README.md:90-105