FastAPI Architecture Validation

Relevant source files

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

• src/flext_quality/rules/engine.py
• src/flext_quality/_constants/values.py
• tests/unit/test_rules_engine_validators.py
• AGENTS.md
• src/flext_quality/_models/flextqualitymodels_part_01.py
• src/flext_quality/utilities.py
• src/flext_quality/_models/flextqualitymodels_part_02.py

FastAPI Architecture Validation in the flext-quality project ensures structural integrity and enforces tier boundaries across API and service layers. The system uses a declarative rules engine to scan source code for forbidden patterns, specifically targeting illegal imports that bypass established architectural layers. This validation is part of a unified orchestration platform for agent tooling and quality workflows.

Sources: AGENTS.md:9, src/flext_quality/rules/engine.py:16

Core Validation Engine

The FlextQualityRulesEngine serves as the primary component for executing architecture and quality checks. It loads declarative rules from YAML files and validates code against these rules using regex-based pattern matching.

Rules Engine Workflow

The engine follows a multi-step process to evaluate files:

1. Rule Loading: The engine reads definitions from YAML files using FlextQualityRulesLoader.
2. File Discovery: It identifies target Python files within the specified project path.
3. Pattern Matching: For each file, it applies pre-defined regex patterns to detect violations.
4. Violation Reporting: It generates structured reports containing the rule name, file path, line number, and severity level.

This diagram illustrates the internal logic of the validate and _check_rule methods within the rules engine.
Sources: src/flext_quality/rules/engine.py:48-124

Tier and Boundary Enforcement

Architecture validation enforces strict separation between layers. The TierValidator specifically flags imports that violate the dependency hierarchy, such as low-level modules importing directly from the api or services tiers.

Tier Violation Detection

The system uses pre-compiled regular expressions to identify forbidden import patterns. If a file categorized in a lower tier (like constants.py) attempts to import from the services or api layers, the validator raises a tier-violation issue.

Pattern Constant	Regex Pattern	Description
PATTERNS_TIER_VIOLATION	from flext_.*\\.(services|api) import	Detects illegal upward imports into API/Service tiers.
PATTERNS_ANY_TYPE	:\\s*Any\\b	Flags usage of the unconstrained Any type.
PATTERNS_TYPE_CHECKING	if\\s+TYPE_CHECKING\\s*:	Identifies type-checking guards for internal logic.

Sources: src/flext_quality/_constants/values.py:104-110, tests/unit/test_rules_engine_validators.py:230-240

Data Models and Schemas

Validation results and configurations are strictly typed using Pydantic models. These models ensure consistency across the documentation and code quality domains.

Quality Rule Definitions

Individual rules are defined using the RuleDefinition model, which tracks the rule's behavior and classification.

Field	Type	Description
name	str	Unique identifier for the rule.
type	RuleType	Category (e.g., content, style, link, accessibility).
pattern	str | None	Optional regex pattern to match against.
action	str	Action to take on match (e.g., flag error or warning).
enabled	bool	Toggle for rule activity.

Sources: src/flext_quality/_models/flextqualitymodels_part_01.py:532-564

Audit and Validation Results

When an architecture audit completes, it produces AuditorResults containing aggregate metrics and specific findings.

class AuditorResults(_WebModels.ManagedModel):
    timestamp: str
    files_analyzed: int
    issues: MutableSequence[MutableMapping[str, t.Primitives | ...]]
    metrics: AuditMetrics
    recommendations: MutableSequence[AuditRecommendation]

Sources: src/flext_quality/_models/flextqualitymodels_part_02.py:279-312

Validation Execution Workflow

The orchestration layer coordinates between the CLI, the Rules Engine, and various specialized validators (e.g., Tier, Pattern, ForbiddenPattern).

This sequence shows how the system aggregates violations from multiple validators during a single validation pass.
Sources: src/flext_quality/rules/engine.py:68-91, tests/unit/test_rules_engine_validators.py:254-268

Summary of Validation Constraints

Architecture validation enforces the following specific constraints found in the project:

• Tier Isolation: Prevents circular or upward dependencies between the core, services, and API layers.
• Pattern Control: Restricts the use of specific Python patterns like type: ignore or cast() in sensitive architectural blocks.
• Strict Typing: Enforces the presence of language specifiers in code blocks and validates proper heading hierarchies in documentation.
• Link Integrity: Validates internal and external links within documentation to ensure structural consistency.

Sources: src/flext_quality/_constants/values.py:120-130, src/flext_quality/_models/flextqualitymodels_part_01.py:240-260