Home
Relevant source files
The following files were used as context for generating this wiki page:
flext-web is the modern web interface for the FLEXT platform, an enterprise-grade data integration framework built with Python 3.13+. It provides a high-level abstraction for web service lifecycle management, supporting both FastAPI and Flask application factories while enforcing strict architectural standards like Railway-Oriented Programming and Type Safety.
The module acts as a platform-class project within the FLEXT ecosystem, offering a unified public facade through the web instance to simplify operations such as starting services, health monitoring, and authentication management.
Sources: index.md:7-9, README.md:1-12, development.md:20-22
Architecture and Components
The architecture of flext-web follows the FLEXT "Unified API" and "Clean Architecture" principles. It is centered around a canonical public facade located in api.py, which exposes the web instance for operational tasks.
Core Structure
The project is organized into several key layers to separate concerns and ensure maintainability:
| Component | Responsibility | Relevant Files |
|---|---|---|
| Public Facade | Thin entry point for all operational code using the web instance. | api.py |
| App Factories | Generators for FastAPI and Flask application instances. | app.py |
| Services | Core business logic including Auth, Entities, Health, and Web. | services/ |
| Base Service | Common base class for services with typed runtime settings. | base.py |
| Protocols | Runtime registry and protocol-backed behavior definitions. | protocols.py |
| Support Tiers | SSOT (Single Source of Truth) for models, constants, and typings. | models.py, constants.py |
Sources: development.md:20-30, development/README.md:16-22
Service Lifecycle Flow
The following diagram illustrates the standard lifecycle of a web service operation using the web facade.
Key Patterns and Standards
flext-web enforces several non-negotiable development patterns to maintain enterprise-grade quality.
Type Safety and Railway-Oriented Programming (ROP)
The project adheres to a "ZERO TOLERANCE" policy regarding type safety, requiring MyPy strict mode and complete annotations. Additionally, ROP is used for error handling, where operations return a Result object (often aliased as p.Result or r) instead of raising exceptions.
from __future__ import annotations
# Example of ROP and Strict Typing
def process_data(data: t.JsonMapping) -> p.Result[ProcessedData]:
if not data:
return r[ProcessedData].fail("Data required")
return r[ProcessedData].ok(ProcessedData(**data))
Sources: guides/development.md:121-150
Unified Models Pattern
Models are encapsulated within project-specific model classes to avoid scattered definitions across the codebase.
Sources: guides/development.md:158-175
Development Workflow
Development within flext-web is governed by a strict "Make Contract." Developers must use specific make targets to ensure quality gates are passed before any changes are committed.
Quality Gates
make check: Performs linting (Ruff) and type checking (MyPy).make test: Runs the test suite with a focus on unit and integration tests.make val: Full validation suite required before pushing code.make gen: Used when exports or lazy initialization need regeneration.
Sources: index.md:21-23, development.md:37-41, development/README.md:24-27
Project Dependencies
As defined in pyproject.toml, the project relies on several key frameworks and internal FLEXT libraries:
- FastAPI (>=0.136.1) and Flask (>=3.1.3)
- flext-core & flext-cli (v0.12.0-dev)
- Pydantic v2 for settings and validation.
- Uvicorn as the ASGI server.
Sources: pyproject.toml:95-112
Configuration
Configuration is managed via namespaced settings singletons. The FlextWebSettings model allows for direct, type-safe access to environment and runtime variables.
from flext_web import FlextWebSettings, settings
runtime_settings = FlextWebSettings(
Web={"host": "localhost", "port": 8080}, debug=settings.debug
)
Sources: development.md:43-52
Summary
flext-web serves as the centralized interface for deploying web applications within the FLEXT ecosystem. By strictly enforcing patterns like Railway-Oriented Programming and utilizing a facade-based architecture, it ensures that web services are consistent, type-safe, and easily maintainable. Developers should primarily interact with the web instance and follow the standard make workflow to ensure compliance with the project's quality gates.
Sources: README.md:27-30, development/README.md:43-50