Architecture: Should SDK components be property-system-dependent (every co...

Documentation for Sessions

🏗️ Architecture: Should SDK components be property-system-dependent (every co...

Date: 2026-03-16
Time: 19:23:41 UTC
Session: gspace1-226.7
Agent: angular
Confidence: 93%
Status: ✅ Documented

📋 Decision Context

Question:

Should SDK components be property-system-dependent (every component uses UnifiedPropertyDefinition) or property-system-compatible (clean @Input APIs, widget layer bridges to properties)?

Task: S226.2: Platform Generation v2 architecture design

🎯 Decision Made

Chosen:

Property-system-COMPATIBLE, not dependent. SDK components have clean @Input() APIs. The widget wrapper layer maps PropertyDefinition configs to @Input values. Components know nothing about the property system.

Options Considered:

Property-system-dependent: every component uses UnifiedPropertyDefinition (initially proposed)
Property-system-compatible: clean @Input APIs with widget wrapper bridge (chosen)
No property system integration at all (too disconnected from page-builder/Vitto)

💭 Reasoning

Forcing the property system on every component is over-engineering. A developer writing doesn't need UnifiedPropertyDefinition. The property system matters for ONE use case: when a component lives on the page-builder canvas and needs a property panel editor. That's the widget wrapper's job. Three-layer architecture: Layer 1 (Platform SDK) = clean @Input APIs, standalone, testable. Layer 2 (Widget Wrappers) = thin adapter, maps property configs to inputs, adds canvas features. Layer 3 (Property System) = defines what properties exist, used by page-builder panel and Vitto AI context. EntityFieldConfig (simple flat config for generated code) and PropertyDefinition (full property system type with AI metadata) are intentionally separate types sharing a type enum. This prevents coupling SDK to the property system while allowing Vitto to work through either path.

📁 Files Involved

libs/core/ui-framework/src/lib/components/
libs/libs-widgets/widgets/src/lib/
libs/libs-foundational/core-properties/src/lib/unified/unified-property.types.ts
libs/libs-structural/page-builder/src/lib/components/properties-panel/properties-panel.component.ts

🔗 Related

Decision ID: dev_1773689021849_vxcqdds
Session: 226
Workspace: gspace1

Auto-generated by MCP Smart Consolidation