marketplaces/docs/architecture/foundation/adr/ADR-005-dynamic-page-section-widget-rendering.md

ADR-005: Dynamic Page, Section, and Widget Rendering

Status: Accepted Date: 2026-07-03

Context

Platform websites must be generated from configuration. Hardcoded page composition blocks tenant scalability.

Decision

Adopt dynamic rendering engine:

• A page definition contains ordered sections.
• A section contains ordered widgets.
• WidgetHost resolves widget type through registry.
• Registry-based resolution avoids renderer edits for every new widget.
• Hero, Carousel, Header, Footer, and other blocks are widgets/layout entries from configuration.

Consequences

Positive:

• New tenant pages created by configuration.
• Supports Builder-driven composition.

Negative:

• Requires robust schema validation.
• Requires widget compatibility and versioning discipline.

Compliance Requirements

• Page templates must not hardcode specific widget combinations.
• Widget rendering must be data-driven from configuration contracts.