Universe Structure

Overview

The Universe Structure is the foundational architecture for organizing applications within the editor2 platform. It provides a semantic, hierarchical system that maps directly to routing, layouts, and widget rendering.

This document serves as the single source of truth for understanding how universes, galaxies, worlds, and pages relate across all parts of the monorepo.

Visual Hierarchy

                           ┌─────────────────────────────────┐
                           │     PLATFORM-ROOT (The Sun)     │
                           │  User Label: "Universe Core"    │
                           │      Type: platform-root        │
                           └───────────────┬─────────────────┘
                                           │
              ┌────────────────────────────┼────────────────────────────┐
              │                            │                            │
              ▼                            ▼                            ▼
    ┌─────────────────┐          ┌─────────────────┐          ┌─────────────────┐
    │     GALAXY      │          │     GALAXY      │          │     GALAXY      │
    │  Admin Portal   │          │   Shop Portal   │          │   Dashboard     │
    │  Route: /admin  │          │  Route: /shop   │          │  Route: /dash   │
    │  Layout: split- │          │  Layout: top-   │          │  Layout: dash-  │
    │     sidebar     │          │      nav        │          │     board       │
    └────────┬────────┘          └────────┬────────┘          └─────────────────┘
             │                            │
    ┌────────┴────────┐          ┌────────┴────────┐
    │                 │          │                 │
    ▼                 ▼          ▼                 ▼
┌─────────┐     ┌─────────┐  ┌─────────┐     ┌─────────┐
│  WORLD  │     │  WORLD  │  │  WORLD  │     │  WORLD  │
│ Members │     │ Settings│  │Products │     │  Cart   │
│ /members│     │/settings│  │/products│     │  /cart  │
└────┬────┘     └─────────┘  └────┬────┘     └─────────┘
     │                            │
┌────┴────────────────┐     ┌────┴────────────────┐
│         │           │     │         │           │
▼         ▼           ▼     ▼         ▼           ▼
┌──────┐┌──────┐┌──────┐  ┌──────┐┌──────┐┌──────┐
│ PAGE ││ PAGE ││ PAGE │  │ PAGE ││ PAGE ││ PAGE │
│MODULE││MODULE││MODULE│  │MODULE││MODULE││MODULE│
│ List ││Detail││ Form │  │ List ││Detail││ Form │
│  ""  ││ :id  ││ /new │  │  ""  ││ :id  ││ /new │
└──────┘└──────┘└──────┘  └──────┘└──────┘└──────┘

Semantic Hierarchy (3 Levels)

Level Definitions

Platform Root (displayed as "Universe Core" to users)

• Type: platform-root
• Purpose: The central sun of your platform - every universe has exactly one
• Children: Only galaxies
• Route: Root path /
• Naming: Technical type is platform-root, user-facing label is "Universe Core"

Galaxy (Application Section)

• Purpose: Top-level route container with a layout template
• Children: Worlds and/or Page-Modules
• Route: First path segment (e.g., /admin, /shop)
• Layout: Defines template (split-sidebar, dashboard, top-nav, content-only)
• Auto-generates: Navigation module for sidebar/header
• Example: "Admin Portal" with split-sidebar layout

World (Feature Group)

• Purpose: Groups related pages by entity/feature
• Children: Page-Modules only
• Route: Second path segment (e.g., /members, /products)
• Metadata: Contains entityId and entityPlural for data binding
• Example: "Member Management" grouping list/detail/form pages

Page-Module (Actual Page)

• Purpose: Routable page with widget content
• Children: None (leaf node)
• Route: Final path segments (e.g., ``, :id, /new)
• References: pageId pointing to Page document with widgets
• Example: "Member List" with DataTable widget

Type Systems & Mappings

Type System Overview (Session 32.2 - Unified)

All type systems now use the SAME names - no conversion needed:

┌─────────────────────────────────────────────────────────────────────────┐
│                    UNIFIED TYPE SYSTEM (Session 32.2)                    │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  CosmicNodeType    =    ModuleType    =    CoreModuleType                │
│  (Canvas/Visual)        (Module Def)        (Core Logic)                 │
│                                                                          │
│  platform-root     =    platform-root  =    platform-root                │
│  galaxy            =    galaxy         =    galaxy                       │
│  world             =    world          =    world                        │
│  page-module       =    page-module    =    page-module                  │
│  page (deprecated) =    page           =    page                         │
│                                                                          │
│  User-facing labels: "Universe Core", "Galaxy", "World", "Page"          │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Mapping Table

Type Mapping (Now 1:1)

Located in architect-module-converter.service.ts:

// Session 32.2: Direct 1:1 mappings - no conversion needed
private moduleTypeToNodeType(moduleType: ModuleType): CosmicNodeType {
  if (moduleType === 'platform-root') return 'platform-root';
  if (moduleType === 'galaxy') return 'galaxy';
  if (moduleType === 'world') return 'world';
  if (moduleType === 'page-module') return 'page-module';
  if (moduleType === 'page') return 'page';  // @deprecated
  // Fallback mappings for legacy types...
  return 'page-module';
}

Interface Sources

Core Models Library

Path: @libs/libs-foundational/core-models/src/lib/types/

Universe Architect Library

Path: @libs/libs-space/universe-architect/src/lib/types/

Interface Definitions

ModuleType (Core Models)

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

export type CoreModuleType =
  | 'platform-root'    // Universe core
  | 'galaxy'           // Application section
  | 'world'            // Feature group
  | 'page-module'      // Actual page (Session 32.2)
  | 'page'             // @deprecated
  | 'data'
  | 'content'
  | 'form'
  | 'workflow'
  | 'integration'
  | 'utility';

export type ModuleType = CoreModuleType | /* other types */;

CosmicNodeType (Universe Architect)

// libs/libs-space/universe-architect/src/lib/types/cosmic-node.types.ts

export type CosmicNodeType =
  | 'platform-root'    // The sun (User Label: "Universe Core")
  | 'galaxy'           // Application section
  | 'world'            // Feature group
  | 'page-module'      // Actual page
  | 'page';            // @deprecated

UniversalModule (Core Models)

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

export interface UniversalModule {
  id: string;
  name: string;
  moduleType: ModuleType;
  description?: string;
  route?: string;
  parentId?: string;

  // Page-module specific
  pageId?: string;              // References Page document

  // Galaxy specific
  layout?: {
    template: 'split-sidebar' | 'dashboard' | 'top-nav' | 'content-only';
    regions?: Record<string, LayoutRegion>;
  };

  // World specific
  metadata?: {
    entityId?: string;          // e.g., 'member'
    entityPlural?: string;      // e.g., 'members'
  };

  children?: UniversalModule[];
  createdAt: string;
  updatedAt: string;
}

CosmicNode (Universe Architect)

// libs/libs-space/universe-architect/src/lib/types/cosmic-node.types.ts

export interface CosmicNode {
  id: string;
  type: CosmicNodeType;
  label: string;
  description?: string;
  position: CanvasPosition;
  parentId: string | null;
  childIds: string[];
  route?: string;
  pageId?: string;              // For page-module nodes
  moduleId?: string;
  icon?: string;
  color?: string;
  isExpanded: boolean;
  isLocked: boolean;
  inputs?: NodePort[];
  outputs?: NodePort[];
  createdAt: string;
  updatedAt: string;
  metadata?: Record<string, unknown>;
}

Visual Configuration

Node Appearance

Color Palette (COSMIC_COLORS)

export const COSMIC_COLORS = {
  // Node colors
  sunCore: '#fbbf24',           // platform-root (Universe Core)
  galaxyCore: '#8b5cf6',        // galaxy
  worldSurface: '#14b8a6',      // world
  pageModuleSurface: '#3b82f6', // page-module
  deprecatedPage: '#64748b',    // page (deprecated)

  // Connection colors
  hierarchyLine: '#6366f1',
  routeLine: '#22c55e',
  dataFlowLine: '#f59e0b',
  dependencyLine: '#ef4444',

  // Backgrounds
  void: '#000000',
  deepSpace: '#0a0a1a',
  nebulaDark: '#0f172a',
  nebulaLight: '#1e293b'
};

Integration with Modular-Universe

How Nodes Map to Runtime

Universe Architect (Design Time)          Modular Universe (Runtime)
─────────────────────────────────         ─────────────────────────────
Galaxy: "Admin" ──────────────────────►   CanvasSection with template
  │                                         ├── Region: sidebar (NavModule)
  │                                         └── Region: main (router-outlet)
  │
  └── World: "Members" ───────────────►   Route group + shared context
        │
        ├── Page-Module: "List" ──────►   PageModuleRendererComponent
        │     pageId: "member-list"         └── Renders DataTable widget
        │
        └── Page-Module: "Detail" ────►   PageModuleRendererComponent
              pageId: "member-detail"       └── Renders EntityCard widget

Layout Templates

File Locations Summary

Core Type Definitions

libs/libs-foundational/core-models/src/lib/types/
├── modules/
│   ├── modules.types.ts              # ModuleType, CoreModuleType
│   └── universal-module.types.ts     # UniversalModule interface
├── multiverse.types.ts               # Universe, Galaxy, Planet
└── space-map/
    └── space-entities.types.ts       # GalaxyGroup, UniverseGroup

Canvas/Visual Types

libs/libs-space/universe-architect/src/lib/
├── types/
│   ├── cosmic-node.types.ts          # CosmicNodeType, CosmicNode, COSMIC_NODE_CONFIGS
│   └── connection.types.ts           # NodePort, Connection types
└── services/
    └── architect-module-converter.service.ts  # Type conversion logic

AI Generation

libs/libs-ai/gograb-ai/src/lib/services/
└── ai-module-generator.service.ts    # Generates hierarchy from prompts

apis/backend-ai-api/src/app/workflow/services/
└── vibe-workflow-orchestrator.service.ts  # Orchestrates generation flow

Deprecation Notes

page Type

• Status: DEPRECATED as of Session 32.2
• Replacement: Use page-module instead
• Reason: page-module clearly indicates a page that references widget content via pageId
• Migration: Existing page nodes will continue to work but should be migrated

Planet Interface

• Status: DEPRECATED
• Location: multiverse.types.ts
• Note: Legacy concept from early multiverse design, now replaced by page-module

Quick Reference

Creating a New Module Hierarchy

1. Galaxy (Application Section)

   • Set moduleType: 'galaxy'
   • Define layout.template
   • Set root route (e.g., /admin)

2. World (Feature Group)

   • Set moduleType: 'world'
   • Set parentId to galaxy
   • Define metadata.entityId
   • Set relative route (e.g., members)

3. Page-Module (Actual Page)

   • Set moduleType: 'page-module'
   • Set parentId to world
   • Set pageId to reference Page document
   • Define route segment (e.g., :id)

Type Checking

// Check if node can have children
const config = COSMIC_NODE_CONFIGS[node.type];
const canHaveChildren = config.behavior.canHaveChildren;
const allowedChildTypes = config.behavior.allowedChildTypes;

Version History