Module Map & Structure
Relevant source files
The following files were used as context for generating this wiki page:
FLEXT Quality organizes its components into a unified orchestration platform for code quality and agent tooling. The system follows a layered architecture where a public facade exposes functionality derived from internal modules for rules, hooks, and Model Context Protocol (MCP) tools. Sources: README.md:21-23, AGENTS.md:12-14
The project uses a structured filesystem layout to separate concerns between core logic, external integrations, and auto-generated data models. Sources: AGENTS.md:16-25
Core Architectural Layout
The project structure separates the public command surface and API from internal service implementations and domain models. The src/flext_quality/ directory contains the primary package logic.
Package Structure Overview
| Directory/File | Description |
|---|---|
api.py | The main FlextQuality facade class. |
cli.py | Command-line surface for Check and Validate operations. |
mcp/ | Tools for Model Context Protocol integration (e.g., search_code). |
hooks/ | Logic for registering, configuring, and executing system hooks. |
integrations/ | Connectors for external tools like Claude Context and Claude Mem. |
rules/ | Quality rules engine and rule definitions. |
_models/ | Domain models split into parts to maintain module size limits. |
Sources: AGENTS.md:16-25, src/flext_quality/_models/flextqualitymodels_part_01.py:1-12
Dependency Flow
FLEXT Quality integrates with the broader FLEXT ecosystem, depending on foundation packages for core functionality, CLI handling, and web components. Sources: README.md:37-41, AGENTS.md:10-10
The diagram shows the relationship between flext-quality and its core dependencies and internal modules. Sources: pyproject.toml:23-28, AGENTS.md:10-10
Key System Symbols
The following classes and modules represent the primary points of interaction within the package:
FlextQuality: The central facade located inapi.py. It handles high-level operations such asexecute_hookandload_rules. Sources: AGENTS.md:28-30FlextQualityMcpTools: Located inmcp/tools.py, this class exposes semantic search and hook execution to MCP-compatible agents. Sources: AGENTS.md:31-31, src/flext_quality/mcp/tools.py:16-18FlextQualityHookManager: Manages the registration and lifecycle of hooks withinhooks/manager.py. Sources: AGENTS.md:32-32
Data Models and Domains
FLEXT Quality utilizes Pydantic-2 models to define the documentation and code quality domains. These models are split across multiple files (e.g., FlextQualityModelsPart01) to comply with package size constraints. Sources: src/flext_quality/_models/flextqualitymodels_part_01.py:7-14
Quality Metrics and Configurations
The Quality namespace within the models defines structures for audit results and validation settings. Sources: src/flext_quality/_models/flextqualitymodels_part_01.py:27-30
| Model | Purpose |
|---|---|
AuditMetrics | Tracks total issues, severity breakdown, and quality scores. |
QualityThresholdsConfig | Defines limits for file age, word counts, and broken links. |
ContentChecksConfig | Toggles for freshness, completeness, and consistency checks. |
MarkdownStyleConfig | Specifies preferences for headings, lists, and code blocks. |
Issue | Represents a canonical documentation issue with severity and recommendation. |
Sources: src/flext_quality/_models/flextqualitymodels_part_01.py:31-40, src/flext_quality/_models/flextqualitymodels_part_01.py:53-60, src/flext_quality/_models/flextqualitymodels_part_01.py:365-375
MCP Orchestration Flow
Model Context Protocol (MCP) tools provide an interface for AI agents to interact with the quality engine and project context. Sources: src/flext_quality/mcp/tools.py:12-14
This diagram illustrates how MCP tools act as a bridge between AI agents and the underlying search and validation engines. Sources: src/flext_quality/mcp/tools.py:46-60, src/flext_quality/mcp/tools.py:84-100
Module Integration Points
The package exposes several public extensions for ecosystem-wide integration:
- CLI Extensions:
FlextQualityCliprovides the main entry point viaflext-qualityscript. Sources: README.md:43-45, pyproject.toml:60-60 - Configuration:
FlextQualityConfigandFlextQualitySettingsmanage environment-specific variables. Sources: src/flext_quality/init.py:81-90 - Utilities:
FlextQualityUtilities(aliased asu) provides helper functions for regex compilation and YAML loading. Sources: src/flext_quality/utilities.py:20-25, src/flext_quality/init.py:127-127
Summary
FLEXT Quality implements a modular architecture centered around a unified facade (FlextQuality). It leverages a rules engine for code validation and MCP tools for semantic search, all governed by typed domain models. The structure ensures that quality gates, such as Ruff and Pyright checks, are orchestrated through a consistent command surface. Sources: README.md:21-23, AGENTS.md:12-14, AGENTS.md:37-39