Core Architecture Models
Relevant source files
The following files were used as context for generating this wiki page:
Core Architecture Models represent the foundational data structures and domain logic used across the FLEXT infrastructure for build automation, code generation, and workspace management. These models provide a typed interface for complex operations such as documentation generation, quality gate enforcement, and automated code refactoring.
The system relies on Pydantic-based models, categorized into ContractModel for immutable policy/configuration and ArbitraryTypesModel for mutable execution results and reports. This differentiation ensures strict type safety for infrastructure settings while allowing flexibility for runtime diagnostics and reporting.
Model Hierarchy and Base Policy
The architecture follows a strict base policy for model definition to distinguish between configuration and execution state.
- ContractModel: Reserved for immutable settings, policies, and API contracts.
- ArbitraryTypesModel: Used for mutable report payloads, result summaries, and intermediate execution states.
- BaseModel: Used for unified item payloads within reports that require strict field forbidding.
Sources: src/flext_infra/_models/validate.py:16-20, src/flext_infra/_models/refactor.py:27-31, src/flext_infra/_models/docs.py:32-37
Model Relationships Diagram
The following diagram illustrates the relationship between base models and specialized infrastructure domains.
Explanation: Base classes from flext_cli are extended by infrastructure-specific containers that group related models for documentation, validation, and quality checks. Sources: src/flext_infra/_models/base.py:20, src/flext_infra/_models/docs.py:20, src/flext_infra/_models/validate.py:22
Documentation Models
The documentation system uses models to manage the lifecycle of generated content, from initial audit to final disk write.
Key Documentation Classes
| Class | Type | Purpose |
|---|---|---|
DocsGenerateRequest | Contract | Consolidates parameters for generation calls (workspace, output, apply). |
DocScope | Arbitrary | Targets a specific project or workspace root for documentation context. |
DocsPhaseReport | Contract | Unified report payload covering audit, fix, build, and generate phases. |
DocsProjectMeta | Contract | SSOT for metadata bundled from pyproject.toml and documentation tables. |
Explanation: The documentation flow begins with a request that is resolved into scopes, followed by audit and generation phases, ultimately producing a comprehensive phase report. Sources: src/flext_infra/_utilities/docs_generate.py:166-200, src/flext_infra/_models/docs.py:23
Quality Gate and Validation Models
Quality gates ensure project health through standardized checks (Ruff, Pyright, Bandit, Pytest). Results are aggregated into structured reports.
Diagnostics and Reporting
The system captures diagnostics from various tools into a unified Issue model and aggregates them into GateExecution and ProjectResult.
class Issue(m.ContractModel):
file: str
line: int
column: int
code: str
message: str
severity: str = c.Infra.ERROR
Sources: src/flext_infra/_models/check.py:129-141
SARIF 2.1.0 Integration
For integration with external security and linting platforms, the SarifReport model provides a 2.1.0 compliant representation of all gate findings.
Sources: src/flext_infra/_models/check.py:205-300
Refactor and Maintenance Models
Refactoring models support complex code migrations, such as MRO (Method Resolution Order) changes and namespace enforcement.
- RefactorProjectInfo: Tracks project metadata and package roots discovered during scanning.
- MethodInfo: Captures metadata about methods (decorators, categories) to support automated reordering within classes.
- LooseClassViolation: Models naming standard violations discovered by the refactor scanner.
- Checkpoint: A serializable state for long-running refactor operations to ensure safety and recovery.
Sources: src/flext_infra/_models/refactor.py:84-180
Refactor Logic Flow
Explanation: The refactor process involves scanning for violations, recording progress in checkpoints for safety, and applying transformations that modify source code. Sources: src/flext_infra/_models/refactor.py:61-150
Summary of Shared Mixins
The infrastructure uses mixins to standardize common CLI parameters and data fields across different domain models.
| Mixin | Fields | Applied To |
|---|---|---|
ScopeMixin | workspace, projects, module, fail_fast | All CLI commands targeting project subsets. |
WriteMixin | apply, gates | Commands performing destructive writes or code changes. |
ReadMixin | report, output_dir | Reporting and auditing commands. |
ProjectNameMixin | project | Results and errors tied to a specific project. |
Sources: src/flext_infra/_models/mixins.py:26-114
Conclusion
The Core Architecture Models provide the structural backbone for FLEXT infrastructure tooling. By strictly separating configuration (ContractModel) from execution state (ArbitraryTypesModel) and utilizing shared mixins, the system achieves a high degree of type safety and consistency across documentation, validation, and refactoring services.