Hybrid Module Integration Plan

Created: December 2, 2025
Status: Planning Phase
Priority: High

Executive Summary

This plan consolidates the gograb-modules architecture into the editor monorepo as the single source of truth. We will NOT maintain two separate monorepos. Instead, we will:

1. Adapt all internal tools to support the Module-First architecture
2. Update widget system to use embeddable components as the foundation
3. Connect everything to the backend-api for real data persistence
4. Enable both visual building AND custom functionality through modules

Current State Analysis

What We Have (Editor Monorepo)

What Needs Updates

Phase 1: Modularity-Lib Upgrade (URGENT)

Current Issues

• Creates visual modules but doesn't generate proper ModuleManifest
• No support for embeddable components
• No public actions definition
• Not connected to module registry

Target State

• Generate complete ModuleManifest from visual builder
• Support defining embeddable components
• Support defining public actions
• Auto-register with ModuleRegistryService

Implementation Tasks

1.1 Update Module Builder Interface

// Current: Visual-only module
interface VisualModule {
  id: string;
  name: string;
  components: Component[];
}

// Target: Full module manifest
interface BuilderModuleDefinition {
  // Core manifest fields
  id: string;
  version: string;
  name: string;
  description: string;
  category: string;
  author?: string;
  tags?: string[];
  
  // Navigation
  navigation?: {
    menuItems: MenuItem[];
  };
  
  // Routes (if module has pages)
  routes?: ModuleRoute[];
  basePath?: string;
  
  // Embeddable components
  embeddableComponents: EmbeddableDefinition[];
  
  // Public actions
  publicActions?: ActionDefinition[];
  
  // Permissions
  permissions?: PermissionDefinition[];
  
  // Configuration schema (for module settings)
  configuration?: ConfigurationSchema;
}

1.2 Create Embeddable Component Builder

New component in modularity-lib:

// libs/libs-structural/modularity-lib/src/lib/components/embeddable-builder/
// Files:
// - embeddable-builder.component.ts
// - embeddable-builder.component.html
// - embeddable-builder.component.scss

// Features:
// - Visual input definition (drag-drop parameter builder)
// - Output event definition
// - Permission assignment
// - Category selection
// - Preview thumbnail upload

1.3 Create Action Builder

New component for defining public actions:

// libs/libs-structural/modularity-lib/src/lib/components/action-builder/
// Features:
// - Action name and description
// - Parameter definition (reuse parameter builder)
// - Return type definition
// - Permission requirements
// - Flow attachment (link to Singularity flow)

1.4 Module Export Service

Service to export visual module as proper manifest:

// libs/libs-structural/modularity-lib/src/lib/services/module-export.service.ts

@Injectable({ providedIn: 'root' })
export class ModuleExportService {
  exportToManifest(visual: BuilderModuleDefinition): ModuleManifest { }
  exportToTypeScript(visual: BuilderModuleDefinition): string { }
  registerModule(manifest: ModuleManifest): Observable<void> { }
}

1.5 Files to Modify

Phase 2: Singularity-Lib Integration

Current Issues

• Flow engine works independently
• Actions not connected to module registry
• No backend sync for flows

Target State

• Flows can call module public actions
• Flows can be exported as module actions
• Backend-api integration for flow storage

Implementation Tasks

2.1 Action Integration

Connect Singularity actions to ActionRegistryService:

// libs/libs-structural/singularity-lib/src/lib/services/action-executor.service.ts

// Instead of local action execution:
executeAction(actionId: string, params: Record<string, unknown>) {
  // First check module actions
  if (this.actionRegistry.hasAction(actionId)) {
    return this.actionRegistry.execute(actionId, params);
  }
  // Fallback to local actions
  return this.executeLocalAction(actionId, params);
}

2.2 Flow Backend Sync

// libs/libs-structural/singularity-lib/src/lib/services/flow-backend.service.ts

@Injectable({ providedIn: 'root' })
export class FlowBackendService {
  private http = inject(HttpClient);
  private storage = inject(GgStorage);
  
  // Sync flows with backend-api
  syncFlows(): Observable<void> { }
  
  // Save flow to backend
  saveFlow(flow: Flow): Observable<Flow> { }
  
  // Load flows from backend
  loadFlows(): Observable<Flow[]> { }
}

2.3 Module Action Export

Allow exporting a flow as a module public action:

// libs/libs-structural/singularity-lib/src/lib/services/flow-to-action.service.ts

exportFlowAsAction(flowId: string, moduleId: string): ModulePublicAction {
  const flow = this.flowService.getFlow(flowId);
  return {
    id: `${moduleId}:${flow.name}`,
    name: flow.name,
    description: flow.description,
    execute: (params) => this.flowExecutor.execute(flowId, params),
    parameters: this.extractParameters(flow),
  };
}

Phase 3: Modular Universe Integration

Current Issues

• Module installation is manual
• No module marketplace/store UI
• No module configuration workflow

Target State

• Module store for browsing/installing modules
• One-click module installation
• Configuration UI for installed modules
• Module routes appear in navigation

Implementation Tasks

3.1 Update Module Store Component

Already created at: singularity-lib/src/lib/components/module-store/module-store.component.ts

Needs:

• Backend sync for module catalog
• Installation progress tracking
• Dependency resolution UI
• Uninstall workflow

3.2 Module Installation Service

// libs/libs-structural/modular-universe/src/lib/services/module-installation.service.ts

@Injectable({ providedIn: 'root' })
export class ModuleInstallationService {
  install(moduleId: string, config?: Record<string, unknown>): Observable<void> {
    // 1. Fetch module definition from backend
    // 2. Resolve dependencies
    // 3. Register with ModuleRegistryService
    // 4. Register routes with ModuleRouteIntegrationService
    // 5. Sync embeddables with WidgetRegistryService
    // 6. Persist installation to storage
  }
  
  uninstall(moduleId: string): Observable<void> { }
  
  configure(moduleId: string, config: Record<string, unknown>): Observable<void> { }
}

3.3 Universe Module Manager

New component for managing modules per universe:

// libs/libs-structural/modular-universe/src/lib/components/universe-module-manager/
// Features:
// - List installed modules for universe
// - Enable/disable modules
// - Configure module settings
// - View module routes/embeddables

Phase 4: Widget System Update

Current Issues

• Widgets are standalone, not module-based
• No embeddable component support
• Manual widget registration

Target State

• All widgets exposed as embeddable components
• Auto-discovery from module registry
• Widget builder generates module manifests

Implementation Tasks

4.1 Convert Existing Widgets to Embeddables

For each widget in libs/libs-widgets/widgets/src/lib/components/:

// Before: Standalone widget
@Component({ ... })
export class ButtonWidgetComponent { }

// After: Module-registered embeddable
// In widgets-manager.module.ts:
embeddableComponents: [
  {
    id: 'widgets:button',
    componentType: ButtonWidgetComponent,
    displayName: 'Button',
    category: 'input',
    inputs: [
      { name: 'label', type: 'string', required: true },
      { name: 'variant', type: 'enum', options: ['primary', 'secondary'] },
    ],
    outputs: [
      { name: 'clicked', type: 'void' },
    ],
  },
  // ... more widgets
]

4.2 Widget Builder Manifest Generation

Update widget builder to generate module manifest:

// libs/libs-widgets/widget-builder/src/lib/services/widget-manifest.service.ts

@Injectable({ providedIn: 'root' })
export class WidgetManifestService {
  generateManifest(widget: WidgetDefinition): ModuleManifest {
    return {
      id: `custom-widget:${widget.id}`,
      name: widget.name,
      version: '1.0.0',
      embeddableComponents: [{
        id: widget.id,
        componentType: widget.component,
        displayName: widget.name,
        category: 'widget',
        inputs: this.convertProperties(widget.properties),
      }],
    };
  }
}

4.3 Widget Routes Update

Update /space/:slug/widgets route to show both:

• Built-in widgets
• Module-provided embeddables

// apps/gograb-space/src/app/pages/widgets/widgets.routes.ts

// Show unified widget palette:
// 1. Built-in widgets from WidgetRegistryService
// 2. Module embeddables from ModuleWidgetBridgeService
// 3. Custom widgets from widget-builder

Phase 5: Backend-API Integration

Current Issues

• Some services still use local storage only
• No real-time sync between users
• Module catalog not persisted

Target State

• All modules stored in backend
• Real-time sync via WebSocket
• Module marketplace with catalog API

Implementation Tasks

5.1 Module Catalog API

// apis/backend-api/src/app/modules/catalog/
// - catalog.controller.ts
// - catalog.service.ts
// - catalog.schema.ts

// Endpoints:
// GET /api/modules - List available modules
// GET /api/modules/:id - Get module details
// POST /api/modules - Publish new module
// PUT /api/modules/:id - Update module
// DELETE /api/modules/:id - Unpublish module

5.2 Universe Module Installation API

// apis/backend-api/src/app/universes/modules/
// - universe-modules.controller.ts
// - universe-modules.service.ts

// Endpoints:
// GET /api/universes/:id/modules - List installed modules
// POST /api/universes/:id/modules/:moduleId - Install module
// DELETE /api/universes/:id/modules/:moduleId - Uninstall
// PUT /api/universes/:id/modules/:moduleId/config - Configure

Phase 6: Testing & Documentation

Test Coverage

Documentation Updates

Timeline

Total Estimated Time: 8 weeks

Success Criteria

1. ✅ Visual module builder generates proper ModuleManifest
2. ✅ Modules can define embeddable components visually
3. ✅ Modules can define public actions visually
4. ✅ Singularity flows can call module actions
5. ✅ Modules can be installed per-universe
6. ✅ All widgets available as embeddables
7. ✅ Backend persistence for modules and flows
8. ✅ No separate monorepo required

Migration Path for gograb-modules

The gograb-modules repository will eventually be archived. Key patterns to port:

Notes

1. Single Repository: All work happens in the editor monorepo
2. Backward Compatibility: Existing widgets continue to work
3. Progressive Enhancement: New features don't break existing functionality
4. Module-First: New features should be built as modules first

Related Documents

• Comparison and Analysis
• Hybrid Architecture Summary
• Test Results Summary