Structural Libraries - Master Architecture Guide

Version: 2.0
Last Updated: October 23, 2025
Status: 🔒 CRITICAL - DO NOT MODIFY WITHOUT REVIEW

Purpose of This Document

This document defines the EXACT responsibilities of each structural NX library in our Ferrari Vibe Coding platform. It exists to prevent code duplication and ensure clear separation of concerns.

⚠️ IMPORTANT: Before adding ANY feature to ANY library, consult this document first!

Current Architecture Overview

Applications (Frontend & Backend)

┌──────────────────────────────────────────────────────┐
│              GOGRAB SPACE PLATFORM                   │
├──────────────────────────────────────────────────────┤
│ gograb-space     Main frontend (Port 9100)          │
│ backend-api      API server (Port varies)           │
│ docs-angular     Documentation showcase (Port 5010) │
│ space-admin      Space management (Just started)    │
└──────────────────────────────────────────────────────┘

Library Organization

┌─────────────────────────────────────────────────────────┐
│              STRUCTURAL LIBRARIES                       │
│  ┌───────────────────────────────────────────────┐    │
│  │  space-map-lib (ORGANIZATIONAL)               │    │
│  │  Universes → Galaxies → Worlds (Pages)        │    │
│  │  Loaded via lazy routes in gograb-space       │    │
│  └───────────────────────────────────────────────┘    │
│                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────┐ │
│  │ singularity  │  │ editor-web   │  │  ux-test    │ │
│  │    -lib      │  │    -lib      │  │    -lib     │ │
│  │   (LOGIC)    │  │  (BUILDER)   │  │  (UI/UX)    │ │
│  │ Blocks→Flows │  │ Page Editor  │  │ Components  │ │
│  └──────────────┘  └──────────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────────┘

Key Change: All former apps (ux-test, space-map, editor-web, singularity) have been converted to libraries and are now loaded as lazy-loaded feature modules within the main gograb-space application.

Complete Library Inventory

📊 Total: 42 Libraries (All building successfully)

🏗️ STRUCTURAL LIBRARIES (libs/structural/ - 4 libraries)

These provide the core functionality previously in separate apps:

🎯 CORE LIBRARIES (libs/core/ - 2 libraries)

Foundation utilities and adapters:

💎 FOUNDATIONAL LIBRARIES (libs/foundational/ - 4 libraries)

Critical system-wide infrastructure:

🎨 UI LIBRARIES (libs/ui/ - 18 libraries)

User interface components and widgets:

🔧 OTHER LIBRARIES (libs/ - 14 libraries)

Specialized functionality and effects:

1. space-map-lib 🗺️

Responsibility: Organizational Structure & Navigation

What it DOES:

• ✅ Manages user's organizational hierarchy (Universes → Galaxies → Worlds)
• ✅ Creates, updates, deletes universes, galaxies, and worlds
• ✅ Provides navigation between pages (worlds)
• ✅ Manages hierarchical relationships
• ✅ Provides visualization of space structure (tree view, grid view, analytics)
• ✅ Handles universe/galaxy/world metadata (name, description, branding)
• ✅ Manages theme and branding at universe level

What it DOES NOT:

• ❌ Build page content (that's editor-web-lib)
• ❌ Manage logic flows (that's singularity-lib)
• ❌ Create UI components/widgets (that's ux-test-lib)
• ❌ Execute logic blocks
• ❌ Generate AI content

Key Types & Models

// Primary entities (from @core)
- UniverseGroup: Container for galaxies
- GalaxyGroup: Container for worlds
- WorldNode: Represents a page

// Services
- UniverseManagerService: CRUD for universes
- GalaxyManagerService: CRUD for galaxies
- WorldManagerService: CRUD for worlds
- SpaceMapFlashStateService: Flash persistence for space state
- UnifiedNavigationService: Navigate between worlds

Storage Keys Pattern

'space-map:universe:{id}'
'space-map:galaxy:{id}'
'space-map:world:{id}'
'space-map:current-context'

Example Usage

// Creating a new universe
const universe = await universeManager.createUniverse({
  name: 'My E-commerce Platform',
  description: 'Online store and admin',
  theme: { primary: '#FF6B6B', secondary: '#4ECDC4' }
});

// Adding a galaxy (app section)
const galaxy = await galaxyManager.createGalaxy({
  universeId: universe.id,
  name: 'Customer Portal',
  description: 'Public-facing pages'
});

// Adding a world (page)
const world = await worldManager.createWorld({
  galaxyId: galaxy.id,
  name: 'Product Catalog',
  path: '/products'
});

2. singularity-lib ⚛️

Responsibility: Logic Building & Flow Composition

What it DOES:

• ✅ Manages logic blocks (data operations, API calls, transformations)
• ✅ Composes blocks into flows
• ✅ Composes flows into larger systems (flow compositions)
• ✅ Executes logic with orchestration engine
• ✅ AI-powered logic generation
• ✅ Stores logic metadata BY universe ID (references space-map universes)
• ✅ Provides visual logic builder UI
• ✅ Provides flow composer UI

What it DOES NOT:

• ❌ Create or manage universes (that's space-map-lib)
• ❌ Build page layouts (that's editor-web-lib)
• ❌ Create UI widgets (that's ux-test-lib)
• ❌ Manage navigation structure

Key Types & Models

// Logic entities
- BlockTemplate: Single logic operation
- LogicFlow: Sequence of connected blocks
- FlowComposition: Connected flows creating a system
- LogicTree: Persisted flow structure

// Metadata (references space-map)
- UniverseLogicMetadata: Logic stats for a universe
  {
    universeId: string;        // Reference to space-map universe
    flowCount: number;
    blockCount: number;
    compositionCount: number;
  }

Services

- LogicBuilderDatabaseService: CRUD for flows and blocks
- LogicExecutionEngineService: Execute flows
- OrchestrationService: Complex execution patterns
- LogicAIService: AI-powered logic generation
- AICodeReviewService: Review logic quality
- ConversationalFlowBuilderService: Build flows via chat

Storage Keys Pattern

'singularity:logic-tree:{id}'
'singularity:block-template:{id}'
'singularity:flow-composition:{id}'
'singularity:metadata:universe:{universeId}'

Example Usage

// Create a logic flow (associated with a space-map universe)
const flow = await dbService.createLogicTree({
  name: 'Product Validation',
  universeId: 'universe-123',  // ✅ References space-map universe
  blocks: [
    { type: 'validator', id: '1', config: { field: 'price' } },
    { type: 'transformer', id: '2', config: { operation: 'format' } }
  ],
  connections: [
    { from: '1', to: '2' }
  ]
});

// Execute the flow
const result = await executionEngine.executeFlow(flow.id);

Integration with space-map

// ✅ CORRECT: Reference universe by ID
const logicMeta: UniverseLogicMetadata = {
  universeId: spaceMapUniverse.id,
  flowCount: 5,
  blockCount: 23
};

// ❌ WRONG: Don't duplicate universe management
// Never create universe objects in singularity!

3. editor-web-lib 🏗️

Responsibility: Page Builder & Content Editor

What it DOES:

• ✅ Builds page layouts (drag-drop editor)
• ✅ Manages widgets on pages
• ✅ Configures widget properties
• ✅ Handles page-level styling
• ✅ Manages page state and data binding
• ✅ Provides visual page editor UI
• ✅ Generates page HTML/templates
• ✅ Page preview and responsive testing

What it DOES NOT:

• ❌ Create universes/galaxies/worlds structure (that's space-map-lib)
• ❌ Build custom logic flows (that's singularity-lib)
• ❌ Design reusable UI components (that's ux-test-lib)
• ❌ Manage navigation between pages

Key Types & Models

// Page entities
- PageNode: Complete page definition
- PageLayout: Grid/flex layout configuration
- WidgetInstance: Widget placed on page
  {
    widgetTypeId: string;    // References ux-test widget
    position: GridPosition;
    config: WidgetConfig;
  }

// Editor state
- EditorState: Current editing session
- PageTemplate: Reusable page structure

Services

- PageBuilderService: Build and edit pages
- WidgetPlacementService: Drag-drop widgets
- DataBindingService: Bind widgets to data sources
- ResponsiveEditorService: Handle breakpoints
- PagePreviewService: Live preview

Storage Keys Pattern

'editor-web:page:{worldId}'           // Page content for a world
'editor-web:template:{id}'            // Reusable templates
'editor-web:autosave:{worldId}'       // Auto-saved drafts

Example Usage

// Build a page for a world (from space-map)
const page = await pageBuilder.buildPage({
  worldId: 'world-456',     // ✅ References space-map world
  template: 'ecommerce-product-page',
  widgets: [
    {
      type: 'product-gallery',  // ✅ References ux-test widget
      position: { row: 0, col: 0, span: 6 },
      config: { imageSize: 'large' }
    },
    {
      type: 'add-to-cart-button',
      position: { row: 0, col: 6, span: 6 },
      bindings: {
        onClick: 'singularity-flow-id-789'  // ✅ References singularity logic
      }
    }
  ]
});

Integration with Other Libraries

// ✅ References space-map world
page.worldId = worldNode.id;

// ✅ Uses ux-test widgets
page.widgets = [{ type: 'card', ... }];

// ✅ Binds to singularity logic
widget.onClick = singularityFlow.id;

4. ux-test-lib 🎨

Responsibility: UI/UX Components & Design System

Status: 🔄 Transitioning to ui-builder - Being refactored for better UX testing workflow

What it DOES:

• ✅ Creates reusable UI components (inputs, buttons, cards, modals)
• ✅ Manages component library showcase
• ✅ Provides theme customization demos
• ✅ Component testing and preview playground
• ✅ Exports components for use in pages
• ✅ Visual component builder demonstrations
• ✅ AI-powered theme generation showcase
• ✅ Widget gallery and testing environment

What it DOES NOT:

• ❌ Build production pages (that's editor-web-lib)
• ❌ Manage page navigation structure (that's space-map-lib)
• ❌ Handle business logic (that's singularity-lib)
• ❌ Create production application structure

Route Integration:

// In gograb-space/src/app/ui-builder/ui-builder.routes.ts
export const UiBuilderRoutes: Routes = [
  { path: '', redirectTo: 'home', pathMatch: 'full' },
  { path: 'home', loadComponent: () => import('./home/home.component') },
  { path: 'ux', children: UX_WIDGET_ROUTES },
  { path: 'themes', children: themeComponentRoutes },
  // ... AI routes, catalog routes, etc.
];

Key Types & Models

// Component entities
- ComponentDefinition: Reusable component spec
  {
    id: string;
    name: string;
    category: 'input' | 'display' | 'layout' | 'navigation';
    props: PropDefinition[];
    template: string;
    styles: string;
  }

- WidgetType: Registered widget in system
- ThemeTokens: Design system variables

Services

- ComponentBuilderService: Create custom components
- ThemeEditorService: Customize themes
- ComponentLibraryService: Manage component catalog
- ComponentPreviewService: Test components

Storage Keys Pattern

'ux-test:component:{id}'
'ux-test:theme:{universeId}'
'ux-test:widget-type:{id}'

Example Usage

// Create a reusable component
const component = await componentBuilder.createComponent({
  name: 'Custom Product Card',
  category: 'display',
  props: [
    { name: 'title', type: 'string', required: true },
    { name: 'price', type: 'number', required: true },
    { name: 'imageUrl', type: 'string' }
  ],
  template: `
    <div class="product-card">
      <img [src]="imageUrl" />
      <h3>{{ title }}</h3>
      <span class="price">{{ price | currency }}</span>
    </div>
  `,
  styles: `
    .product-card {
      border: 1px solid var(--border-color);
      border-radius: var(--radius-md);
      padding: var(--spacing-4);
    }
  `
});

// Register as widget type
await componentLibrary.registerWidget({
  id: 'custom-product-card',
  componentId: component.id,
  availableInUniverses: ['universe-123']  // ✅ Scoped to universe
});

Integration with Other Libraries

// ✅ Used by editor-web-lib
const widgetInstance = {
  widgetTypeId: 'custom-product-card',  // From ux-test
  position: { ... }
};

// ✅ Styled using universe theme (from space-map)
const theme = universeManager.getUniverseTheme(universeId);
componentBuilder.applyTheme(component, theme);

Cross-Library Integration in gograb-space

How They Work Together in the Main Application

// SCENARIO: User builds an e-commerce product page in gograb-space

// The main application (gograb-space) orchestrates all libraries:

// 1. User navigates to Space Map (lazy-loaded space-map-lib)
// Route: /space-map
const universe = await spaceMapService.createUniverse({ name: 'E-commerce' });
const galaxy = await spaceMapService.createGalaxy({ 
  universeId: universe.id, 
  name: 'Store' 
});
const world = await spaceMapService.createWorld({ 
  galaxyId: galaxy.id, 
  name: 'Products' 
});

// 2. User navigates to UI Builder (lazy-loaded ux-test-lib)
// Route: /ux/widgets
const productCard = await componentService.createComponent({
  name: 'ProductCard',
  props: ['title', 'price', 'image']
});

// 3. User navigates to Singularity (lazy-loaded singularity-lib)
// Route: /singularity/logic-builder
const addToCartFlow = await logicService.createLogicFlow({
  universeId: universe.id,
  name: 'Add To Cart',
  blocks: [
    { type: 'validate-stock' },
    { type: 'update-cart' },
    { type: 'show-notification' }
  ]
});

// 4. User navigates to Editor (lazy-loaded editor-web-lib)
// Route: /editor/workspace
const page = await pageBuilder.buildPage({
  worldId: world.id,
  widgets: [
    {
      type: productCard.id,        // ✅ From ux-test-lib
      bindings: {
        onClick: addToCartFlow.id  // ✅ From singularity-lib
      }
    }
  ]
});

// 5. Result: Complete functional page with seamless cross-library integration
// All within a single gograb-space application, with instant navigation

Shared Services Across Libraries

All structural libraries share foundational services:

// Shared across all structural libraries
import { StorageService } from '@storage-system';
import { ThemeManagerService } from '@theme-system';
import { AIFactoryService } from '@gograb-ai';
import type { SafeAny } from '@libs-foundational/core-models';

// Each library uses these consistently:
// - StorageService for persistence
// - ThemeManagerService for theming
// - AIFactoryService for AI features
// - Core types for type safety

Rules to Prevent Duplication

⚠️ NEVER DO THIS

// ❌ Don't create universes in singularity
// singularity-lib/services/universe-manager.service.ts
export class UniverseManagerService {
  createUniverse() { ... }  // ❌ WRONG! Use space-map!
}

// ❌ Don't build pages in singularity
// singularity-lib/services/page-builder.service.ts
export class PageBuilderService {
  buildPage() { ... }  // ❌ WRONG! Use editor-web!
}

// ❌ Don't create widgets in editor-web
// editor-web-lib/services/widget-factory.service.ts
export class WidgetFactoryService {
  createWidget() { ... }  // ❌ WRONG! Use ux-test!
}

✅ ALWAYS DO THIS

// ✅ Reference by ID across libraries
interface LogicFlowMetadata {
  universeId: string;  // ✅ References space-map universe
}

interface PageDefinition {
  worldId: string;     // ✅ References space-map world
  widgets: {
    typeId: string;    // ✅ References ux-test component
    onClick: string;   // ✅ References singularity flow
  }[];
}

Decision Matrix

"Where should I add this feature?"

Storage Namespace Rules

Each library MUST use its own namespace prefix:

// space-map-lib
'space-map:universe:{id}'
'space-map:galaxy:{id}'
'space-map:world:{id}'

// singularity-lib
'singularity:logic-tree:{id}'
'singularity:flow:{id}'

// editor-web-lib
'editor-web:page:{worldId}'
'editor-web:template:{id}'

// ux-test-lib
'ux-test:component:{id}'
'ux-test:theme:{id}'

Benefits:

• ✅ Clear ownership
• ✅ Easy to query by library
• ✅ No key conflicts
• ✅ Simple debugging

Migration from Old Architecture

Before (Wrong)

// singularity had its own Universe type ❌
interface Universe {
  id: string;
  name: string;
  flows: LogicFlow[];
}

After (Correct)

// singularity references space-map universes ✅
interface UniverseLogicMetadata {
  universeId: string;  // Reference only!
  flowCount: number;
}

// Get universe details from space-map
const universe = await spaceMap.getUniverse(metadata.universeId);

Enforcement Checklist

Before adding ANY feature, verify:

• I checked this master guide first
• This feature belongs in the correct library
• I'm not duplicating functionality from another library
• I'm using reference IDs (not duplicating entities)
• I'm using the correct storage namespace
• I updated this document if needed

Questions?

Q: "Where does authentication belong?"
A: core library (shared by all)

Q: "Where does AI integration belong?"
A: gograb-ai library (used by all structural libs)

Q: "Where does storage system belong?"
A: storage-system library (used by all)

Q: "Can singularity create pages?"
A: NO! It can generate logic that pages USE.

Q: "Can space-map execute logic?"
A: NO! It can trigger singularity flows by ID.

Q: "Can ux-test build complete pages?"
A: NO! It creates COMPONENTS that editor-web uses.

gograb-space Application Routes

All structural libraries are integrated via lazy-loaded routes in the main gograb-space application:

// apps/gograb-space/src/app/app.routes.ts
export const appRoutes: Route[] = [
  // Main dashboard
  { path: '', redirectTo: 'home', pathMatch: 'full' },
  
  // UI Builder (ux-test-lib)
  {
    path: 'ux',
    loadChildren: () => import('./ui-builder/ui-builder.routes').then(m => m.UiBuilderRoutes)
  },
  
  // Space Map (space-map-lib)
  {
    path: 'space-map',
    loadChildren: () => import('@space-map-lib').then(m => m.spaceMapRoutes)
  },
  
  // Editor (editor-web-lib)
  {
    path: 'editor',
    loadChildren: () => import('@editor-web-lib').then(m => m.EditorRoutes)
  },
  
  // Singularity (singularity-lib)
  {
    path: 'singularity',
    loadChildren: () => import('@singularity-lib').then(m => m.SingularityRoutes)
  }
];

Change Log

• 2025-10-23: Major architectural update (v2.0)

  • Converted apps to libraries (ux-test, space-map, editor-web, singularity → libs)
  • All features now lazy-loaded in single gograb-space application
  • Added comprehensive library inventory (42 libraries total)
  • Updated integration patterns for unified app architecture
  • Documented route structure for library integration

• 2025-10-12: Initial version created (v1.0)

  • Fixed universe duplication between space-map and singularity
  • Defined clear boundaries for all structural libraries
  • Established storage namespace conventions

REMEMBER: This is a living document. Update it when adding new structural libraries or changing responsibilities!