GoGrab Space Ecosystem Integration Overview

Last Updated: October 10, 2025
Version: 1.0.0
Status: Production Ready (Phase 1-4 Complete)

🎯 Vision

The GoGrab Space ecosystem is a unified platform where:

• Singularity orchestrates logic and connects everything
• Editor-web creates visual content (pages)
• Space-map organizes and visualizes the universe (worlds, galaxies, universes)
• Storage-system handles all persistence with user-level segregation
• Everything works together seamlessly through shared services and event-driven architecture

📐 Architecture

Core Layers

┌─────────────────────────────────────────────────────────────┐
│                    User Applications                         │
│  ┌────────────┐  ┌────────────┐  ┌─────────────────────┐   │
│  │  Editor    │  │ Space Map  │  │   Singularity       │   │
│  │  (Pages)   │  │  (Worlds)  │  │  (Logic Flows)      │   │
│  └────────────┘  └────────────┘  └─────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│              Integration & Orchestration Layer               │
│  ┌──────────────────────────────────────────────────────┐   │
│  │     OrchestrationService (Event Bus)                 │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │   │
│  │  │  Editor  │  │Space-Map │  │    Storage       │  │   │
│  │  │  Bridge  │  │  Bridge  │  │    Bridge        │  │   │
│  │  └──────────┘  └──────────┘  └──────────────────┘  │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │     PageWorldSyncService (Editor ↔ Space-Map)      │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │   ContentRegistryService (Content Discovery)       │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │   UnifiedNavigationService (Routing)                │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│              Storage & Persistence Layer                     │
│  ┌──────────────────────────────────────────────────────┐   │
│  │   UserContextService (User/Space Context)           │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │   UserDatabaseManager (Per-User Databases)          │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │   GgStorage with Scoped Keys                        │   │
│  │   (OPFS, IndexedDB, localStorage)                   │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

🎨 Key Features Implemented

1. User-Level Data Segregation

All data is automatically scoped by user and space:

// Key Format: user/{userId}/space/{spaceId}/{key}
// Example: "user/abc123/space/main/pages/home"

Benefits:

• Complete data isolation between users
• Multi-space support per user
• Automatic context-aware storage
• Cross-tab synchronization

Implementation:

• UserContextService - Manages active user/space context
• scopeKey() / unscopeKey() - Automatic key scoping
• UserDatabaseManager - Per-user/space database instances
• UserScopedStorage - Context-aware storage wrapper

2. Event-Driven Orchestration

Central event bus connecting all systems:

// Emit events
orchestration.emit('page-created', 'editor', pageData);

// Listen to events
orchestration.on('page-created', (event) => {
  // React to page creation
});

// Register workflows
orchestration.registerWorkflow({
  id: 'auto-create-world',
  trigger: { eventType: 'page-created' },
  actions: [/* ... */]
});

Event Types:

• page-created, page-updated, page-deleted
• world-created, world-updated, world-deleted
• logic-executed, logic-attached, logic-detached
• sync-started, sync-complete, sync-failed

Bridges:

• EditorBridge - Editor ↔ Orchestration
• SpaceMapBridge - Space-Map ↔ Orchestration
• StorageBridge - Storage ↔ Orchestration

3. Page-World Synchronization

Automatic bidirectional sync between editor pages and space-map worlds:

// Sync page to world
const world = await pageWorldSync.syncPageToWorld(page);

// Check sync status
const hasWorld = pageWorldSync.hasWorldForPage(pageId);
const worldId = pageWorldSync.getWorldIdForPage(pageId);

Features:

• Automatic mapping management
• Bidirectional synchronization
• Sync event tracking
• Configurable sync behavior

4. Content Discovery

Unified registry for all content with advanced search:

// Register content
contentRegistry.register({
  id: 'page-1',
  type: 'page',
  title: 'Home Page',
  tags: ['landing', 'public'],
  status: 'published',
  // ...
});

// Search content
const results = contentRegistry.search({
  text: 'home',
  types: ['page'],
  tags: ['public'],
  sortBy: 'updatedAt'
});

Features:

• Multi-type content tracking (pages, worlds, logic flows, etc.)
• Full-text search
• Tag and category filtering
• Automatic indexing
• Preview generation integration

5. Unified Navigation

Context-aware routing across all apps:

// Navigate to editor with page
navigation.toEditor({ pageId: 'page-1' });

// Navigate to space map with world
navigation.toSpaceMap({ worldId: 'world-1', galaxyId: 'galaxy-1' });

// Deep linking
const link = navigation.getDeepLink({
  type: 'page',
  id: 'page-1',
  action: 'edit'
});

Features:

• Context preservation
• Navigation history
• Breadcrumb generation
• Deep link support
• Query parameter management

🔧 Component Integration

Editor Integration

Space Integration Panel: Display and manage page's space map location

<gg-space-integration-panel [page]="currentPage()">
</gg-space-integration-panel>

Features:

• Shows current space location
• Assign to universes/galaxies
• Quick link to space map
• Sync status indicator

Space-Map Integration

World Details: Connect worlds back to editor pages

// Navigate to editor from world
navigation.toEditor({ pageId: world.coreWorldId });

Content Browsing

Content Browser Component: Browse all user content

<gg-content-browser></gg-content-browser>

Features:

• Grid and list views
• Advanced filtering
• Preview thumbnails
• Quick actions (view, edit, delete, share)

📊 Data Flow Examples

Creating a Page and Connecting to Space Map

// 1. Create page in editor
const page = createPage({ title: 'My Page', widgets: [...] });

// 2. Save page (triggers event)
editorBridge.notifyPageCreated({
  pageId: page.id,
  title: page.title,
  slug: page.slug,
  widgets: page.widgets
});

// 3. Assign to space map
const updatedPage = {
  ...page,
  cosmos: {
    galaxies: [{ id: 'galaxy-1', name: 'Alpha Galaxy' }],
    world: { id: 'universe-1', name: 'Main Universe' }
  }
};

// 4. Sync creates world
const world = await pageWorldSync.syncPageToWorld(updatedPage);

// 5. World is now visible in space map
navigation.toSpaceMap({ worldId: world.id });

User Context and Data Isolation

// 1. User logs in
userContext.setUserContext({
  userId: 'user-123',
  spaceId: 'my-space',
  permissions: ['read', 'write']
});

// 2. All storage operations are automatically scoped
await storage.put('pages/home', pageData);
// Actually stored as: "user/user-123/space/my-space/pages/home"

// 3. User switches space
userContext.setActiveSpace('another-space');

// 4. Storage now points to different data
const data = await storage.get('pages/home');
// Reads from: "user/user-123/space/another-space/pages/home"

🚀 Performance

• Cache Hit: 0.3ms average (maintained from storage-system)
• Sync Overhead: < 10ms for typical page-world sync
• Event Propagation: < 5ms between systems
• Zero Breaking Changes: All existing features continue working

📝 Best Practices

1. Always Use Orchestration Events

✅ Do:

editorBridge.notifyPageCreated(pageData);

❌ Don't:

// Direct service calls without events
spaceMapService.createWorld(pageData);

2. Leverage User Context

✅ Do:

const storage = inject(UserScopedStorage);
await storage.put('my-data', data); // Automatically scoped

❌ Don't:

// Manual key scoping
await storage.put(`user/${userId}/space/${spaceId}/my-data`, data);

3. Register Content for Discovery

✅ Do:

contentRegistry.register({
  id: page.id,
  type: 'page',
  title: page.title,
  tags: ['public', 'landing'],
  status: 'published'
});

4. Use Navigation Service

✅ Do:

navigation.toEditor({ pageId: 'page-1' });

❌ Don't:

router.navigate(['/editor/editor'], { queryParams: { pageId: 'page-1' } });

🧪 Testing Integration

describe('Ecosystem Integration', () => {
  it('should sync page to world', async () => {
    const page = createTestPage();
    const world = await pageWorldSync.syncPageToWorld(page);
    expect(world.coreWorldId).toBe(page.id);
  });

  it('should maintain user context', () => {
    userContext.setUserContext({ userId: 'test', spaceId: 'test' });
    const key = 'test-key';
    const scopedKey = scopeKey(key, 'test', 'test');
    expect(scopedKey).toBe('user/test/space/test/test-key');
  });

  it('should emit orchestration events', (done) => {
    orchestration.on('page-created', (event) => {
      expect(event.type).toBe('page-created');
      done();
    });
    editorBridge.notifyPageCreated({ pageId: 'test', title: 'Test' });
  });
});

🔍 Troubleshooting

Issue: Page not appearing in space map

Solution:

1. Check sync service is enabled: pageWorldSync.config().enabled
2. Verify page has cosmos data: page.cosmos.galaxies
3. Check sync events: pageWorldSync.events$.subscribe(console.log)

Issue: User data appearing for wrong user

Solution:

1. Verify user context: userContext.userContext()
2. Check key scoping: scopeKey('test', userId, spaceId)
3. Clear context and re-login

Issue: Orchestration events not firing

Solution:

1. Check bridge is injected properly
2. Verify event type is correct
3. Enable monitoring: orchestration.setMonitoring(true)

📚 Additional Resources

• User Data Segregation Guide
• Content Creation Flow
• Orchestration Guide
• Editor Integration
• Space Map Integration

🎓 Next Steps

1. MongoDB Integration - Add MongoDB sync for cloud persistence
2. Logic Integration - Attach logic flows to pages
3. Content Gallery - Build beautiful showcase with video previews
4. Advanced Workflows - Create complex orchestration workflows
5. Real-time Collaboration - Multi-user editing with sync

Built with: Angular 20 Signals, Standalone Components, Flash State Management
Maintained by: GoGrab Space Team
License: Proprietary