AI Module Generation Guide

Instructions for AI to generate module-based universe structures

🤖 AI Module Generation Guide

For: AI Assistant training
Purpose: Generate optimal module structures based on user intent
Architecture: Universal Module System with Type-Based Behavior

🎯 Core Concept

Everything is a module with a type!

// Don't think:
"Create universe → galaxy → world → page"

// Think:
"Create modules with appropriate types based on intent"

📚 Module Types Reference

Structural Modules (Use Cosmic Names!)

Galaxy (type: 'galaxy')

Purpose: Route collection with children
Use When: Organizing related content areas
Example: "Products", "Blog", "Account"
Can Contain: Worlds, Pages, other Galaxies
Cosmic Term: "Galaxy" (preserve in UI!)

World (type: 'world')

Purpose: Page container with optional filtering
Use When: Grouping related pages with common features
Example: "Electronics", "Clothing", "Breakfast Menu"
Can Contain: Pages
Cosmic Term: "World" (preserve in UI!)

Page (type: 'page')

Purpose: Actual content page with widgets
Use When: Creating viewable content
Example: "Home", "About", "Product Details"
Can Contain: Widgets
Cosmic Term: "Page" (preserve in UI!)

Functional Modules

Navigation (type: 'navigation')

Purpose: Nav components (TopNav, Footer, Sidebar)
Position: header, footer, sidebar
Example: Main navigation, footer menu

Feature (type: 'feature')

Purpose: Feature modules (Cart, Auth, Search)
Position: header, overlay, modal
Example: Shopping cart, search bar

Widget (type: 'widget')

Purpose: Reusable UI components
Example: Product card, hero section

🧠 Generation Rules

Rule 1: Simplicity First

User: "Create a blog"

✅ GOOD (Simple):
[
  { type: 'navigation', name: 'Header', position: 'header' },
  { type: 'page', name: 'Home', route: '/' },
  { type: 'page', name: 'About', route: '/about' },
  { type: 'page', name: 'Blog', route: '/blog' },
  { type: 'navigation', name: 'Footer', position: 'footer' }
]

❌ BAD (Over-engineered):
[
  { type: 'galaxy', name: 'Main', children: [
    { type: 'world', name: 'Content', children: [
      { type: 'page', name: 'Home' }
    ]}
  ]}
]

Principle: Don't use Galaxy/World unless structure actually needs it

Rule 2: Use Hierarchy When Meaningful

User: "Create e-commerce site with product categories"

✅ GOOD (Meaningful hierarchy):
[
  { type: 'navigation', name: 'TopNav', position: 'header' },
  { 
    type: 'galaxy', 
    name: 'Products',
    route: '/products',
    children: [
      { 
        type: 'world', 
        name: 'Electronics',
        route: '/products/electronics',
        children: [
          { type: 'page', name: 'Laptops', route: '/products/electronics/laptops' },
          { type: 'page', name: 'Phones', route: '/products/electronics/phones' }
        ]
      },
      { 
        type: 'world', 
        name: 'Clothing',
        route: '/products/clothing',
        children: [...]
      }
    ]
  },
  { type: 'feature', name: 'Cart', position: 'header' }
]

Principle: Use Galaxy for major sections, World for categories, Page for items

Rule 3: Flexible Composition

User: "Add user account section"

✅ Can add as simple pages:
[
  { type: 'page', name: 'Profile', route: '/profile' },
  { type: 'page', name: 'Settings', route: '/settings' }
]

✅ OR as Galaxy with pages:
[
  { 
    type: 'galaxy',
    name: 'Account',
    route: '/account',
    children: [
      { type: 'page', name: 'Profile', route: '/account/profile' },
      { type: 'page', name: 'Settings', route: '/account/settings' }
    ]
  }
]

Principle: Both are valid - choose based on user's likely intent

💡 Generation Patterns

Pattern 1: Simple Website

// User: "Create portfolio website"

generateModules([
  { type: 'navigation', name: 'Header', position: 'header' },
  { type: 'page', name: 'Home', route: '/' },
  { type: 'page', name: 'Portfolio', route: '/portfolio' },
  { type: 'page', name: 'About', route: '/about' },
  { type: 'page', name: 'Contact', route: '/contact' },
  { type: 'navigation', name: 'Footer', position: 'footer' }
])

// NO galaxy/world needed - just pages!

Pattern 2: Content Site with Sections

// User: "Create restaurant menu site"

generateModules([
  { type: 'navigation', name: 'TopNav', position: 'header' },
  {
    type: 'world',
    name: 'Breakfast',
    route: '/breakfast',
    children: [
      { type: 'page', name: 'Pancakes', route: '/breakfast/pancakes' },
      { type: 'page', name: 'Waffles', route: '/breakfast/waffles' }
    ]
  },
  {
    type: 'world',
    name: 'Lunch',
    route: '/lunch',
    children: [...]
  },
  { type: 'feature', name: 'Order Cart', position: 'header' }
])

// Uses World for meal categories

Pattern 3: Complex Application

// User: "Create full e-commerce platform"

generateModules([
  { type: 'navigation', name: 'MainNav', position: 'header' },
  { type: 'feature', name: 'Shopping Cart', position: 'header' },
  { type: 'feature', name: 'Search', position: 'header' },
  
  // Products section
  {
    type: 'galaxy',
    name: 'Products',
    route: '/products',
    children: [
      {
        type: 'world',
        name: 'Electronics',
        children: [
          { type: 'page', name: 'Laptops' },
          { type: 'page', name: 'Phones' }
        ]
      },
      { type: 'world', name: 'Clothing', children: [...] }
    ]
  },
  
  // Account section
  {
    type: 'galaxy',
    name: 'Account',
    route: '/account',
    children: [
      { type: 'page', name: 'Profile' },
      { type: 'page', name: 'Orders' },
      { type: 'page', name: 'Settings' }
    ]
  },
  
  { type: 'navigation', name: 'Footer', position: 'footer' }
])

// Full hierarchy: Galaxy → World → Page

🎨 Best Practices

1. Route Generation

// Auto-generate routes from names
name: "Product Catalog" → route: "/product-catalog"
name: "About Us" → route: "/about-us"

// Nest routes naturally
Galaxy "Products" route="/products"
  → World "Electronics" route="/products/electronics"
    → Page "Laptops" route="/products/electronics/laptops"

2. Parent Relationships

// Set parentId for nesting
{
  type: 'world',
  name: 'Electronics',
  parentId: productsGalaxyId,  // ← Nest in Products galaxy
  children: [...]
}

3. Position Assignment

// Always set position for navigation/feature modules
{ type: 'navigation', position: 'header' }
{ type: 'feature', position: 'overlay' }

// Don't set position for structural modules
{ type: 'galaxy' }  // No position needed

4. Order Management

// Use order for display sequence
{ type: 'page', name: 'Home', order: 1 },
{ type: 'page', name: 'About', order: 2 },
{ type: 'page', name: 'Contact', order: 3 }

🚫 Common Mistakes to Avoid

Mistake 1: Over-nesting

// ❌ BAD: Too many levels for simple site
{
  type: 'galaxy',
  children: [{
    type: 'world',
    children: [{
      type: 'page', name: 'Home'
    }]
  }]
}

// ✅ GOOD: Keep it simple
{ type: 'page', name: 'Home', route: '/' }

Mistake 2: Wrong Type Selection

// ❌ BAD: Using page for navigation
{ type: 'page', name: 'TopNav' }

// ✅ GOOD: Use navigation type
{ type: 'navigation', name: 'TopNav', position: 'header' }

Mistake 3: Missing Routes

// ❌ BAD: Structural module without route
{ type: 'galaxy', name: 'Products' }  // No route!

// ✅ GOOD: Always add routes for galaxy/world/page
{ type: 'galaxy', name: 'Products', route: '/products' }

🎯 Decision Tree

User wants to create content
  ↓
Ask: Is it a nav component?
  → YES: type='navigation', set position
  → NO: Continue
  ↓
Ask: Is it a feature (cart, search, auth)?
  → YES: type='feature', set position  
  → NO: Continue
  ↓
Ask: Is it a collection/section?
  → YES: Use Galaxy or World (based on complexity)
  → NO: Use Page
  ↓
Ask: Should it have children?
  → YES: type='galaxy' or 'world'
  → NO: type='page'

💡 Examples by Use Case

Blog

Simple → Just Pages
{navigation, page, page, page, navigation}

Portfolio

Medium → Galaxy with Pages
{navigation, galaxy[pages...], navigation}

E-commerce

Complex → Galaxy → World → Pages
{navigation, feature, galaxy[world[pages...]], galaxy[pages...], navigation}

SaaS App

Very Complex → Multiple Galaxies with Nested Structure
{navigation, galaxy[world[pages...]], galaxy[pages...], feature, navigation}

🔥 AI Generation Algorithm

function generateModuleStructure(userIntent: string): UniversalModule[] {
  const modules: CreateModuleData[] = [];
  
  // 1. Always start with navigation
  modules.push({
    type: 'navigation',
    name: 'Header',
    position: 'header'
  });
  
  // 2. Parse user intent
  const sections = extractSections(userIntent);
  
  // 3. Generate structure based on complexity
  sections.forEach(section => {
    if (section.hasSubcategories) {
      // Use Galaxy → World → Pages
      modules.push({
        type: 'galaxy',
        name: section.name,
        route: `/${slugify(section.name)}`,
        children: section.subcategories.map(sub => ({
          type: 'world',
          name: sub.name,
          route: `/${slugify(section.name)}/${slugify(sub.name)}`,
          children: sub.pages.map(page => ({
            type: 'page',
            name: page.name,
            route: `/${slugify(section.name)}/${slugify(sub.name)}/${slugify(page.name)}`
          }))
        }))
      });
    } else if (section.hasMultiplePages) {
      // Use Galaxy → Pages
      modules.push({
        type: 'galaxy',
        name: section.name,
        route: `/${slugify(section.name)}`,
        children: section.pages.map(page => ({
          type: 'page',
          name: page.name,
          route: `/${slugify(section.name)}/${slugify(page.name)}`
        }))
      });
    } else {
      // Just Page
      modules.push({
        type: 'page',
        name: section.name,
        route: `/${slugify(section.name)}`
      });
    }
  });
  
  // 4. Add features if mentioned
  if (userIntent.includes('cart') || userIntent.includes('shopping')) {
    modules.push({
      type: 'feature',
      name: 'Shopping Cart',
      position: 'header'
    });
  }
  
  // 5. Always end with footer
  modules.push({
    type: 'navigation',
    name: 'Footer',
    position: 'footer'
  });
  
  return modules;
}

✅ Validation Rules

Before Generating, Check:

✅ Does each module have a name?
✅ Does each structural module (galaxy/world/page) have a route?
✅ Are parentId relationships valid?
✅ Do navigation/feature modules have position?
✅ Are routes unique and properly formatted?

After Generating, Verify:

✅ At least one page exists
✅ Routes don't conflict
✅ Parent relationships are valid
✅ Structure makes logical sense

🎯 Real-World Examples

Example 1: "Create a personal blog"

[
  { "type": "navigation", "name": "Header", "position": "header" },
  { "type": "page", "name": "Home", "route": "/" },
  { "type": "page", "name": "Blog", "route": "/blog" },
  { "type": "page", "name": "About", "route": "/about" },
  { "type": "navigation", "name": "Footer", "position": "footer" }
]

Example 2: "Create restaurant menu with breakfast, lunch, dinner"

[
  { "type": "navigation", "name": "Top Nav", "position": "header" },
  {
    "type": "world",
    "name": "Breakfast",
    "route": "/breakfast",
    "children": [
      { "type": "page", "name": "Pancakes", "route": "/breakfast/pancakes" },
      { "type": "page", "name": "Waffles", "route": "/breakfast/waffles" }
    ]
  },
  {
    "type": "world",
    "name": "Lunch",
    "route": "/lunch",
    "children": [...]
  },
  {
    "type": "world",
    "name": "Dinner",
    "route": "/dinner",
    "children": [...]
  },
  { "type": "feature", "name": "Order Cart", "position": "header" },
  { "type": "navigation", "name": "Footer", "position": "footer" }
]

Example 3: "Create online store with products and account"

[
  { "type": "navigation", "name": "Main Nav", "position": "header" },
  { "type": "feature", "name": "Search", "position": "header" },
  { "type": "feature", "name": "Cart", "position": "header" },
  {
    "type": "galaxy",
    "name": "Products",
    "route": "/products",
    "children": [
      {
        "type": "world",
        "name": "Electronics",
        "route": "/products/electronics",
        "children": [
          { "type": "page", "name": "Laptops", "route": "/products/electronics/laptops" },
          { "type": "page", "name": "Phones", "route": "/products/electronics/phones" }
        ]
      },
      {
        "type": "world",
        "name": "Clothing",
        "route": "/products/clothing",
        "children": [...]
      }
    ]
  },
  {
    "type": "galaxy",
    "name": "Account",
    "route": "/account",
    "children": [
      { "type": "page", "name": "Profile", "route": "/account/profile" },
      { "type": "page", "name": "Orders", "route": "/account/orders" }
    ]
  },
  { "type": "navigation", "name": "Footer", "position": "footer" }
]

🚀 API Integration

Create Modules via Service

// Use UniversalModuleService
const moduleService = inject(UniversalModuleService);

// Create galaxy
moduleService.createGalaxy(
  universeId,
  'Products',
  '/products'
).subscribe(galaxy => {
  // Create world inside galaxy
  moduleService.createWorld(
    universeId,
    'Electronics',
    '/electronics',
    galaxy.id  // parentId
  ).subscribe(world => {
    // Create pages inside world
    moduleService.createPage(
      universeId,
      'Laptops',
      '/laptops',
      world.id  // parentId
    ).subscribe();
  });
});

🎓 Training Examples

Train on these patterns:

Simple sites: Just pages + navigation
Content sites: Worlds for categories
Complex apps: Galaxy → World → Page hierarchy
Features: Always use feature type for cart/search/auth
Navigation: Always use navigation type for nav components

✅ Quality Checklist

Before returning generated modules:

Every module has a valid type
Every module has a name
Structural modules have routes
Navigation modules have positions
Parent relationships are valid
At least one content page exists
Routes don't conflict
Structure matches user intent
Simplicity is maintained

This guide enables AI to generate perfect module structures for any use case! 🌟