Domain Models & Entities
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The FLEXT Plugin system relies on a structured set of domain models and entities to manage plugin lifecycles, execution states, and discovery metadata. These models extend the core flext-core patterns, adhering to Railway-Oriented Programming (ROP) principles and utilizing r[T] types for robust error handling. The primary focus of these entities is to provide a standardized interface for plugin identity, validation, and operational monitoring within the FLEXT Platform.
Sources: src/flext_plugin/models.py:20-28, src/flext_plugin/_utilities/plugin_platform.py:173-180
Core Domain Entities
Plugin Entity
The FlextPluginModels.Plugin.Entity is the central domain object representing a plugin. It manages identity (via unique IDs), semantic versioning, and operational state (enabled/disabled). It includes built-in methods for recording execution metrics and error tracking directly into the entity's metadata.
The diagram above illustrates the structure and primary behaviors of the Plugin Entity.
Sources: src/flext_plugin/models.py:34-192, tests/unit/test_domain_entities.py:30-45
Plugin Types and Status
Plugins are categorized by a Type (e.g., TAP, TARGET, SERVICE) and maintain a Status (e.g., ACTIVE, INACTIVE, ERROR) to reflect their current operational readiness.
| Field | Type | Description |
|---|---|---|
name | str | Unique identifier; must follow specific pattern and length constraints. |
plugin_version | str | Semantic version string (X.Y.Z). |
plugin_type | c.Plugin.Type | Classification (e.g., DATABASE, AUTHENTICATION, UTILITY). |
is_enabled | bool | Flag indicating if the plugin is available for use. |
Sources: src/flext_plugin/models.py:56-94, tests/unit/test_models.py:48-69
Lifecycle and Execution Models
Plugin Execution Entity
The PluginExecution entity tracks the lifecycle of a specific plugin run. It captures input data, start/end timestamps, and final results or error messages.
This flow represents the state transitions of a plugin execution from initiation to completion.
Sources: src/flext_plugin/_utilities/plugin_platform.py:41-86
Execution Metadata Fields
When an execution occurs, the Plugin Entity updates its internal metadata to track historical performance:
execution_count: Total number of times the plugin has run.total_execution_time: Cumulative time spent in execution.success_count/failure_count: Tally of outcome results.last_error: The most recent error message encountered.
Sources: src/flext_plugin/models.py:127-167, tests/unit/test_domain_entities.py:64-83
Discovery and Registry Models
Discovery Data
DiscoveryData is an immutable value object representing the result of a plugin discovery process (e.g., scanning the file system or entry points). It bridges the gap between raw file system paths and formal Plugin Entities.
Sources: src/flext_plugin/models.py:194-230, tests/unit/test_models.py:113-125
Plugin Registry
The PluginRegistry serves as a central storage for registered plugins, maintaining schema versions and update timestamps. It supports multiple registration scopes, such as CLASS or INSTANCE.
| Attribute | Type | Description |
|---|---|---|
version | str | Registry schema version. |
plugins | JsonMapping | Map of registered plugin names to their data. |
last_updated | datetime | Timestamp of the most recent change. |
Sources: src/flext_plugin/models.py:270-291, src/flext_plugin/_utilities/plugin_platform.py:88-100
Validation Logic
All domain entities implement business rule validation via the validate_business_rules() method. This ensures:
- Identity: The plugin name is non-empty and adheres to naming constraints.
- Versioning: The version string strictly follows the semantic
X.Y.Zformat using numeric parts. - Integrity: Required metadata and type classifications are present.
Sources: src/flext_plugin/models.py:171-192, tests/unit/test_domain_entities.py:102-111, examples/basic-plugin.md:154-180
Conclusion
The Domain Models & Entities in flext-plugin provide a robust foundation for the plugin ecosystem. By separating discovery data from active entities and maintaining detailed execution state, the system enables complex plugin orchestration with high observability and strict type safety.