Embeddables, Widgets, and Modules — How It All Fits Together

The end state (big picture)

• Single registry, clear kinds: Every embeddable is registered once with a kind (widget, layout-module, feature-module) so each surface shows only what it can actually render.
• Shared web responsiveness: A common ResponsiveDefinition is used by both widgets and web-facing module layouts. Modules keep their multi-platform metadata (Flutter/React), but on web they speak the same responsive language as widgets.
• Widgets remain embeddable-first: Widgets are built in the widget-builder (manual or AI) with property groups, values, accessibility, responsive breakpoints, and an embeddableId. They can be dropped into pages or into module regions.
• Modules remain feature/layout containers: Modules (built with modularity-lib) own regions, actions, state, routes, permissions, and multi-platform metadata. For web, they expose webResponsive and can host widgets in their regions via an adapter.
• AI everywhere, but validated: Both builders (widgets and modules) use backend property templates, responsive contracts, and validation loops so AI outputs are complete, accessible, and reusable.

What the steps achieve

1. Classification & filtering across the monorepo

   • Embeddables carry kind. Palettes (gograb-space) and backend-api responses filter so widget-only views don’t show module layouts unless they’re adapted. Badges make it obvious what you’re dragging.

2. Shared web responsive contract

   • ResponsiveDefinition in core models defines size/layout/visibility per breakpoint.
   • Widgets already use responsive props; now they align to the same contract.
   • Modules add webResponsive to their manifest for the web runtime, while keeping Flutter/React metadata intact.

3. Layout adapter in editor-web

   • Module regions become drop zones. You can place widgets into module layouts in the editor. Region selections and responsive overrides persist back to the module context.
   • Only modules that provide webResponsive + adapter metadata show up as layouts in the widget palette.

4. Widget-builder hardening

   • Every AI/manual widget export includes: propertyGroups/values, responsive base-sm-md-lg, embeddableId, accessibility (aria/role), and a manifest snippet describing how modules can embed it.
   • Backend property templates (pricing, CTA, colors, etc.) are injected automatically; missing pieces trigger AI retry.

5. Modularity-lib AI & validation

   • Module AI generation checks models/state/actions/routes/permissions/embeddables/responsive/variants. Regions must host widgets or declare placeholders/allowed types. Exports are blocked until valid.
   • Reuse-first: suggest existing widgets before creating new ones to reduce duplication and keep performance tight.

6. Backend property system integration

   • Property templates from backend-api drive both widget and module AI, so pricing/CTA/color/accessibility props are consistent and tracked (usage increments, guarantees).

7. Tests & gates

   • CI checks: classification/filtering, adapter smoke, responsive snapshots (e.g., Pricing + Two Column Equal), accessibility, and monorepo filtering (backend-api + gograb-space).

How the architecture will look

• Core models: own ResponsiveDefinition, widget and module contracts. One place for responsive and type definitions.
• Registry layer: one embeddable registry with kind on entries; bridges add kind; backend-api surfaces kind; gograb-space palettes filter by kind.
• Widgets: generated with full metadata (props, responsive, a11y, manifest snippet) and embeddableId; consumable directly or inside modules.
• Modules: NX libraries with manifests including webResponsive (for web) plus multi-platform metadata. Regions host widgets via the adapter.
• Editors/builders:
  • Widget-builder: generates embeddable-ready, responsive, accessible widgets using backend property templates and validation loops.
  • Modularity-lib: builds modules with validated contracts and can pull widgets from the registry into regions.
• AI layer: Both builders use shared prompts + validation to ensure completeness; failed validations trigger retries.
• Runtime surfaces:
  • Editor-web shows widgets by default; can show layout modules that are adapted.
  • Modular-universe uses modules (and their embeddables) natively; can host widgets via regions.
  • Backend-api consistently marks and serves embeddables by kind and metadata.

Why this is structurally sound

• Contracts live in core (no ad-hoc bridges), manifests remain the source of truth for modules, and widgets keep their embeddable-first design.
• Kind filtering prevents incompatible items from leaking into the wrong surfaces.
• Shared responsiveness removes divergence between widgets and web layouts while keeping other platforms untouched.
• AI outputs are validated against the same contracts and property templates, ensuring reuse, consistency, and quality.
• Tests/CI enforce classification, responsiveness, accessibility, and filtering across the monorepo.

Performance & packaging considerations

• One registry, small payloads: list responses stay thin (id/name/kind/icon/tags) and are always filtered (by kind/category/search). Rich metadata is fetched on demand.
• Platform-aware exposure: widget palettes default to kind=widget; layout modules are shown only when adapter + webResponsive exist; backend-api surfaces kind so clients can pre-filter.
• Tree-shake and lazy-load: modules remain NX libraries; apps import only what they use. Widgets and layouts can be lazy-loaded to keep builds lean.
• Caching and indexing: backend indexed by kind/category/tags; frontends cache recent slices. No “load everything” flows.