Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The flext-web project serves as the modern web interface for the FLEXT platform, designed as a "platform" class project within the FLEXT monorepo. It provides a typed, scalable web layer that integrates with core FLEXT services, utilizing FastAPI and Flask factories to expose platform capabilities. The architecture is centered around a canonical public facade pattern, ensuring that operational code interacts with a unified surface rather than internal service implementations.
Sources: index.md, README.md:14, development.md:15-16
Core Architectural Design
The architecture follows Clean Architecture principles and a "Facade-First" approach. The primary entry point for all operations is a thin public facade represented by the web instance. This design keeps the public API surface stable while allowing internal service logic to evolve independently.
System Components and Layout
The project is structured into distinct tiers to maintain a Single Source of Truth (SSOT):
| Component | Responsibility |
|---|---|
Facade (api.py) | Thin public facade and shared web instance for operational access. |
App Factories (app.py) | Framework-specific logic for generating FastAPI and Flask applications. |
Service Base (base.py) | Common service foundations with typed runtime settings. |
Settings (_settings.py) | Direct namespaced settings singleton and Pydantic models. |
Services (services/) | Canonical implementations for Auth, Entities, Health, and Web layers. |
Protocols (protocols.py) | Runtime protocol and registry behavior management. |
Sources: development.md:18-25, development/README.md:16-22
High-Level Interaction Flow
The following diagram illustrates how external requests or operational code interacts with the flext-web facade and its underlying services.
The diagram shows the hierarchical dependency where the web facade acts as the gateway to specialized services and framework factories.
Sources: development.md:18-25, development/README.md:25-33
Key Implementation Patterns
Railway-Oriented Programming (ROP)
The project strictly enforces ROP for error handling. Instead of traditional exception-based flows, all operations return a Result object (often aliased as r). This ensures that errors are treated as data and passed through the pipeline via methods like map and flat_map.
def validate_and_process(data: dict) -> p.Result[ProcessedData]:
return (
validate_data(data)
.flat_map(transform_data)
.map(enrich_data)
.map_error(handle_error)
)
Sources: guides/development.md:126-140
Unified Models Pattern
Models are organized using a [Project]Models pattern to prevent scattered definitions. This approach encapsulates Requests, Responses, and Configurations within a single namespace.
Sources: guides/development.md:144-158
Namespaced Settings
Configuration access is direct and namespaced, utilizing Pydantic for validation. The settings singleton provides a typed interface for accessing runtime parameters.
Sources: development.md:37-45
Service Lifecycle Management
Lifecycle operations such as starting, stopping, and health monitoring are strictly managed through the public facade. This prevents fragmentation where different parts of the application might attempt to manage service states independently.
Service Operation Sequence
The sequence demonstrates the requirement that lifecycle operations stay on the facade.
Sources: development.md:47-54, development/README.md:25-33
Quality and Development Standards
The architecture is protected by "Quality Gates" and strict development rules:
- Type Safety: Zero tolerance for missing type annotations; MyPy strict mode is enforced.
- Facade Constraint: Tests and examples must exercise the public facade (
web), not internal service classes. - Thin Facade:
api.pymust remain thin; actual behavior resides in services, protocols, or app factories.
Sources: development.md:27-35, guides/development.md:109-115
Conclusion
The flext-web architecture provides a robust, typed interface for the FLEXT platform by combining framework factories (FastAPI/Flask) with a strict facade pattern and Railway-Oriented Programming. This structure ensures that while the web technologies or internal service logic may change, the operational interface remains consistent and type-safe.
Sources: README.md:28-35, development.md:18-25