Embeddable Architecture - Critical Clarification

Resolving the confusion between .embeddable.ts files, widgets, and MongoDB storage

Embeddable Architecture - Critical Clarification

🚨 The Problem You Identified

You're absolutely right to question this! Looking at the codebase, we have THREE OVERLAPPING SYSTEMS:

.embeddable.ts files (17 files in libs-ui-core/, libs-ui/, libs-ux/)
- Define UiComponentConfig with inputs, outputs, and variants
- Hardcoded in source code
- Example: card.embeddable.ts has 4 variants hardcoded
Widget Builder (MongoDB storage)
- Creates widgets with variants dynamically
- Stores in space_widgets collection
- Variants are user-created
Embeddable Registry (WidgetsEmbeddableRegistryService)
- Single source of truth for UI atoms
- Loads from BOTH built-in .embeddable.ts AND MongoDB widgets

The Confusion: Variants exist in TWO places, creating ambiguity about the source of truth.

📊 Current Architecture (What Actually Exists)

┌─────────────────────────────────────────────────────────────────┐
│                    EMBEDDABLE REGISTRY                          │
│            (Single Source of Truth - Runtime)                   │
└───────────────────┬─────────────────────────────────────────────┘
                    │
        ┌───────────┴───────────┐
        │                       │
┌───────▼────────┐      ┌──────▼──────────┐
│  BUILT-IN      │      │  USER-CREATED   │
│  (Hardcoded)   │      │  (MongoDB)      │
├────────────────┤      ├─────────────────┤
│ Source: NX libs│      │ Source: DB      │
│ 17 .embeddable │      │ Dynamic         │
│ Has variants   │      │ Has variants    │
│ Static         │      │ User-defined    │
└────────────────┘      └─────────────────┘

Example: Card Component

Built-in (card.embeddable.ts):

export const CARD_EMBEDDABLE: UiComponentConfig = {
  id: 'ux-card',
  name: 'UX Card',
  component: UxCardComponent,
  variants: [
    { id: 'default-card', name: 'Default Card', inputOverrides: {...} },
    { id: 'elevated-card', name: 'Elevated Card', inputOverrides: {...} },
    { id: 'outlined-card', name: 'Outlined Card', inputOverrides: {...} },
    { id: 'full-card', name: 'Full Featured Card', inputOverrides: {...} }
  ]
};

User-created (MongoDB):

{
  "id": "widget_123",
  "name": "My Custom Card",
  "type": "card",
  "variants": [
    { "id": "variant_456", "name": "Dark Card", "properties": {...} },
    { "id": "variant_789", "name": "Light Card", "properties": {...} }
  ]
}

Problem: Two separate variant systems with no clear relationship!

🎯 The Solution (95% Confidence)

Principle: Two-Tier System

TIER 1: Built-in Embeddables (Foundation)
  ↓ (provides)
TIER 2: User Widgets (Extensions)

Architecture Should Be:

┌─────────────────────────────────────────────────────────────────┐
│                    TIER 1: BUILT-IN EMBEDDABLES                 │
│              (Foundation - Ships with Platform)                 │
├─────────────────────────────────────────────────────────────────┤
│ • Defined in .embeddable.ts files                               │
│ • Provide DEFAULT variants as starting points                   │
│ • Immutable, versioned with platform releases                   │
│ • Examples: UX Card (4 defaults), Button (6 defaults)           │
│ • Purpose: Professional, polished, ready-to-use components      │
└─────────────────────────────────────────────────────────────────┘
                              │
                    (user extends)
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    TIER 2: USER WIDGETS                         │
│              (Extensions - Created by Users)                    │
├─────────────────────────────────────────────────────────────────┤
│ • Created via Widget Builder                                    │
│ • Stored in MongoDB (space_widgets collection)                  │
│ • Can REFERENCE built-in embeddables as base                    │
│ • User-created variants extend/override defaults                │
│ • Examples: "My Brand Button", "Custom Pricing Card"            │
│ • Purpose: Custom, brand-specific, project-specific components  │
└─────────────────────────────────────────────────────────────────┘

🔧 Implementation Strategy

1. Keep `.embeddable.ts` Files As-Is ✅

Purpose: Professional component library (like Material UI, Ant Design)

Characteristics:

✅ Hardcoded in source code
✅ Variants are "starter presets"
✅ Immutable (change via code release)
✅ Always available (no database dependency)
✅ Professional quality (vetted by platform team)

Example Use Case:

// User starts with built-in "Elevated Card" variant
// Then customizes it in Widget Builder
// Saves as "My Brand Card" in MongoDB

2. Clarify MongoDB Widgets ✅

Purpose: User-created extensions

Characteristics:

✅ Created via Widget Builder
✅ Stored in MongoDB
✅ Can reference built-in embeddable as baseEmbeddableId
✅ Variants are user-created customizations
✅ Dynamic, editable, deletable

Data Model (MongoDB):

interface UserWidget {
  id: string;
  name: string;
  type: string;
  
  // Reference to built-in embeddable (optional)
  baseEmbeddableId?: string; // e.g., 'ux-card'
  
  // User's customizations
  propertyConfig: {
    groups: PropertyGroup[];
    values: Record<string, unknown>;
  };
  
  // User's variants (extend/override built-in)
  variants: Array<{
    id: string;
    name: string;
    description: string;
    properties: Record<string, unknown>;
    baseVariantId?: string; // Reference to built-in variant (optional)
  }>;
  
  // Metadata
  spaceId: string;
  scope: 'private' | 'public';
  createdBy: string;
  createdAt: Date;
}

3. Registry Merging Strategy ✅

On App Load:

// 1. Load built-in embeddables (static)
await uiEmbeddableRegistrar.initialize();
// Result: 17 built-in embeddables with default variants

// 2. Load user widgets from MongoDB (dynamic)
await widgetFlashSync.initialize(spaceId);
// Result: User's custom widgets

// 3. Merge in Registry
const allEmbeddables = [
  ...builtInEmbeddables,  // Source: 'builtin'
  ...userWidgets          // Source: 'user-created'
];

In Widget Builder:

// Show both tiers
const templates = [
  { group: 'Built-in', items: builtInEmbeddables },
  { group: 'My Widgets', items: userWidgets }
];

🎨 Variant Inheritance Model

Scenario: User Customizes Built-in Card

Step 1: User selects "Elevated Card" (built-in variant)

// Built-in definition
{
  id: 'elevated-card',
  name: 'Elevated Card',
  inputOverrides: {
    variant: 'elevated',
    size: 'md'
  }
}

Step 2: User customizes in Widget Builder

Changes shadow to 0 8px 24px
Changes border radius to 16px
Adds brand color

Step 3: User saves as "My Brand Card"

{
  "id": "widget_user_123",
  "name": "My Brand Card",
  "type": "card",
  "baseEmbeddableId": "ux-card",
  "variants": [
    {
      "id": "variant_456",
      "name": "Brand Elevated",
      "baseVariantId": "elevated-card",
      "properties": {
        "variant": "elevated",
        "size": "md",
        "boxShadow": "0 8px 24px rgba(59, 130, 246, 0.3)",
        "borderRadius": 16,
        "backgroundColor": "#3b82f6"
      }
    }
  ]
}

Result: User widget extends built-in, creating brand-specific version.

📋 Recommended Changes (Immediate)

Change 1: Add `baseEmbeddableId` to MongoDB Schema ✅

File: apis/backend-api/src/app/widgets/dto/create-widget.dto.ts

export class CreateWidgetDto {
  name: string;
  type: string;
  category: string;
  
  // NEW: Reference to built-in embeddable
  baseEmbeddableId?: string;
  
  propertyConfig: {...};
  variants: WidgetVariantDto[];
}

Change 2: Add `baseVariantId` to Variant Schema ✅

File: apis/backend-api/src/app/widgets/dto/create-variant.dto.ts

export class CreateVariantDto {
  name: string;
  description?: string;
  properties: Record<string, unknown>;
  
  // NEW: Reference to built-in variant
  baseVariantId?: string;
  
  preview?: string;
}

Change 3: Update Widget Builder UI ✅

File: libs/libs-widgets/widget-builder/src/lib/components/widget-builder-workspace/widget-builder-workspace.component.ts

Add "Start from Template" tab:

<div class="template-selector">
  <h3>Start from Built-in</h3>
  @for (embeddable of builtInEmbeddables(); track embeddable.id) {
    <div class="template-card" (click)="selectBuiltIn(embeddable)">
      <div class="icon">{{ embeddable.icon }}</div>
      <div class="name">{{ embeddable.name }}</div>
      <div class="variants">{{ embeddable.variants?.length }} variants</div>
    </div>
  }
</div>

Change 4: Clarify Documentation ✅

Update: docs/english/GoGrab-Space/modules/embeddable-components-guide.md

Add section:

## Two Types of Embeddables

### 1. Built-in Embeddables (Platform Foundation)
- Defined in `.embeddable.ts` files
- Professional, polished components
- Default variants as starting points
- Immutable (change via platform release)
- Examples: UX Card, Panel, Menu, Button

### 2. User Widgets (Custom Extensions)
- Created via Widget Builder
- Stored in MongoDB
- Can reference built-in as base
- User-defined variants
- Examples: "My Brand Button", "Company Card"

🏆 Final Architecture (AI-Ready)

For AI Agents to Understand:

Q: What's an embeddable?

A: An Angular component with a well-defined contract (inputs/outputs)
Can be built-in (shipped with platform) OR user-created (MongoDB)

Q: What's a widget?

A: A user-created embeddable with editor metadata (property groups, variants)
Always stored in MongoDB
Can reference/extend built-in embeddables

Q: What are .embeddable.ts files?

A: Configuration for built-in components (Tier 1)
Provides professional defaults
Users extend these via Widget Builder

Q: Where do variants live?

A: Both places, but with different purposes:
- Built-in: Default presets (starting points)
- User widgets: Custom variants (extensions)

Q: Can I create a widget without a built-in base?

A: Yes! User can create from scratch via AI generation or manual composition.

Q: How do modules fit in?

A: Modules expose embeddables in their manifest. Those embeddables can be:
- References to built-in embeddables
- Module-specific embeddables (inside module NX lib)
- Wrappers around user widgets

🎯 Naming Convention (Final)

Term	Definition	Storage	Example
Component	Pure Angular component	NX library	`UxCardComponent`
Embeddable	Component + registration config	`.embeddable.ts`	`CARD_EMBEDDABLE`
Built-in Embeddable	Platform-shipped embeddable	NX library	All 17 in libs-ui
User Widget	User-created via builder	MongoDB	"My Brand Card"
Module Embeddable	Component exposed by module	Module manifest	`UserListWidget`
Widget Wrapper	Embeddable + editor features	Runtime	`CardWidgetComponent`

✅ Action Items (Immediate)

1. Update MongoDB Schema ✅

Add baseEmbeddableId to widget schema
Add baseVariantId to variant schema
This creates explicit inheritance tracking

2. Update Widget Builder UI ✅

Add "Start from Built-in" template selector
Show built-in variants as starting points
Clear visual distinction: Built-in vs Custom

3. Update Documentation ✅

Clarify two-tier system in all docs
Explain inheritance model
Provide AI training examples

4. Clean Up Terminology ✅

Use "Built-in Embeddable" not just "embeddable"
Use "User Widget" not just "widget"
Be explicit about tier in UI

🤖 AI Training Guidance

Generate New Widget from Built-in

User Prompt: "Create a dark mode version of the Elevated Card"

AI Flow:

Load CARD_EMBEDDABLE definition
Find elevated-card variant
Start with those inputOverrides
Apply dark mode properties
Save as new user widget with baseEmbeddableId: 'ux-card'

Result:

{
  "name": "Dark Elevated Card",
  "baseEmbeddableId": "ux-card",
  "variants": [{
    "name": "Dark Mode",
    "baseVariantId": "elevated-card",
    "properties": {
      "variant": "elevated",
      "size": "md",
      "backgroundColor": "#1f2937",
      "textColor": "#f9fafb",
      "boxShadow": "0 10px 25px rgba(139, 92, 246, 0.3)"
    }
  }]
}

Generate New Widget from Scratch

User Prompt: "Create a testimonial card with author photo and quote"

AI Flow:

No baseEmbeddableId (from scratch)
Generate component structure
Create property groups
Generate default variant
Save as new user widget

Result:

{
  "name": "Testimonial Card",
  "baseEmbeddableId": null,
  "propertyConfig": {
    "groups": [/* custom property groups */]
  },
  "variants": [/* generated variants */]
}

🎨 Variant Creation Workflow (Final)

For Built-in Embeddables

When: User wants professional, vetted components

Flow:

Browse built-in embeddables in Widget Builder
Select embeddable (e.g., "UX Card")
See 4 built-in variants
Click "Use as Template"
Customize in editor
Save as new user widget (with baseEmbeddableId)

For Custom Widgets

When: User needs unique, brand-specific components

Flow:

AI Generate OR Manual Compose
Define property groups
Create variants
Save to MongoDB
Use across pages

🚀 Benefits of This Architecture

For Users

✅ Professional components out-of-the-box (built-ins) ✅ Unlimited customization (user widgets) ✅ Clear inheritance (baseEmbeddableId + baseVariantId) ✅ Reusability (save once, use everywhere)

For AI

✅ Clear distinction between tiers ✅ Explicit inheritance for learning ✅ Default presets as training data ✅ Variant generation guidance

For Platform

✅ Version control for built-ins (via git) ✅ Multi-tenant isolation for user widgets (via MongoDB) ✅ Gradual rollout (add more built-ins over time) ✅ Extensibility (users can always go custom)

📐 Data Models (Final)

Built-in Embeddable (`.embeddable.ts`)

interface UiComponentConfig {
  id: string;                      // 'ux-card'
  name: string;                    // 'UX Card'
  component: Type<unknown>;        // UxCardComponent
  inputs: UiInputDefinition[];     // Contract
  outputs: UiOutputDefinition[];   // Contract
  variants: UiVariant[];           // DEFAULT presets
  category: string;
  icon: string;
  tags: string[];
}

User Widget (MongoDB)

interface UserWidget {
  id: string;                      // 'widget_123'
  name: string;                    // 'My Brand Card'
  type: string;                    // 'card'
  
  // Inheritance
  baseEmbeddableId?: string;       // 'ux-card' (if extends built-in)
  
  // Configuration
  propertyConfig: {
    groups: PropertyGroup[];       // Custom property organization
    values: Record<string, unknown>; // Current values
  };
  
  // Variants
  variants: Array<{
    id: string;                    // 'variant_456'
    name: string;                  // 'Dark Mode'
    baseVariantId?: string;        // 'elevated-card' (if extends built-in variant)
    properties: Record<string, unknown>;
  }>;
  
  // Metadata
  spaceId: string;
  scope: 'private' | 'public';
  createdBy: string;
  createdAt: Date;
  updatedAt: Date;
}

🔄 Migration Path (If Needed)

Current State: Mixed responsibilities

Target State: Clear two-tier system

Steps:

✅ Add baseEmbeddableId and baseVariantId to schema
✅ Update Widget Builder to show built-in templates
✅ Update docs to clarify two-tier system
⏳ (Optional) Migrate existing user widgets to reference built-ins

Timeline: Can be done incrementally, no breaking changes

💡 Key Insights

What You Were Right About

✅ "Things we're saving as .embeddable should be MongoDB-ready"

Partially correct: Built-ins provide TEMPLATES, users save to MongoDB

✅ "The issue would be actions, inputs, outputs, etc"

Correct: Built-ins define contract, user widgets customize values

✅ "Everything must be ready to create variants easily"

Correct: Both tiers support variants, but with different purposes

What's Actually Happening

Built-in embeddables (.embeddable.ts):

Professional component library
Default variants = starting points
Like Material UI or Ant Design

User widgets (MongoDB):

Custom extensions
User variants = brand-specific
Like Tailwind UI Pro (user customizations)

Together:

Built-ins provide foundation
Users extend/customize
Both registered in same runtime registry
Clear inheritance via baseEmbeddableId

🎯 Confidence Rating: 95%

Why 95% and not 100%?

Need to verify backend schema supports baseEmbeddableId
Need to implement template selector UI
Need to test variant inheritance end-to-end

What makes it 95%?

Architecture aligns with industry standards (Material UI model)
Clear separation of concerns
Extensibility without breaking existing code
AI-trainable with explicit inheritance

Last Updated: December 9, 2025 - Session 10.2 Status: Ready for implementation

Embeddable Architecture - Critical Clarification

🚨 The Problem You Identified

📊 Current Architecture (What Actually Exists)

Example: Card Component

🎯 The Solution (95% Confidence)

Principle: Two-Tier System

Architecture Should Be:

🔧 Implementation Strategy

1. Keep .embeddable.ts Files As-Is ✅

2. Clarify MongoDB Widgets ✅

3. Registry Merging Strategy ✅

🎨 Variant Inheritance Model

Scenario: User Customizes Built-in Card

📋 Recommended Changes (Immediate)

Change 1: Add baseEmbeddableId to MongoDB Schema ✅

Change 2: Add baseVariantId to Variant Schema ✅

Change 3: Update Widget Builder UI ✅

Change 4: Clarify Documentation ✅

🏆 Final Architecture (AI-Ready)

For AI Agents to Understand:

🎯 Naming Convention (Final)

✅ Action Items (Immediate)

1. Update MongoDB Schema ✅

2. Update Widget Builder UI ✅

3. Update Documentation ✅

4. Clean Up Terminology ✅

🤖 AI Training Guidance

Generate New Widget from Built-in

Generate New Widget from Scratch

🎨 Variant Creation Workflow (Final)

For Built-in Embeddables

For Custom Widgets

🚀 Benefits of This Architecture

For Users

For AI

For Platform

📐 Data Models (Final)

Built-in Embeddable (.embeddable.ts)

User Widget (MongoDB)

🔄 Migration Path (If Needed)

💡 Key Insights

What You Were Right About

What's Actually Happening

🎯 Confidence Rating: 95%

1. Keep `.embeddable.ts` Files As-Is ✅

Change 1: Add `baseEmbeddableId` to MongoDB Schema ✅

Change 2: Add `baseVariantId` to Variant Schema ✅

Built-in Embeddable (`.embeddable.ts`)