AI Generation Gaps Analysis

Problem Statement

Generated modules (e.g., "Complete Fitness") have generic "Item" entities instead of domain-specific ones (Member, Class, Trainer). Tools (Canvas, Architect, Workbench) cannot properly render/edit these modules.

Root Cause #1: LLM Fallback Triggers Too Easily

File: libs/libs-api/llm-integration/src/lib/services/generation.service.ts:313-357

private createFallbackModuleConfig(request: ModuleGenerationRequest): GeneratedModuleConfig {
  return {
    entities: [
      {
        name: 'Item',  // ❌ GENERIC - NOT domain-specific
        fields: [...]
      }
    ],
    // ...
  };
}

When Fallback Triggers:

1. LLM returns invalid JSON
2. JSON extraction regex fails (/```json\n?([\s\S]*?)\n?```/)
3. Parser encounters unexpected structure
4. Any error in parsing → immediate fallback to "Item"

Impact: Every generation failure produces identical generic modules instead of domain-specific ones.

Root Cause #2: Missing Entity Extraction from Business Description

Problem: When LLM fails, there's NO attempt to extract entities from the business description using heuristics.

Example:

• Prompt: "Create a fitness studio platform with membership management, class scheduling, trainer assignments"
• Current Fallback: Creates "Item" entity
• Expected: Extract "Member", "Class", "Trainer" from description

Should Do:

private extractEntitiesFromDescription(description: string): Entity[] {
  const entityPatterns = [
    /(\w+)\s+management/gi,
    /manage\s+(\w+)/gi,
    /track\s+(\w+)/gi,
    /schedule\s+(\w+)/gi,
    /(\w+)\s+tracking/gi,
  ];
  
  const entities = new Set<string>();
  for (const pattern of entityPatterns) {
    const matches = description.matchAll(pattern);
    for (const match of matches) {
      entities.add(capitalizeFirst(match[1]));
    }
  }
  
  return Array.from(entities).map(name => ({
    name: singularize(name),
    fields: generateDefaultFields(name)
  }));
}

Root Cause #3: Code Generator Doesn't Adapt to Missing Entities

File: apis/backend-ai-api/src/app/workflow/generators/module-code-generator.service.ts:180-266

Even when given generic entities, the code generator creates action files named after the entity:

• create-item.action.ts instead of create-member.action.ts
• ItemListComponent instead of MemberListComponent

This makes the generated code non-semantic and harder to edit.

Root Cause #4: Manifest Routes Don't Match Domain

File: modules/other/complete-fitness/src/lib/complete-fitness.manifest.ts:11-22

"routes": [
  {
    "path": "complete-fitness",        // ❌ Should be "/members", "/classes", "/trainers"
    "title": "Complete Fitness",
    "component": "ItemList"            // ❌ Should be "MemberList"
  },
  {
    "path": "complete-fitness/:id",
    "title": "Complete Fitness Detail",
    "component": "ItemDetail"
  }
]

Domain routes are essential for:

• Navigation clarity
• SEO optimization
• User understanding
• Tool integration

Root Cause #5: Canvas Doesn't Render Module Children

Observation: Screenshot shows "Complete Fitness UNIVERSE CORE" badge but empty content below.

Analysis: The generated universe tree has structure:

platform-root
  ├── navigation
  └── galaxy
      └── Complete Fitness (world)

But the canvas is showing "UNIVERSE CORE" instead of rendering the world module.

Likely Issues:

1. Canvas expects sections with contentType: 'module' and moduleId
2. Generated modules have type: 'world' but canvas doesn't know how to render worlds
3. Missing component mapping: world → which component renders it?

Root Cause #6: No Space Module Registration

Observation: Module files exist in /modules/other/complete-fitness/ but aren't in space_modules collection.

Impact:

• ModuleRegistry can't find the module
• Building Blocks palette doesn't show it
• Tools can't discover embeddable components
• Actions aren't registered in ActionRegistry

Required Flow:

// After generating files:
1. Register module in space_{spaceId}/modules collection
2. Add manifest to ModuleRegistry (frontend)
3. Register actions in ActionRegistry
4. Register embeddables for widget system
5. Broadcast module:registered event

Root Cause #7: Workbench Can't Load Generated Modules

Problem: editModule() in Vibe creates a new ModuleContext from scratch, but doesn't load the existing files.

Current: Creates empty context + navigates to workbench Expected:

1. Load manifest from modules/other/complete-fitness
2. Parse entities/actions/embeddables from manifest
3. Populate ModuleContext with existing data
4. Allow editing existing module

Comprehensive Fix Required

Phase 1: AI Generation Enhancement

1.1 Improve LLM Prompts

• Add more examples of entity extraction
• Specify required JSON structure more clearly
• Add validation rules to system prompt

1.2 Add Entity Extraction Heuristics

• Pattern matching for common business terms
• NLP-based entity extraction as fallback
• Domain vocabulary (fitness → Member, Class, Trainer, etc.)

1.3 Validate Before Fallback

• Check if JSON is partially valid
• Attempt to repair common issues
• Only fallback if truly unrecoverable

Phase 2: Module Registration Pipeline

2.1 Register in space_modules

After generating files, save to MongoDB:

const spaceModule = {
  _id: moduleSpec.id,
  spaceId,
  name: moduleSpec.name,
  type: 'code-module',
  manifest: generatedManifest,
  modulePath: `/modules/${category}/${moduleSpec.id}`,
  isActive: true
};
await spaceModulesCollection.insertOne(spaceModule);

2.2 Frontend Registration

// In frontend after generation:
this.moduleRegistry.registerModule(manifest);
// Registers actions, embeddables, routes

2.3 Broadcast Events

this.crossToolSync.broadcastModuleRegistered(moduleId, manifest);
// All tools refresh their catalogs

Phase 3: Canvas Rendering

3.1 Module → Section Conversion

Canvas needs to convert world/feature modules to render able sections:

if (module.type === 'world') {
  const section: CanvasSection = {
    id: module.id,
    contentType: 'module',
    moduleId: module.moduleRef || module.moduleId,
    layout: module.layout || defaultLayout,
    label: module.name,
    // Render as an embeddable container
  };
}

3.2 Component Registry

Register default renderers for module types:

• world → WorldContainerComponent (shows entity list/detail/form tabs)
• feature → FeatureContainerComponent (renders embeddables)
• navigation → NavigationRendererComponent (sidebar/topnav)

Phase 4: Workbench Integration

4.1 Load from Manifest

async loadGeneratedModule(moduleId: string): Promise<ModuleContext> {
  // 1. Read manifest from disk
  const manifest = await import(`/modules/${category}/${moduleId}/manifest.ts`);
  
  // 2. Convert to ModuleContext
  const context: ModuleContext = {
    moduleId,
    moduleName: manifest.name,
    entities: manifest.entities.map(convertToEntityDefinition),
    actions: manifest.publicActions.map(convertToActionDefinition),
    embeddables: manifest.embeddableComponents.map(convertToEmbeddableDefinition),
    // ...
  };
  
  return context;
}

4.2 Bi-Directional Sync

• Edit in workbench → regenerate code files
• Code changes → update ModuleContext
• Both stay in sync

Phase 5: Architect Visualization

5.1 Node Rendering

Architect already converts UniversalModule[] to CosmicNode[], but needs:

• Proper colors for module types
• Entity/action counts in metadata
• Port definitions for connections

5.2 Detail Panel

Show module manifest data:

• Entities with field lists
• Actions with I/O signatures
• Embeddables with bindings
• Routes

Priority Order

1. P0: Fix entity extraction (stops generic "Item" generation)
2. P0: Register modules in space_modules (enables discovery)
3. P0: Canvas rendering for world modules (shows in UI)
4. P1: Workbench load from manifest (enables editing)
5. P1: Architect detail panel (better visualization)
6. P2: Bi-directional sync (advanced editing)

Estimated Work

• Entity extraction fix: ~2 hours
• Registration pipeline: ~3 hours
• Canvas rendering: ~4 hours
• Workbench integration: ~3 hours
• Architect enhancements: ~2 hours
• Testing & debugging: ~4 hours

Total: ~18 hours of focused development

This is a full system integration task requiring changes across 8+ libraries.