FLEXT Infra Overview
Relevant source files
The following files were used as context for generating this wiki page:
FLEXT Infrastructure (flext-infra) is a comprehensive tooling suite designed for build automation, code generation, and workspace management within the FLEXT ecosystem. It provides a standardized framework for managing multi-project workspaces, ensuring consistency across documentation, dependency management, and quality gates.
The system operates as a set of utilities and protocols that govern project lifecycles, from initial scaffolding and metadata management in pyproject.toml to the generation of API references and technical documentation. It enforces a strict "Single Source of Truth" (SSOT) philosophy, deriving project documentation and configuration directly from code exports and docstrings.
Sources: README.md:9-11, src/flext_infra/_utilities/docs_render.py:207-210, src/flext_infra/_constants/base.py:17-21
Core Architectural Components
The infrastructure is built upon a modular architecture consisting of models, protocols, and utility services. These components work together to provide automated workspace governance.
Project & Workspace Models
The system uses Pydantic-based models to define the state of the workspace and its constituent projects. Key models include DocScope, which defines the targeting of a specific project or the workspace root, and DocsPhaseReport, which tracks the outcome of infrastructure operations.
Sources: src/flext_infra/_models/docs.py:53-66, src/flext_infra/_models/docs.py:117-130
Protocols and Service Interfaces
Standardization is achieved through runtime-checkable protocols. These define the expected behavior for various service types:
- Checker: Validates project and workspace quality.
- Generator: Handles artifact and documentation generation.
- Discovery: Locates and classifies projects within a workspace.
- Orchestrator: Executes commands (e.g.,
makeverbs) across multiple projects.
Sources: src/flext_infra/_protocols/base.py:72-108, src/flext_infra/_protocols/base.py:270-281
High-Level Service Flow
The following diagram illustrates the relationship between the core infrastructure services and the project workspace:
The diagram shows how discovery services identify project scopes, which are then processed by audit, generation, and build utilities to produce various artifacts.
Sources: src/flext_infra/_utilities/docs_generate.py:176-220, src/flext_infra/_utilities/docs.py:99-113
Documentation Lifecycle
Documentation management is a primary feature of flext-infra. It automates the creation of READMEs, API references, and MkDocs configurations based on project metadata.
Generation Logic
The DocsGenerate utility manages the lifecycle of generated files. It uses a contract-driven approach where the "Public API Contract" is extracted from __init__.py exports and pyproject.toml.
| Generated Artifact | Source of Truth | Purpose |
|---|---|---|
README.md | pyproject.toml + exports | Project entry point and high-level overview. |
docs/index.md | pyproject.toml + docstrings | MkDocs landing page for the project. |
api-reference/ | Code exports + docstrings | Technical documentation generated via mkdocstrings. |
catalog.md | Workspace discovery | A central list of all projects in the workspace. |
Sources: src/flext_infra/_utilities/docs_render.py:246-302, src/flext_infra/_utilities/docs_generate.py:65-115
Document Scoping
FLEXT distinguishes between the Workspace Root (scope root) and individual Projects. Scopes determine which files are collected and how paths are resolved.
- Root Scope: Manages the global project catalog and the workspace-wide MkDocs configuration.
- Project Scope: Manages specific package exports, local guides, and project-level READMEs.
Sources: src/flext_infra/_models/docs.py:53-66, src/flext_infra/_utilities/docs.py:17-48
Workspace Quality Gates
Infrastructure operations are governed by "Quality Gates," which are canonical make verbs used to ensure code health and consistency.
Standard Verbs
The system recognizes four primary quality gates:
check: Executes quality and linting checks.test: Runs the test suite.val: Performs formal validation of architectural constraints.docs: Audits, fixes, and builds documentation.
Sources: README.md:38-40, src/flext_infra/_constants/base.py:228-237
Audit and Fix Pipeline
The audit system detects issues such as broken internal links or missing docstrings for public symbols. The fix utility can automatically correct some of these issues, such as updating Table of Contents (TOC) blocks or fixing simple markdown link targets.
The sequence shows the process of identifying documentation issues and applying automated fixes to the local filesystem.
Sources: src/flext_infra/_utilities/docs_audit.py:61-98, src/flext_infra/_utilities/docs_fix.py:73-100
Configuration and Metadata
flext-infra relies heavily on pyproject.toml for configuration. It uses a specific [tool.flext.docs] section to override default behaviors and define project classes.
Project Classification
Projects are classified into several categories to determine which infrastructure rules apply:
infra: Infrastructure tooling (likeflext-infraitself).integration: Integration-specific packages.domain: Core business logic packages.test: Test-specific utilities.
Sources: src/flext_infra/_utilities/docs_render.py:212-214, src/flext_infra/_constants/base.py:21-25
Key Constants
The system defines a wide range of constants for file paths, regex patterns, and result statuses to maintain consistency.
| Constant Category | Examples |
|---|---|
| Reserved Keys | summary, scope, violations, file, status |
| Directives | ::: package_name (mkdocstrings) |
| Pathing | .reports/docs, docs/, src/ |
| Regex | MARKDOWN_LINK_RE, PYTHON_FENCE_RE, HEADING_RE |
Sources: src/flext_infra/_constants/base.py:356-384, src/flext_infra/_utilities/docs_render.py:148-154, src/flext_infra/_constants/docs.py:23-55
Summary
flext-infra serves as the backbone for workspace consistency within the FLEXT ecosystem. By automating the extraction of metadata and the generation of standardized documentation, it reduces manual maintenance overhead while enforcing high-quality engineering standards. Its model-driven approach ensures that every project within a workspace follows a predictable structure, facilitating easier onboarding and maintenance.
Sources: README.md:9-11, src/flext_infra/_utilities/docs_render.py:246-249