Add trait dependency documentation and architecture diagrams

Co-authored-by: jbtronics <5410681+jbtronics@users.noreply.github.com>

Author: Copilot

ENTITY_REFACTORING.md

@@ -4,6 +4,48 @@
 
 This refactoring decomposes the deep entity inheritance hierarchy into a more flexible trait-based architecture. This provides better code reusability, composition, and maintainability.
 
+## Architecture Diagram
+
+### Before (Deep Inheritance):
+```
+AbstractDBElement (ID logic)
+    └─ AbstractNamedDBElement (name + timestamps)
+        └─ AttachmentContainingDBElement (attachments)
+            └─ AbstractStructuralDBElement (tree/hierarchy + parameters)
+                ├─ AbstractPartsContainingDBElement
+                │   ├─ Category
+                │   ├─ Footprint
+                │   ├─ StorageLocation
+                │   └─ AbstractCompany (company fields)
+                │       ├─ Manufacturer
+                │       └─ Supplier
+```
+
+### After (Trait Composition):
+```
+Traits:                          Interfaces:
+- DBElementTrait                 - DBElementInterface
+- NamedElementTrait              - NamedElementInterface
+- TimestampTrait                 - TimeStampableInterface
+- AttachmentsTrait               - HasAttachmentsInterface
+- MasterAttachmentTrait          - HasMasterAttachmentInterface
+- StructuralElementTrait         - StructuralElementInterface
+- ParametersTrait                - HasParametersInterface
+- CompanyTrait                   - CompanyInterface
+
+Class Hierarchy (now uses traits):
+AbstractDBElement (uses DBElementTrait, implements DBElementInterface)
+    └─ AbstractNamedDBElement (uses NamedElementTrait + TimestampTrait)
+        └─ AttachmentContainingDBElement (uses AttachmentsTrait + MasterAttachmentTrait)
+            └─ AbstractStructuralDBElement (uses StructuralElementTrait + ParametersTrait)
+                ├─ AbstractPartsContainingDBElement
+                │   ├─ Category (gets all traits via inheritance)
+                │   ├─ Footprint (gets all traits via inheritance)
+                │   └─ AbstractCompany (uses CompanyTrait)
+                │       ├─ Manufacturer
+                │       └─ Supplier
+```
+
 ## Changes Made
 
 ### New Traits Created

src/Entity/Base/AttachmentsTrait.php

@@ -29,6 +29,11 @@
 
 /**
  * Trait providing attachments functionality.
+ *
+ * Requirements:
+ * - Class using this trait should have $id property (e.g., via DBElementTrait)
+ * - Class may optionally have $master_picture_attachment property (via MasterAttachmentTrait)
+ * - Class should implement HasAttachmentsInterface
  */
 trait AttachmentsTrait
 {

src/Entity/Base/StructuralElementTrait.php

@@ -34,6 +34,11 @@
 
 /**
  * Trait for structural/hierarchical elements forming a tree structure.
+ *
+ * Requirements:
+ * - Class using this trait must have getName() method (e.g., via NamedElementTrait)
+ * - Class using this trait must have getID() method (e.g., via DBElementTrait)
+ * - Class should implement StructuralElementInterface
  */
 trait StructuralElementTrait
 {