Getting Started

Relevant source files

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

• guides/getting-started.md
• guides/development.md
• development.md
• pyproject.toml
• README.md
• index.md

FLEXT Web is an enterprise-grade web interface for the FLEXT Platform, built using Python 3.13+ and modern architectural patterns such as Clean Architecture and Railway-Oriented Programming. It serves as a modern web surface for the platform, providing unified API facades, strict type safety via Pydantic v2, and integration with common web frameworks like FastAPI and Flask.

Sources: README.md:12-14, guides/getting-started.md:27-32, index.md:7-9

Prerequisites

To begin working with flext-web, ensure your environment meets the following requirements:

• Python: Version 3.13 or higher is strictly required.
• Package Management: Poetry is used for dependency management.
• Version Control: Git is required for repository management.
• Operating System: Linux is the primary target platform for development and execution environments.

Sources: guides/development.md:25-29, pyproject.toml:68, pyproject.toml:254

Installation

Basic Installation

For general usage, install the core framework and specific libraries as needed:

# Install core framework
pip install flext-core

# Install web-specific interface
pip install flext-web

Sources: guides/getting-started.md:38-46

Development Environment Setup

Developers should clone the repository and use the standard FLEXT setup routines:

# Clone the monorepo
git clone https://github.com/flext-sh/flext.git
cd flext

# Automated setup (installs dependencies and pre-commit hooks)
make setup

Sources: guides/development.md:33-40, guides/development.md:44-45

Core Architecture and Entry Points

flext-web is centered on a canonical public facade designed to simplify access to underlying services. Operationally, developers should prefer interacting with the web instance rather than internal classes.

The Public Facade Flow

The diagram below illustrates how a developer interacts with the web facade to manage application lifecycles and services.

This diagram shows the relationship between the developer, the central web facade, and the internal components it abstracts.
Sources: development.md:14-22, development/README.md:34-42

Key Components

Component	Description	Reference File
web	The primary operational facade instance.	api.py
FlextWebSettings	Namespaced configuration model and singleton.	_settings.py
FlextWebApp	Factory for creating FastAPI and Flask application instances.	app.py
FlextWebServices	Orchestrator for auth, entities, and health layers.	services/

Sources: development.md:17-25, development/README.md:24-32, api-reference/generated/overview.md:11-13

Development Workflow

FLEXT employs strict quality gates. No change is considered complete until it passes linting, type checking, and tests.

Quality Gate Pipeline

This diagram depicts the standard developer workflow for validating changes using repository-provided make targets.
Sources: guides/development.md:49-55, development.md:29-33, guides/development.md:104-106

Essential Commands

Task	Command	Description
Validation	make check PROJECT=flext-web	Runs linting and static analysis.
Testing	make test PROJECT=flext-web	Executes the test suite.
Generation	make gen PROJECT=flext-web	Regenerates exports or lazy initializations.
Full Verify	make val	Comprehensive quality check (Quick validation).

Sources: development.md:31-33, guides/development.md:52-54, development/README.md:36-40

Implementation Standards

Railway-Oriented Programming (ROP)

FLEXT uses r[T] (Result types) for all operations to handle errors functionally without excessive try/except blocks.

# Standard result-based flow
def start_web() -> p.Result[None]:
    return (
        web.configure(settings)
        .flat_map(lambda _: web.start_service())
    )

Sources: guides/development.md:132-138, guides/getting-started.md:112-118

Type Safety

The project enforces a ZERO TOLERANCE policy for missing type annotations. MyPy strict mode and Pyrefly are utilized to ensure the integrity of the MRO (Method Resolution Order) facade boundaries.

Sources: guides/development.md:120-128, pyproject.toml:139-145

Summary

Getting started with flext-web involves setting up a Python 3.13 environment, utilizing the unified web facade for development, and adhering to strict quality gates enforced by make targets. By following the Railway-Oriented Programming pattern and maintaining strict type safety, developers can contribute to a robust, enterprise-grade web interface for the FLEXT platform.

Sources: README.md:23-28, guides/development.md:220-225