recursionpharma · ivanmilevtues · Jul 4, 2025
diff --git a/.codeboarding/Data_Management.md b/.codeboarding/Data_Management.md
@@ -0,0 +1,239 @@
+```mermaid
+
+graph LR
+
+    SpiffWorkflow_serializer_base_Serializer["SpiffWorkflow.serializer.base.Serializer"]
+
+    SpiffWorkflow_serializer_dict_DictionarySerializer["SpiffWorkflow.serializer.dict.DictionarySerializer"]
+
+    SpiffWorkflow_serializer_json_JSONSerializer["SpiffWorkflow.serializer.json.JSONSerializer"]
+
+    SpiffWorkflow_serializer_xml_XmlSerializer["SpiffWorkflow.serializer.xml.XmlSerializer"]
+
+    SpiffWorkflow_bpmn_serializer_workflow_BpmnWorkflowSerializer["SpiffWorkflow.bpmn.serializer.workflow.BpmnWorkflowSerializer"]
+
+    SpiffWorkflow_bpmn_serializer_helpers_spec_TaskSpecConverter["SpiffWorkflow.bpmn.serializer.helpers.spec.TaskSpecConverter"]
+
+    SpiffWorkflow_bpmn_serializer_helpers_spec_EventDefinitionConverter["SpiffWorkflow.bpmn.serializer.helpers.spec.EventDefinitionConverter"]
+
+    SpiffWorkflow_bpmn_serializer_default_task_spec_BpmnTaskSpecConverter["SpiffWorkflow.bpmn.serializer.default.task_spec.BpmnTaskSpecConverter"]
+
+    SpiffWorkflow_bpmn_serializer_migration_version_migration_VersionMigration["SpiffWorkflow.bpmn.serializer.migration.version_migration.VersionMigration"]
+
+    SpiffWorkflow_camunda_serializer_task_spec_UserTaskConverter["SpiffWorkflow.camunda.serializer.task_spec.UserTaskConverter"]
+
+    SpiffWorkflow_bpmn_serializer_default_event_definition_ErrorEscalationEventDefinitionConverter["SpiffWorkflow.bpmn.serializer.default.event_definition.ErrorEscalationEventDefinitionConverter"]
+
+    SpiffWorkflow_serializer_dict_DictionarySerializer -- "inherits from" --> SpiffWorkflow_serializer_base_Serializer
+
+    SpiffWorkflow_serializer_json_JSONSerializer -- "extends" --> SpiffWorkflow_serializer_dict_DictionarySerializer
+
+    SpiffWorkflow_serializer_xml_XmlSerializer -- "extends" --> SpiffWorkflow_serializer_dict_DictionarySerializer
+
+    SpiffWorkflow_bpmn_serializer_workflow_BpmnWorkflowSerializer -- "inherits from" --> SpiffWorkflow_serializer_base_Serializer
+
+    SpiffWorkflow_bpmn_serializer_workflow_BpmnWorkflowSerializer -- "utilizes" --> SpiffWorkflow_bpmn_serializer_helpers_spec_TaskSpecConverter
+
+    SpiffWorkflow_bpmn_serializer_workflow_BpmnWorkflowSerializer -- "interacts with" --> SpiffWorkflow_bpmn_serializer_migration_version_migration_VersionMigration
+
+    SpiffWorkflow_bpmn_serializer_default_task_spec_BpmnTaskSpecConverter -- "inherits from" --> SpiffWorkflow_bpmn_serializer_helpers_spec_TaskSpecConverter
+
+    SpiffWorkflow_bpmn_serializer_default_event_definition_ErrorEscalationEventDefinitionConverter -- "inherits from" --> SpiffWorkflow_bpmn_serializer_helpers_spec_EventDefinitionConverter
+
+    SpiffWorkflow_camunda_serializer_task_spec_UserTaskConverter -- "extends" --> SpiffWorkflow_bpmn_serializer_default_task_spec_BpmnTaskSpecConverter
+
+```
+
+
+
+[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%[email protected]?style=flat-square)](mailto:[email protected])
+
+
+
+## Details
+
+
+
+The `Data Management` component in `SpiffWorkflow` is primarily responsible for the serialization and deserialization of workflow, task, and specification instances, enabling the persistence and retrieval of the workflow engine's state. It is designed with modularity and extensibility in mind, allowing for various formats and BPMN extensions.
+
+
+
+### SpiffWorkflow.serializer.base.Serializer
+
+Abstract base class for serialization and deserialization operations.
+
+
+
+
+
+**Related Classes/Methods**: _None_
+
+
+
+### SpiffWorkflow.serializer.dict.DictionarySerializer
+
+Concrete implementation of Serializer for dictionary conversion.
+
+
+
+
+
+**Related Classes/Methods**:
+
+
+
+- <a href="https://github.com/recursionpharma/SpiffWorkflow/blob/main/SpiffWorkflow/serializer/base.py#L77-L93" target="_blank" rel="noopener noreferrer">`SpiffWorkflow.serializer.base.Serializer` (77:93)</a>
+
+
+
+
+
+### SpiffWorkflow.serializer.json.JSONSerializer
+
+Serializer for converting workflow data to and from JSON strings.
+
+
+
+
+
+**Related Classes/Methods**:
+
+
+
+- <a href="https://github.com/recursionpharma/SpiffWorkflow/blob/main/SpiffWorkflow/serializer/dict.py#L57-L545" target="_blank" rel="noopener noreferrer">`SpiffWorkflow.serializer.dict.DictionarySerializer` (57:545)</a>
+
+
+
+
+
+### SpiffWorkflow.serializer.xml.XmlSerializer
+
+Serializer for converting workflow data to and from XML format.
+
+
+
+
+
+**Related Classes/Methods**:
+
+
+
+- <a href="https://github.com/recursionpharma/SpiffWorkflow/blob/main/SpiffWorkflow/serializer/dict.py#L57-L545" target="_blank" rel="noopener noreferrer">`SpiffWorkflow.serializer.dict.DictionarySerializer` (57:545)</a>
+
+
+
+
+
+### SpiffWorkflow.bpmn.serializer.workflow.BpmnWorkflowSerializer
+
+Specialized serializer for handling BPMN workflows.
+
+
+
+
+
+**Related Classes/Methods**:
+
+
+
+- <a href="https://github.com/recursionpharma/SpiffWorkflow/blob/main/SpiffWorkflow/serializer/base.py#L77-L93" target="_blank" rel="noopener noreferrer">`SpiffWorkflow.serializer.base.Serializer` (77:93)</a>
+
+
+
+
+
+### SpiffWorkflow.bpmn.serializer.helpers.spec.TaskSpecConverter
+
+Abstract helper class for converting task specifications.
+
+
+
+
+
+**Related Classes/Methods**: _None_
+
+
+
+### SpiffWorkflow.bpmn.serializer.helpers.spec.EventDefinitionConverter
+
+Abstract helper class for converting BPMN event definitions.
+
+
+
+
+
+**Related Classes/Methods**: _None_
+
+
+
+### SpiffWorkflow.bpmn.serializer.default.task_spec.BpmnTaskSpecConverter
+
+Concrete implementation of TaskSpecConverter for standard BPMN tasks.
+
+
+
+
+
+**Related Classes/Methods**:
+
+
+
+- <a href="https://github.com/recursionpharma/SpiffWorkflow/blob/main/SpiffWorkflow/bpmn/serializer/helpers/spec.py#L116-L226" target="_blank" rel="noopener noreferrer">`SpiffWorkflow.bpmn.serializer.helpers.spec.TaskSpecConverter` (116:226)</a>
+
+
+
+
+
+### SpiffWorkflow.bpmn.serializer.migration.version_migration.VersionMigration
+
+Component for managing and applying migration rules to workflow data.
+
+
+
+
+
+**Related Classes/Methods**: _None_
+
+
+
+### SpiffWorkflow.camunda.serializer.task_spec.UserTaskConverter
+
+Specialized converter for Camunda-specific extensions for user tasks.
+
+
+
+
+
+**Related Classes/Methods**:
+
+
+
+- <a href="https://github.com/recursionpharma/SpiffWorkflow/blob/main/SpiffWorkflow/bpmn/serializer/default/task_spec.py#L56-L87" target="_blank" rel="noopener noreferrer">`SpiffWorkflow.bpmn.serializer.default.task_spec.BpmnTaskSpecConverter` (56:87)</a>
+
+
+
+
+
+### SpiffWorkflow.bpmn.serializer.default.event_definition.ErrorEscalationEventDefinitionConverter
+
+Concrete implementation of EventDefinitionConverter for error escalation events.
+
+
+
+
+
+**Related Classes/Methods**:
+
+
+
+- <a href="https://github.com/recursionpharma/SpiffWorkflow/blob/main/SpiffWorkflow/bpmn/serializer/helpers/spec.py#L58-L113" target="_blank" rel="noopener noreferrer">`SpiffWorkflow.bpmn.serializer.helpers.spec.EventDefinitionConverter` (58:113)</a>
+
+
+
+
+
+
+
+
+
+### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq)
diff --git a/.codeboarding/Framework_Utilities.md b/.codeboarding/Framework_Utilities.md
@@ -0,0 +1,123 @@
+```mermaid
+
+graph LR
+
+    Framework_Utilities["Framework & Utilities"]
+
+    Eventing_System["Eventing System"]
+
+    General_Utilities["General Utilities"]
+
+    Custom_Exception_Hierarchy["Custom Exception Hierarchy"]
+
+    Framework_Utilities -- "provides core services to" --> Workflow_Engine
+
+    Framework_Utilities -- "provides core services to" --> BPMN_Parser
+
+    Framework_Utilities -- "provides core services to" --> DMN_Parser
+
+    Framework_Utilities -- "provides core services to" --> BPMN_Task_Specifications
+
+    Framework_Utilities -- "provides core services to" --> Serialization_Deserialization
+
+    Framework_Utilities -- "provides core services to" --> Scripting_Engine
+
+    Framework_Utilities -- "provides core services to" --> Camunda_Integration
+
+    Framework_Utilities -- "provides core services to" --> SpiffWorkflow_Extensions
+
+    click Framework_Utilities href "https://github.com/recursionpharma/SpiffWorkflow/blob/main/.codeboarding//Framework_Utilities.md" "Details"
+
+```
+
+
+
+[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%[email protected]?style=flat-square)](mailto:[email protected])
+
+
+
+## Details
+
+
+
+The `Framework & Utilities` component serves as the foundational layer for the SpiffWorkflow engine, providing essential cross-cutting concerns that enable modularity, robust error handling, and inter-component communication. It is fundamental because it encapsulates common functionalities and architectural patterns (like Event-Driven Architecture) that would otherwise be duplicated across various parts of the system, leading to a more maintainable and extensible codebase.
+
+
+
+### Framework & Utilities [[Expand]](./Framework_Utilities.md)
+
+A foundational layer providing general-purpose utility functions, a robust internal eventing mechanism for inter-component communication, and a hierarchy of custom exceptions for robust error handling across the entire SpiffWorkflow engine.
+
+
+
+
+
+**Related Classes/Methods**: _None_
+
+
+
+### Eventing System
+
+Implements a publish-subscribe mechanism, allowing various components within the workflow engine to communicate and react to state changes or actions without direct coupling. This adheres to the Event-Driven Architecture pattern, promoting loose coupling and extensibility.
+
+
+
+
+
+**Related Classes/Methods**:
+
+
+
+- <a href="https://github.com/recursionpharma/SpiffWorkflow/blob/main/SpiffWorkflow/util/event.py#L31-L244" target="_blank" rel="noopener noreferrer">`SpiffWorkflow.util.event.Event` (31:244)</a>
+
+
+
+
+
+### General Utilities
+
+Provides a collection of reusable helper functions and classes for common, non-domain-specific operations. This includes functionalities like deep merging dictionaries, filtering tasks based on various criteria, and managing weak references to callable objects, which are broadly applicable across the engine.
+
+
+
+
+
+**Related Classes/Methods**:
+
+
+
+- <a href="https://github.com/recursionpharma/SpiffWorkflow/blob/main/SpiffWorkflow/util/deep_merge.py" target="_blank" rel="noopener noreferrer">`SpiffWorkflow.util.deep_merge.deep_merge`</a>
+
+- <a href="https://github.com/recursionpharma/SpiffWorkflow/blob/main/SpiffWorkflow/util/task.py#L127-L175" target="_blank" rel="noopener noreferrer">`SpiffWorkflow.util.task.TaskFilter` (127:175)</a>
+
+- <a href="https://github.com/recursionpharma/SpiffWorkflow/blob/main/SpiffWorkflow/util/weakmethod.py#L40-L88" target="_blank" rel="noopener noreferrer">`SpiffWorkflow.util.weakmethod.WeakMethod` (40:88)</a>
+
+
+
+
+
+### Custom Exception Hierarchy
+
+Defines a structured and extensible set of custom exceptions that provide specific error types for various operational and business logic failures within the SpiffWorkflow engine. This facilitates precise error identification, graceful degradation, and easier debugging.
+
+
+
+
+
+**Related Classes/Methods**:
+
+
+
+- <a href="https://github.com/recursionpharma/SpiffWorkflow/blob/main/SpiffWorkflow/exceptions.py#L19-L33" target="_blank" rel="noopener noreferrer">`SpiffWorkflow.exceptions.SpiffWorkflowException` (19:33)</a>
+
+- <a href="https://github.com/recursionpharma/SpiffWorkflow/blob/main/SpiffWorkflow/exceptions.py#L36-L52" target="_blank" rel="noopener noreferrer">`SpiffWorkflow.exceptions.WorkflowException` (36:52)</a>
+
+
+
+
+
+
+
+
+
+### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq)