FINAL Cosmic Architecture - Session 48

STATUS: APPROVED - Reflects actual implementation Date: January 16, 2026 Last Updated: Session 48 - Layout Builder & libs-renderable Integration Goal: ONE canonical architecture - modules as reusable building blocks

1. Core Principles

What We Solved:

1. Consistent Naming: universe-root is the canonical root type
2. Unified Node Types: 'universe-root' | 'galaxy' | 'world' | 'page-module'
3. Placement-Based Inheritance: No separate "nebula" - modules inherit based on where they're placed
4. Modules as Building Blocks: Truly reusable, placement determines scope

Key Insight:

Modules are structure. A module's behavior is determined by WHERE it's placed, not by a special cosmic type.

2. FINAL Cosmic Hierarchy

Universe (MongoDB document - the container)
└── universe-root (type: 'universe-root') ☀️
    │
    ├── [navigation] ← Placed here = renders on ALL galaxies/worlds
    ├── [layout]     ← Placed here = applies universally
    │
    ├── galaxy (type: 'galaxy') 🌌
    │   │
    │   ├── [navigation] ← Placed here = renders on this galaxy's worlds only
    │   │
    │   ├── world (type: 'world') 🌍
    │   │   └── page-module (type: 'page-module') 📄
    │   │
    │   └── world
    │       └── page-module
    │
    └── galaxy
        └── world
            └── page-module

Inheritance Rule:

• Module at universe-root → Renders on ALL descendants (all galaxies, all worlds)
• Module at galaxy → Renders on that galaxy's worlds only
• Module at world → Renders on that world only

3. CrossToolSync Node Types

// Canonical node types for cross-tool synchronization
type CrossToolNodeType = 'universe-root' | 'galaxy' | 'world' | 'page-module';

Used in:

• CrossToolSyncService.broadcastNodeUpdate()
• CrossToolSyncService.broadcastNodeCreate()
• CrossToolSyncService.broadcastNodeDelete()

4. Visual Representation

5. CosmicModuleType

/**
 * CosmicModuleType - The structural types in the cosmic hierarchy
 *
 * 🎯 AI TRAINING:
 * - 'universe-root': Top-level container (ONE per universe, required)
 * - 'galaxy': Route collection (e.g., /admin, /public)
 * - 'world': Page container within a galaxy (e.g., /admin/dashboard)
 * - 'page-module': Actual page with content (links to pageId)
 * - 'layout': Layout container for organizing children
 * - 'navigation': Navigation components (sidebar, topnav)
 * - 'feature': Feature modules with business logic
 * - 'widget': Reusable UI widgets
 * - 'custom': Custom module types
 */
export type CosmicModuleType =
  | 'universe-root'  // ONE per universe, the sun
  | 'galaxy'         // Major sections with their own routes
  | 'world'          // Pages within a galaxy
  | 'page-module'    // Actual page content (references pageId)
  | 'navigation'     // Nav components (placement determines scope)
  | 'layout'         // Layout wrappers (placement determines scope)
  | 'feature'        // Feature modules with business logic
  | 'widget'         // UI widgets
  | 'custom';        // Custom types

6. COSMIC_HIERARCHY_RULES

export const COSMIC_HIERARCHY_RULES: Record<CosmicModuleType, CosmicModuleType[]> = {
  // Universe-root can contain galaxies and global UI
  'universe-root': ['galaxy', 'layout', 'navigation', 'feature', 'widget'],
  
  // Galaxy contains worlds and galaxy-level UI
  'galaxy': ['world', 'layout', 'navigation', 'feature', 'widget'],
  
  // World contains pages and world-level UI
  'world': ['page-module', 'layout', 'widget', 'feature'],
  
  // Page-module is a leaf that renders widget content
  'page-module': ['widget', 'feature'],
  
  // Layout can contain structural elements
  'layout': ['layout', 'navigation', 'feature', 'widget', 'custom'],
  
  // Navigation can have sub-navigation
  'navigation': ['navigation', 'widget'],
  
  // Feature and widget are typically leaves
  'feature': ['widget'],
  'widget': [],
  'custom': ['widget', 'feature'],
};

7. Inheritance Configuration

StructureNodeConfig

interface StructureNodeConfig {
  // Identity
  name: string;
  type: CosmicModuleType;

  // Routing
  route?: string;

  // Layout
  layoutSlot?: 'header' | 'sidebar' | 'content' | 'footer' | 'overlay';
  layout?: ModuleLayout;

  // Inheritance Behavior
  inheritToChildren?: boolean;  // Default: true for navigation/layout, false for content

  // Page Reference (for page-module type)
  pageId?: string;

  // AI Metadata
  ai?: ModuleAIMetadata;
}

Default Inheritance Rules:

8. Placement-Based Scoping (Replaces Nebula)

Instead of a separate "nebula" type, modules are scoped by WHERE they're placed:

Example: Global Navigation

{
  "structure": [
    {
      "moduleId": "universe-root-123",
      "config": { "type": "universe-root", "name": "My Platform" },
      "children": [
        {
          "config": { 
            "type": "navigation", 
            "name": "Main Navigation",
            "inheritToChildren": true,
            "layoutSlot": "header"
          }
        },
        {
          "moduleId": "galaxy-admin-123",
          "config": { "type": "galaxy", "name": "Admin", "route": "/admin" },
          "children": [
            {
              "moduleId": "world-dashboard-123",
              "config": { "type": "world", "name": "Dashboard", "route": "/dashboard" },
              "children": [
                { "config": { "type": "page-module", "name": "Dashboard Page", "pageId": "..." } }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Result: Main Navigation renders on ALL pages in ALL galaxies.

Example: Galaxy-Specific Sidebar

{
  "moduleId": "galaxy-admin-123",
  "config": { "type": "galaxy", "name": "Admin", "route": "/admin" },
  "children": [
    {
      "config": { 
        "type": "navigation", 
        "name": "Admin Sidebar",
        "inheritToChildren": true,
        "layoutSlot": "sidebar"
      }
    },
    { "config": { "type": "world", "name": "Dashboard" }, "children": [...] }
  ]
}

Result: Admin Sidebar renders ONLY on Admin galaxy's worlds.

9. Real-World Examples

E-Commerce Platform

universe-root: "ShopNow Platform"
├── [navigation: "Main Nav"] ← Global, renders everywhere
├── [widget: "Cart Drawer"]  ← Global overlay
│
├── galaxy: "Storefront" (/shop)
│   ├── world: "Home" (/)
│   │   └── page-module: "Home Page"
│   ├── world: "Products" (/products)
│   │   └── page-module: "Product List"
│   └── world: "Checkout" (/checkout)
│       └── page-module: "Checkout Flow"
│
├── galaxy: "Account" (/account)
│   ├── [navigation: "Account Sidebar"] ← Only on Account pages
│   ├── world: "Profile" (/profile)
│   └── world: "Orders" (/orders)
│
└── galaxy: "Admin" (/admin)
    ├── [navigation: "Admin Sidebar"] ← Only on Admin pages
    ├── world: "Dashboard" (/dashboard)
    └── world: "Inventory" (/inventory)

SaaS Dashboard

universe-root: "Analytics Hub"
├── [navigation: "Top Bar"]
├── [layout: "App Shell"]
│
├── galaxy: "Dashboard" (/dashboard)
│   ├── world: "Overview" (/)
│   ├── world: "Reports" (/reports)
│   └── world: "Alerts" (/alerts)
│
└── galaxy: "Settings" (/settings)
    ├── [navigation: "Settings Nav"]
    ├── world: "Account" (/account)
    └── world: "Integrations" (/integrations)

10. Tool Responsibilities

10.1 libs-renderable (Session 48)

Reusable templates for layouts and navigation with dual Angular + Flutter support.

Structure

libs/libs-renderable/
├── layout-templates/
│   ├── split-sidebar/           # Angular + Flutter
│   ├── header-content-footer/   # Angular + Flutter
│   ├── dashboard/               # Angular + Flutter
│   ├── two-column-equal/        # Angular + Flutter
│   └── three-column-equal/      # Angular + Flutter
├── navigation-templates/
│   ├── sidebar-nav/             # Angular + Flutter
│   ├── top-nav/                 # Angular + Flutter
│   ├── footer/                  # Angular + Flutter
│   └── breadcrumb-nav/          # Angular + Flutter
├── shell-components/
│   ├── page-renderer/
│   └── routes-manager/
└── shared/
    ├── models/
    ├── angular/
    └── flutter/

Usage with moduleRef

Navigation and layout nodes reference libs-renderable templates:

const navNode: CosmicNode = {
  id: 'nav-1',
  name: 'Main Navigation',
  nodeType: 'navigation',
  moduleRef: '@libs-renderable/navigation-templates/sidebar-nav',
  inheritToChildren: true,
  layoutSlot: 'sidebar',
};

Layout Configuration

Galaxies and worlds can specify layout configuration:

const galaxyNode: CosmicNode = {
  id: 'galaxy-1',
  name: 'Admin',
  nodeType: 'galaxy',
  layout: {
    template: 'split-sidebar',
    templateRef: '@libs-renderable/layout-templates/split-sidebar',
    sidebarWidth: 280,
    sidebarPosition: 'left',
  },
};

10.2 Layout Builder Tool (Session 48)

Visual tool for creating and editing layouts with dual-target export.

Capabilities

• Drag-and-drop visual layout editing
• Pre-built template library from libs-renderable
• Responsive breakpoint configuration
• Dual export: Angular standalone components + Flutter widgets

Export Targets

Integration

The layout-builder is available in unified-builder as the builder-layout panel.

11. Files Updated (Session 46.3)

Cross-Tool Sync:

• cross-tool-sync.service.ts - NodeType: 'universe-root' | 'galaxy' | 'world' | 'page-module'

Page Builder:

• page-builder.component.ts - Uses 'page-module' nodeType

Vibe Universe Generator:

• vibe-universe-generator.component.ts - toCrossToolNodeType() returns proper types

Universe Context:

• universe-context.service.ts - Uses ActiveToolType union

12. Duplicate Interfaces - Status

Canonical Source (KEEP):

libs/libs-foundational/core-models/src/lib/types/modules/universal-module.types.ts

Duplicates (Session 48):

• backend-module-api.service.ts - Imports from core-models
• universal-modules.controller.ts - Imports from shared types

12.1 Singularity → Modularity-lib Migration (Session 48)

The standalone singularity-lib has been integrated into modularity-lib.

Migration Path

// Old (deprecated)
import { FlowCompositionService } from '@libs-structural/singularity-lib';

// New
import { FlowIntegrationService } from '@libs-structural/modularity-lib';

Integration Benefits

• Actions generated by modularity-lib can have inline flow definitions
• Complex CRUD operations use flow builder for custom logic
• Single tool for both module structure AND action logic

Deprecated Files

The following are deprecated and retained for reference only:

• libs/libs-structural/singularity-lib/ - Use modularity-lib instead
• modules/layout/* - Use @libs-renderable/layout-templates
• modules/navigation/* - Use @libs-renderable/navigation-templates

13. Summary

Status: Reflects actual codebase state as of Session 48