Foundation Libraries Review - November 2025

Comprehensive audit of singularity, editor-web, and modularity libraries

🔍 Foundation Libraries Review - November 2025

Last Updated: November 14, 2025
Status: 🎯 FOUNDATION AUDIT COMPLETE
Purpose: Understand current capabilities and integration paths

🎯 EXECUTIVE SUMMARY

This document audits the three critical foundational libraries that support the modular-universe builder:

singularity-lib - Logic blocks and flows (smallest reusable units)
editor-web-lib - Visual page editor (content creation)
modularity-lib - Module creation and packaging (module factory)

Key Finding: All three libraries are operational but need better integration with the universal module system and modular-universe builder.

⚡ SINGULARITY-LIB REVIEW

Location: libs/libs-structural/singularity-lib/
Purpose: Create reusable logic blocks and flows that power functionality across the platform

📊 Current State

Status: ✅ OPERATIONAL - Well-structured, needs integration enhancement

Core Components:

singularity-lib/
├── components/
│   ├── logic-builder/              # Visual logic block builder
│   │   ├── logic-block.component   # Individual block rendering
│   │   ├── logic-canvas.component  # Canvas for connecting blocks
│   │   └── logic-sidebar.component # Block palette
│   ├── flow-composer/              # Flow composition tool
│   ├── singularity-dashboard/      # Main dashboard
│   └── ai-assistance/              # AI-powered generation
│
├── services/
│   ├── logic-execution-engine      # Execute logic blocks/flows
│   ├── flow-composition            # Compose blocks into flows
│   ├── flow-attachment             # Attach flows to modules
│   ├── logic-ai                    # AI code generation
│   └── widget-flow-executor        # Execute flows from widgets
│
├── templates/
│   ├── api-block-templates         # HTTP, REST API blocks
│   ├── business-logic-blocks       # Business rules
│   ├── database-block-templates    # DB operations
│   ├── flow-control-blocks         # If/loop/switch
│   ├── math-block-templates        # Math operations
│   ├── platform-block-templates    # Platform-specific
│   ├── string-block-templates      # String manipulation
│   ├── trigger-block-templates     # Event triggers
│   └── ui-control-blocks           # UI interactions
│
└── state/
    └── singularity.state.ts        # Flash-state management

✅ Strengths

Rich Block Library - 100+ pre-built logic blocks
Visual Canvas - Drag-and-drop flow composition
Execution Engine - Real-time block execution
AI Integration - AI-powered flow generation
Storage Integration - Uses flash-persistence
Widget Integration - Can attach flows to widgets

⚠️ Integration Gaps

Module Attachment - Flow attachment to universal modules needs enhancement
Storage Schema - Flow storage not fully aligned with universe-scoped data
Module Browser - Flows not discoverable in module browser
Cross-Tool Navigation - Routes commented out due to circular dependency

🎯 Required Enhancements

1. Universe-Scoped Storage

Current:

// Generic storage
storage.put('flow:123', flowData);

Needed:

// Universe-scoped storage
storage.putInUniverse(spaceId, universeId, 'flow:123', flowData);

// Flow as module
const flowModule: UniversalModule = {
  id: 'flow-123',
  name: 'Order Processing Flow',
  type: 'flow',
  universeId: 'universe-456',
  config: {
    blocks: [...],
    connections: [...]
  }
};

2. Module Registry Integration

Needed:

// Register flows as installable modules
@ModuleDecorator({
  id: 'order-processing-flow',
  name: 'Order Processing Flow',
  type: 'flow',
  category: 'Business Logic',
  embeddableComponents: [],
  publicActions: ['execute', 'validate', 'test']
})
export class OrderProcessingFlowModule implements BrowserModuleContract {
  manifest: ModuleManifest = { /* ... */ };
  
  async execute(input: any): Promise<any> {
    // Execute flow
  }
}

3. Attachment API Enhancement

Current:

// Attach flow to widget
flowAttachmentService.attachFlowToWidget(widgetId, flowId);

Needed:

// Attach flow to universal module
flowAttachmentService.attachFlowToModule(
  moduleId: string,
  flowId: string,
  trigger: 'onInit' | 'onClick' | 'onChange' | 'onSubmit'
);

// Attach flow to section (in modular-universe)
flowAttachmentService.attachFlowToSection(
  sectionId: string,
  flowId: string,
  trigger: string
);

4. Cross-Tool Navigation

Proposed Routes:

// From modular-universe section config
→ /space/:spaceSlug/singularity/flows?context=section&id=section-123

// From module detail
→ /space/:spaceSlug/singularity/flows?context=module&id=module-456

// From widget config
→ /space/:spaceSlug/singularity/flows?context=widget&id=widget-789

📋 Action Items for Singularity

Implement universe-scoped storage for flows
Register flows as universal modules in ModuleRegistry
Enhance flow-attachment service for universal modules
Create flow-module wrapper for module browser
Add context-aware navigation from modular-universe
Update routes to support universe context

📝 EDITOR-WEB-LIB REVIEW

Location: libs/libs-structural/editor-web-lib/
Purpose: Visual page editor for creating beautiful content pages

📊 Current State

Status: ✅ OPERATIONAL - Powerful editor, needs module integration

Core Components:

editor-web-lib/
├── components/
│   ├── editor-main/              # Main editor orchestrator
│   ├── editor-canvas/            # Visual editing canvas
│   ├── editor-workspace/         # Full workspace with tools
│   ├── widget-library/           # Widget palette
│   ├── widget-builder/           # Create custom widgets
│   ├── editor-preview/           # Preview mode
│   └── flow-binding-panel/       # Bind flows to widgets
│
├── services/
│   ├── page-layout.service       # Page layout management
│   ├── widget-registry.service   # Widget registration
│   ├── widget-builder.service    # Widget creation
│   └── theme-bridge.service      # Theme integration
│
├── state/
│   ├── pages-structured.state    # Page state management
│   └── widgets-structured.state  # Widget state
│
└── actions/
    ├── save-current-page         # Save page
    ├── export-page-as-json       # Export functionality
    └── open-page-in-editor       # Open existing page

✅ Strengths

Visual Editor - Drag-and-drop page building
Widget System - Rich widget library
Layout Management - Flexible page layouts
Theme Integration - Uses theme-system
Preview Mode - Real-time preview
Export/Import - JSON-based page serialization

⚠️ Integration Gaps

Universe Context - Pages not scoped to specific universe
Module Assignment - Pages not assignable to modular-universe sections
Storage Schema - Page storage not aligned with universal module system
Section Awareness - Editor doesn't know about modular-universe sections

🎯 Required Enhancements

1. Universe-Scoped Pages

Current:

// Generic page storage
pageService.savePage(pageId, pageData);

Needed:

// Universe-scoped page as module
const pageModule: UniversalModule = {
  id: 'page-home',
  name: 'Home Page',
  type: 'page',
  universeId: 'universe-123',
  parentId: 'section-456', // Parent section in modular-universe
  config: {
    layout: pageLayout,
    widgets: widgets,
    flows: attachedFlows
  }
};

// Save as module
moduleService.install(universeId, pageModule, sectionId);

2. Section Integration

Needed:

// Open editor in context of section
editorService.openPageInSection({
  universeId: 'universe-123',
  sectionId: 'section-456',
  pageId: 'page-home' // or null for new page
});

// When saving, update section assignment
const section: SectionConfig = {
  id: 'section-456',
  contentType: 'page',
  assignedModuleId: 'page-home',
  // ... other config
};

3. Module Browser Integration

Needed:

// Pages appear in module browser as type='page'
const pageManifest: ModuleManifest = {
  id: 'page-home',
  name: 'Home Page',
  type: 'page',
  category: 'Content',
  access: {
    visibility: 'public',
    audience: 'space-builder',
    showInBrowser: true,
    showInSelector: true
  },
  embeddableComponents: [],
  publicActions: ['edit', 'preview', 'export']
};

4. Navigation Context

Proposed Routes:

// From modular-universe section
→ /space/:spaceSlug/editor?universe=123&section=456&page=home

// From module browser (create new page)
→ /space/:spaceSlug/editor?universe=123&section=456&mode=create

// Standalone page editing
→ /space/:spaceSlug/editor/pages/:pageId

📋 Action Items for Editor-Web

Implement universe-scoped page storage
Add section context awareness to editor
Register pages as universal modules
Add "Edit in Editor" action to section-config-panel
Update routes to support section context
Enhance page-layout service with module integration

🧩 MODULARITY-LIB REVIEW

Location: libs/libs-structural/modularity-lib/
Purpose: Module creation wizard and packaging system

📊 Current State

Status: ✅ OPERATIONAL - Good foundation, UX needs improvement

Core Components:

modularity-lib/
├── components/
│   ├── modularity-dashboard/      # Main dashboard
│   ├── module-creation-wizard/    # Step-by-step creation
│   ├── module-builder/            # Visual module builder
│   ├── ai-module-builder/         # AI-powered generation
│   ├── module-detail/             # Module detail page
│   ├── template-selector/         # Module templates
│   ├── deploy-config/             # Deployment settings
│   └── marketplace-page/          # Module marketplace
│
├── services/
│   ├── modularity.service         # Core service
│   ├── module-generator.service   # Generate modules
│   ├── module-packager.service    # Package for export
│   ├── module-storage.service     # Storage operations
│   ├── ai-module-generation       # AI generation
│   └── unified-module-manager     # Manage all modules
│
└── models/
    └── unified-module.models.ts   # Module type definitions

✅ Strengths

Creation Wizard - Step-by-step module creation
AI Generation - AI-powered module building
Templates - Pre-built module templates
Packaging - Export modules for reuse
Marketplace - Share modules (foundation)

⚠️ Integration Gaps

Disconnected UX - Wizard feels separate from modular-universe
Module Types - Not fully aligned with universal module types
Visual Builder - ui-canvas-builder needs work
Flow Integration - Not connected to singularity flows
Page Integration - Not connected to editor-web pages

🎯 Required Enhancements

1. Unified Module Creation

Current Flow:

User → Modularity Dashboard → Wizard → Create → Done (but where does it go?)

Needed Flow:

User → Module Browser → "Create New Module" →
  ↓
Module Type Selection:
  - Page → Open editor-web-lib (with universe context)
  - Flow → Open singularity-lib (with universe context)
  - Navigation → Template + config wizard
  - Feature → Wizard with flow attachment
  - Galaxy/World → Open modular-universe builder
  - Widget → Open widget-builder (to be created)
  ↓
Module Created → Appears in module browser → Assignable to sections

2. Type-Specific Builders

Needed Routing Matrix:

const MODULE_CREATION_ROUTES = {
  'page': '/space/:spaceSlug/editor?mode=create&universe=:universeId',
  'flow': '/space/:spaceSlug/singularity/flows?mode=create&universe=:universeId',
  'galaxy': '/space/:spaceSlug/modular-universe?type=galaxy&mode=create',
  'world': '/space/:spaceSlug/modular-universe?type=world&mode=create',
  'navigation': '/space/:spaceSlug/modularity/builder?type=navigation',
  'feature': '/space/:spaceSlug/modularity/builder?type=feature',
  'widget': '/space/:spaceSlug/widgets/builder?mode=create'
};

3. Module Browser Integration

Needed:

// Modularity creates module → Registers with ModuleRegistry → Appears in browser
moduleRegistryService.registerModule(manifest);

// Module immediately available in section-config-panel
// No need to reload or navigate away

4. Enhanced Wizard

Proposed Steps:

Step 1: Module Type (visual cards with icons)
  - Structural: Galaxy, World, Page
  - Functional: Navigation, Feature, Widget
  - Logic: Flow, Custom

Step 2: Basic Info
  - Name, Description, Icon
  - Universe scope (if applicable)

Step 3: Configuration (type-specific)
  - Galaxy: Route, layout preferences
  - Page: Template selection → Opens editor
  - Flow: → Opens singularity
  - Navigation: Position, menu items
  - Feature: → Wizard with flow attachment

Step 4: Initial Structure (for galaxy/world)
  - Add children
  - Define relationships

Step 5: Review & Create
  - Summary
  - Create module
  - Auto-register with ModuleRegistry

📋 Action Items for Modularity

Refactor wizard to be type-aware with routing to specialized tools
Integrate module-browser as starting point
Connect to editor-web for page creation
Connect to singularity for flow creation
Connect to modular-universe for galaxy/world creation
Enhance module-detail page with cross-tool navigation
Implement seamless registration after creation

🔗 INTEGRATION STRATEGY

Cross-Library Communication

/**
 * Unified Module Creation Flow
 */

// 1. User clicks "Create Module" in module-browser
→ Opens modularity wizard

// 2. User selects module type
→ Wizard determines routing

// 3. Type-specific routing
if (type === 'page') {
  → navigate to editor-web with universe context
  → editor creates page
  → editor saves as UniversalModule
  → editor registers with ModuleRegistry
  → page appears in module-browser
}

if (type === 'flow') {
  → navigate to singularity with universe context
  → singularity creates flow
  → singularity saves as UniversalModule
  → singularity registers with ModuleRegistry
  → flow appears in module-browser
}

if (type === 'galaxy' || type === 'world') {
  → navigate to modular-universe
  → modular-universe creates structure
  → saves as UniversalModule
  → registers with ModuleRegistry
}

// 4. Module available everywhere
→ Module-browser shows new module
→ Section-config-panel can assign it
→ Space-builder can reuse it

Storage Schema Unification

Current (Inconsistent):

// Singularity
storage.put('flow:123', flowData);

// Editor-web
storage.put('page:456', pageData);

// Modularity
storage.put('module:789', moduleData);

Needed (Unified):

// All as universal modules
storage.putInUniverse(spaceId, universeId, 'module:flow-123', flowModule);
storage.putInUniverse(spaceId, universeId, 'module:page-456', pageModule);
storage.putInUniverse(spaceId, universeId, 'module:navigation-789', navModule);

// Query by type
const pages = await storage.queryModulesByType(universeId, 'page');
const flows = await storage.queryModulesByType(universeId, 'flow');

Service Layer Integration

Needed: UnifiedModuleCreationService

@Injectable()
export class UnifiedModuleCreationService {
  
  /**
   * Create module with type-specific routing
   */
  async createModule(
    type: ModuleType,
    universeId: string,
    context?: { sectionId?: string; parentId?: string }
  ): Promise<UniversalModule> {
    
    // Route to appropriate builder
    const route = this.getBuilderRoute(type, universeId, context);
    this.router.navigate([route]);
    
    // Return promise that resolves when module is created
    return this.awaitModuleCreation();
  }
  
  /**
   * Get builder route based on type
   */
  private getBuilderRoute(
    type: ModuleType,
    universeId: string,
    context?: any
  ): string {
    const routes = {
      'page': `/space/${this.spaceSlug}/editor`,
      'flow': `/space/${this.spaceSlug}/singularity/flows`,
      'galaxy': `/space/${this.spaceSlug}/modular-universe`,
      'world': `/space/${this.spaceSlug}/modular-universe`,
      'navigation': `/space/${this.spaceSlug}/modularity/builder`,
      'feature': `/space/${this.spaceSlug}/modularity/builder`,
      'widget': `/space/${this.spaceSlug}/widgets/builder`
    };
    
    const base = routes[type] || routes['page'];
    const params = new URLSearchParams({
      universe: universeId,
      type: type,
      mode: 'create',
      ...(context?.sectionId && { section: context.sectionId })
    });
    
    return `${base}?${params}`;
  }
}

📊 IMPLEMENTATION PRIORITY

Phase 1: Storage Unification (Week 1)

Implement universe-scoped storage methods
Migrate singularity flows to universal modules
Migrate editor-web pages to universal modules
Update storage-system with module query methods

Phase 2: Module Registry Integration (Week 2)

Register flows as modules in ModuleRegistry
Register pages as modules in ModuleRegistry
Ensure all modules appear in module-browser
Update access control for created modules

Phase 3: Cross-Tool Navigation (Week 3)

Create UnifiedModuleCreationService
Update modularity wizard with routing
Add "Edit in X" actions to module-detail pages
Implement context-aware navigation

Phase 4: Enhanced Integration (Week 4)

Flow attachment to universal modules
Page assignment to modular-universe sections
Seamless workflow testing
Documentation and training materials

🎯 SUCCESS METRICS

Technical Integration

All modules stored with universe scope
All modules registered with ModuleRegistry
All modules appear in module-browser
Cross-tool navigation working seamlessly

User Experience

Create module → appears in browser (< 5 seconds)
Assign module to section (< 3 clicks)
Edit module → opens correct tool (1 click)
Reuse module across universes (drag & drop)

Platform Cohesion

Unified storage schema
Consistent module types
Integrated navigation
Connected workflows

📚 RELATED DOCUMENTS

Decisions: DECISIONS-REFRESHED-NOV-2025.md
Master Plan: ULTIMATE-PLATFORM-BUILDER-MASTER-PLAN.md
Module Architecture: BREAKTHROUGH-MODULES-ARE-STRUCTURE.md

Status: ✅ REVIEW COMPLETE
Next Action: Implement storage unification
Owner: Development Team
Last Updated: November 14, 2025