Singularity & Space-Map Architecture - Critical Separation

Date: October 12, 2025
Status: ✅ Architecture Corrected
Author: Ferrari Vibe Coding Team

The Problem (Before)

We were duplicating universe management between two libraries:

• space-map-lib had UniverseGroup (from @core)
• singularity-lib created its own Universe type and UniverseManagerService

This caused confusion and code duplication!

The Solution (After)

Clear separation of concerns:

space-map-lib: Organizational Structure

Purpose: Manage spatial/organizational hierarchy
Responsibilities:

• ✅ Create, update, delete Universes (UniverseGroup)
• ✅ Create, update, delete Galaxies (GalaxyGroup)
• ✅ Create, update, delete Worlds/Pages (WorldNode)
• ✅ Organize hierarchical relationships
• ✅ Provide navigation and visualization

Key Type: UniverseGroup from @core

singularity-lib: Functional Logic

Purpose: Build and execute logic flows
Responsibilities:

• ✅ Create, update, delete Logic Blocks
• ✅ Create, update, delete Logic Flows
• ✅ Create, update, delete Flow Compositions
• ✅ Execute logic and handle data flow
• ✅ Reference space-map universes (by ID only)

Key Types:

• LogicBlock, LogicFlow, FlowComposition
• UniverseLogicMetadata (metadata only, NOT universe management!)

Architecture Diagram

┌─────────────────────────────────────────────┐
│           USER'S GOGRAB SPACE               │
└─────────────────────────────────────────────┘
                    │
        ┌───────────┴────────────┐
        │                        │
        ▼                        ▼
┌──────────────┐        ┌──────────────────┐
│ space-map-lib │        │ singularity-lib  │
│  (Structure)  │        │    (Logic)       │
└──────────────┘        └──────────────────┘
        │                        │
        │ Creates/Manages        │ References by ID
        ▼                        ▼
┌──────────────┐        ┌──────────────────┐
│  Universe    │←──────│  universeId:     │
│  (UniverseG roup)    │  string          │
│              │        │                  │
│  ├─ Galaxy  │        │  LogicFlow:      │
│  │  └─ World│        │    universeId    │
│  └─ Galaxy  │        │                  │
│     └─ World│        │  FlowComposition:│
└──────────────┘        │    universeId    │
                        └──────────────────┘

Key Changes Made

1. Removed from singularity-lib ❌

• Universe interface (deleted)
• UniverseExport interface (replaced with UniverseLogicExport)
• UniverseManagerService (deleted)

2. Added to singularity-lib ✅

• UniverseLogicMetadata - tracks logic per universe (NOT universe itself!)
• UniverseLogicExport - exports logic for a universe
• LogicShareRequest - shares logic between universes

3. Updated Components ✅

• UniverseDashboardComponent:
  • Now displays logic metadata for space-map universes
  • Does NOT create/edit/delete universes
  • Redirects to space-map for universe management

4. Integration Pattern ✅

Correct way to integrate:

// In singularity-lib component/service
import { UniverseGroup } from '@libs-foundational/core-models'; 
import { SpaceMapFlashStateService } from '@space-map-lib';

@Component({...})
export class MySingularityComponent {
  // ✅ Get universes from space-map
  private spaceMap = inject(SpaceMapFlashStateService);
  readonly universes = this.spaceMap.universes;
  
  // ✅ Reference universes by ID
  async loadFlowsForUniverse(universeId: string) {
    const flows = await this.dbService.getLogicTrees().toPromise();
    return flows.filter(f => f.universeId === universeId);
  }
  
  // ❌ NEVER create universes in singularity
  // createUniverse() { ... } // NO!
}

Data Flow

Creating a Universe

User → space-map-lib → Create UniverseGroup → Storage
                                   ↓
                      Space-map UI shows universe

Creating Logic in a Universe

User → singularity-lib → Create LogicFlow
                           with universeId
                                   ↓
                      Singularity saves flow
                                   ↓
                      References space-map universe

Viewing Universes with Logic

space-map-lib provides: UniverseGroup[]
singularity-lib provides: UniverseLogicMetadata[]
                                   ↓
                      UI combines both for display

Storage Architecture

space-map-lib Storage Keys

'space-map/universes'     // UniverseGroup[]
'space-map/galaxies'      // GalaxyGroup[]
'space-map/worlds'        // WorldNode[]
'space-map/selected-universe'

singularity-lib Storage Keys

'singularity:flow:{id}'          // LogicFlow
'singularity:composition:{id}'   // FlowComposition
'singularity:block:{id}'         // BlockTemplate
// NOTE: Flows have .universeId that references space-map

Multi-Verse Concept (Corrected)

Users can have multiple universes, and logic can be organized per universe:

User
├── Universe 1 (Personal Projects)  ← space-map-lib
│   ├── Galaxy: E-commerce
│   │   └── World: Admin Panel
│   └── LOGIC:                      ← singularity-lib
│       ├── Flow: User Auth (universeId: universe-1)
│       └── Flow: Payment (universeId: universe-1)
│
└── Universe 2 (Client Work)        ← space-map-lib
    ├── Galaxy: CRM
    │   └── World: Dashboard
    └── LOGIC:                      ← singularity-lib
        ├── Flow: User Auth (SHARED from Universe 1!)
        └── Flow: Custom CRM Logic (universeId: universe-2)

Benefits of This Architecture

1. No Duplication: Universe management exists only in space-map-lib
2. Clear Separation: space-map = structure, singularity = logic
3. Better Integration: Singularity enhances space-map, doesn't replace it
4. Reusability: Logic can be shared across space-map universes
5. Maintainability: Each library has a single, clear purpose

Migration Guide

If you have old code using singularity's universe management:

Before (❌ Wrong)

// In singularity component
import { Universe } from '@libs-structural/singularity-lib';
import { UniverseManagerService } from '@libs-structural/singularity-lib';

// Creating universe in singularity - WRONG!
await this.universeManager.createUniverse({ name: 'My Universe' });

After (✅ Correct)

// In space-map component
import { UniverseGroup } from '@libs-foundational/core-models'; 
import { SpaceMapFlashStateService } from '@space-map-lib';

// Creating universe in space-map - CORRECT!
await this.spaceMap.createUniverse({ name: 'My Universe' });

// Then in singularity, just reference it
const flows = await this.getFlowsForUniverse(universeId);

Related Documentation

• space-map-lib/README.md - Organizational structure management
• singularity-lib/README.md - Logic flow building
• @core types - Shared types (UniverseGroup, GalaxyGroup, WorldNode)

Questions?

Q: Can singularity create universes?
A: No! Use space-map-lib for universe management.

Q: Can singularity see which universes exist?
A: Yes! Inject SpaceMapFlashStateService to read universes.

Q: Can logic flows exist in multiple universes?
A: Yes! Share flows using LogicShareRequest.

Q: Where are universe themes/branding stored?
A: In space-map's UniverseGroup, not in singularity.

Remember: space-map-lib owns the structure, singularity-lib owns the logic. 🚀