COMPLETE ARCHITECTURE ANALYSIS

Ecosistema completo para organización y gestión de contenido con interfaces espaciales

GoGrab Space - Complete Architecture Analysis

Date: October 28, 2025
Purpose: Comprehensive mapping of all systems before final reorganization
Status: 🔄 IN PROGRESS

1. NX Libraries Inventory (40+ Libraries)

Core Infrastructure Libraries

1.1 Storage & Persistence

1.2 Models & Types

1.3 Module System

Platform Tools (Main Features)

2.1 Editor System

2.2 Widget System

2.3 Singularity (Logic Builder)

2.4 Modularity (Module Packager)

2.5 Space Map (Universe Management)

2.6 Launch Station (Deployment)

UI/UX Libraries

3.1 Design System

3.2 Component Libraries

3.3 Testing & Development

Specialized Libraries

4.1 AI & Intelligence

4.2 Visual & Animation

4.3 Backend & Security

4.4 Other Specialized

2. Storage System - Three-Tier Architecture

Flash Persistence Core (autoFlashState)

Three-Tier Data Model (CONCEPTUAL - NEEDS IMPLEMENTATION)

Currently, storage is namespaced by key prefixes:

RECOMMENDATION: Implement explicit GgStorage namespaces:

// Global tier (shared across all spaces)
storage.global.put('widget-templates', templates);

// Space tier (shared across all universes in a space)
storage.space(spaceId).put('custom-widgets', widgets);

// Private tier (universe-specific)
storage.private(universeId).put('draft-pages', pages);

Backend Sync Points

3. Widget Input/Output System

ComponentInput Interface

// libs/core-models/src/lib/types/component.types.ts
export interface ComponentInput {
  name: string;
  type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'any';
  description?: string;
  default?: any;
  required?: boolean;
  validator?: string; // JSON schema or function string
}

ComponentOutput Interface

export interface ComponentOutput {
  name: string;
  type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'any';
  description?: string;
}

UXFrameworkInput/Output (for advanced widgets)

// libs/core-models/src/lib/types/widget-generation.types.ts
export interface UXFrameworkInput {
  name: string;
  type: string;
  required: boolean;
  defaultValue?: any;
  description: string;
}

export interface UXFrameworkOutput {
  name: string;
  type: string;
  description: string;
}

Current State: NOT YET CONNECTED

What Needs to Be Built:

  1. FlowAttachmentService - Attach flows to pages
  2. DataPipelineService - Route flow outputs to widget inputs
  3. WidgetDataBinding - Subscribe widgets to data sources
  4. Editor UI - Panel to connect flows to widgets

4. Backend API Structure

Modules

// apis/backend-api/src/app/app.module.ts
@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    MongooseModule.forRootAsync({ ... }), // MongoDB
    ThrottlerModule.forRoot([...]), // Rate limiting
    AuthModule,      // JWT auth, user management
    AIModule,        // AI generation, completions
    StorageModule,   // S3/storage integration
    UniversesModule, // Universe CRUD, deployment
    AssetsModule,    // Asset management
  ]
})

MongoDB Collections (Inferred)

API Endpoints (Need to Verify)

JSON Export/Import Endpoints (NOT IMPLEMENTED)

RECOMMENDATION: Add these endpoints:

5. UI Builder (/ux-test routes)

Purpose

Component showcase and testing environment, NOT the main Editor.

Route Structure

// apps/gograb-space/src/app/ui-builder/ui-builder.routes.ts
/ux-test
  /home → Component Development Hub
  /ux/widgets → Widget demos (button, input, menu, etc.)
  /themes → Theme system showcase
    /editor → Theme Designer
    /picker-demo → Theme Picker
    /utility-classes → 17 utility files
  /ai → AI integration guide and tester
  /storage-inspector → Storage debugging
  /smart-canvas → Smart canvas demo

Key Difference from Editor

Integration with Main System

6. JSON Export/Import System

Current State: PARTIALLY IMPLEMENTED

Module Export (Modularity)

// libs/modularity-lib/src/lib/types/module-config.types.ts
export interface ModuleExport {
  config: ModuleConfig;
  pages: any[]; // Full page data
  flows: any[]; // Full flow data
  exportedAt: string;
  exportVersion: string;
}

Widget Export (Editor)

// Editor's onSave() and onExport() methods create JSON blobs
const exportData = {
  page: currentPage,
  exportedAt: new Date(),
};
const blob = new Blob([JSON.stringify(exportData, null, 2)]);
// Downloads as .json file

Flow Export (Singularity)

// libs/singularity-lib/src/lib/services/flow-export.service.ts
// libs/singularity-lib/src/lib/models/exported-flow.interface.ts

What's Missing

  1. Unified Export Format - Different systems use different JSON structures
  2. Import Mechanisms - Can export, but no UI to import
  3. Vibe Coding Integration - No "paste JSON to create" workflow
  4. Backend Storage - Exports download to disk, not saved to backend

Recommendation: Unified Export System

interface UnifiedExport {
  type: 'widget' | 'page' | 'flow' | 'module' | 'universe';
  id: string;
  name: string;
  version: string;
  data: any; // Type-specific data
  dependencies: { type: string; id: string; }[]; // What this needs
  metadata: {
    exportedAt: string;
    exportedBy: string;
    platform: 'gograb-space';
    platformVersion: string;
  };
}

7. Dashboard Requirements

Current Dashboard (g-space-dashboard.component.ts)

// Signals
readonly userHistory = this.userHistoryService.userHistory;
readonly currentUser = this.authService.user;
readonly universes = this._universesSignal.asReadonly();
readonly hasUniverses = computed(() => this.universes().length > 0);
readonly publishedUniversesCount = computed(() => ...);
readonly draftUniversesCount = computed(() => ...);
readonly showWelcomeFlow = computed(() => ...);

// Features
- User history tracking
- Universe quick access
- Feature cards (Editor, Singularity, Modularity, etc.)
- Welcome flow for first-time users

What Should Be Added

  1. Space-Level Analytics:

    • Total pages across all universes
    • Total flows created
    • Total widgets built
    • Storage usage
    • AI tokens used

  2. Cross-Universe Insights:

    • Most used widgets
    • Most reused modules
    • Popular flows
    • Recently modified assets

  3. Quick Actions:

    • Create new universe
    • Create new page (with universe selector)
    • Create new flow
    • Create new widget

  4. Visual Data:

    • Universe status cards (draft/deployed)
    • Timeline of recent activity
    • Universe thumbnails/previews

8. Complete Route Mapping

Current Route Structure

Main App (apps/gograb-space/src/app/app.routes.ts)

/ → /landing
/landing → Landing page
/auth/* → Authentication routes
/dashboard → Main dashboard (g-space-dashboard)
/universe/create → Universe creation wizard
/ux-test/* → UI Builder (component showcase)
/editor/* → Editor routes (from @editor-web-lib)
/space-map/* → Space Map routes (from @space-map-lib)
/singularity/* → Singularity routes (from @singularity-lib)
/modularity/* → Modularity routes (from @modularity-lib)
/launch-station/* → Launch Station routes (from @launch-station-lib)
/space/widgets → Widgets Manager routes (from @widgets)

Editor Routes (libs/editor-web-lib/src/lib/editor.routes.ts)

/editor
  /:universeIdentifier/workspace → Main editor workspace
  /:universeIdentifier/pages → Page management
  (REMOVED: /:universeIdentifier/widgets)

Proposed New Structure (from gograb-space-route-architecture.plan.md)

Space-Scoped (Reusable):
/space/:spaceSlug → Space overview
/space/:spaceSlug/widgets → Widgets Manager
/space/:spaceSlug/singularity → Singularity
/space/:spaceSlug/modularity → Modularity
/space/:spaceSlug/settings → Space settings

Universe-Scoped (Specific):
/space/:spaceSlug/:universeId → Universe overview (3D space-map)
/space/:spaceSlug/:universeId/editor → Editor (galaxy/world selector)
/space/:spaceSlug/:universeId/editor/:galaxyId → Editor for galaxy
/space/:spaceSlug/:universeId/editor/:galaxyId/:worldId → Edit specific page
/space/:spaceSlug/:universeId/launch → Launch/Deploy
/space/:spaceSlug/:universeId/settings → Universe settings
/space/:spaceSlug/:universeId/:galaxyId → Galaxy settings

Deployed Universes (Subdomains):
universe-slug.gograb.space/ → Deployed universe

Migration Path

  1. Add space-slug resolution (auto-select if user has one space)
  2. Create route guards: SpaceAutoSelectGuard, UniverseContextGuard
  3. Update all tool routes to be relative to space/universe
  4. Add redirects from old routes
  5. Update all navigation links

9. Data Flow Diagrams

1. Widget Creation → Registration → Usage Flow

[User] → [Widgets Manager (/space/widgets)]
  ↓
[Create Widget] → Save to storage (space_custom-widgets)
  ↓
[WidgetModuleLoaderService] loads all widget modules
  ↓
[WidgetRegistryService (@demos-lib)] registers widget
  ↓
[Widget appears in Editor] → widget-library.component.ts
  ↓
[User drags widget to canvas]
  ↓
[EditorService] adds widget to page.widgets[]
  ↓
[Flash Persistence] auto-saves to storage (pages_state)
  ↓
[Backend Sync] (eventual) → MongoDB

2. Module Creation → Packaging → Deployment Flow

[User] → [Modularity (/modularity)]
  ↓
[Tab 1: Select Pages] → Browse Editor pages
[Tab 2: Select Flows] → Browse Singularity flows
[Tab 3: Map Routes] → Define module routes
[Tab 4: Review & Deploy] → Preview + Deploy
  ↓
[ModuleConfig created] → Saved to storage
  ↓
[Build Process] → Packages pages + flows
  ↓
[ModuleManifest generated] → Registered with @module-system
  ↓
[Module available in Editor] → Can be inserted into pages
  ↓
[Launch Station] → Deploy to subdomain or custom domain

3. Flow Creation → Attachment → Execution Flow

[User] → [Singularity (/singularity)]
  ↓
[Create Flow] → Visual node editor
  ↓
[Flow saved] → storage (space_flows)
  ↓
(MISSING STEP) [Attach flow to page] → Editor needs FlowAttachmentPanel
  ↓
(MISSING STEP) [Map flow outputs to widget inputs] → DataPipelineService
  ↓
(MISSING STEP) [Runtime execution] → FlowExecutionEngine
  ↓
(MISSING STEP) [Widget receives data] → Updates UI

4. Universe Creation → Editing → Deployment Flow

[User] → [Dashboard] → "Create Universe" button
  ↓
[Universe Creation Wizard] (/universe/create)
  ↓
[Universe created] → Saved to storage (universe_*)
  ↓
[Space Map] (/space-map) → Visualize universe
  ↓
[Create Galaxies] → Organizational containers
  ↓
[Create Pages] → Jump to Editor
  ↓
[Editor] → Build pages with widgets + modules + flows
  ↓
[Modularity] → Package pages into modules
  ↓
[Launch Station] → Deploy universe
  ↓
[Deployed to subdomain] → universe-slug.gograb.space

10. Critical Missing Connections

1. Launch Station Data Disconnect

Problem: Launch Station shows "No Universes" despite universes existing
Root Cause: Launch Station doesn't use UniverseManagerService or SpaceService
Fix: Inject UnifiedDataService (to be created) and load universes

2. Flow → Page Attachment

Problem: No way to attach Singularity flows to Editor pages
Root Cause: Missing FlowAttachmentService and Editor UI
Fix: Create service + UI panel

3. Flow → Widget Data Pipeline

Problem: Flows exist, widgets exist, but they can't communicate
Root Cause: Missing DataPipelineService and WidgetDataBinding
Fix: Create runtime data flow system

4. Module → Editor Integration

Problem: Can't insert packaged modules into Editor
Root Cause: Editor only accepts widgets, not modules
Fix: Create ModuleInserterComponent and ModuleInstance type

5. Universe/Galaxy → Editor Navigation

Problem: Can't jump from Space Map to Editor with context
Root Cause: No "Edit in Editor" buttons with proper routing
Fix: Add buttons with context-aware navigation

11. Implementation Priority

Phase 1: Data Unification (CRITICAL - 2-3 days)

Problem: Each tool maintains its own data, no single source of truth
Solution: Create UnifiedDataService

// libs/core-angular/src/lib/services/unified-data.service.ts
@Injectable({ providedIn: 'root' })
export class UnifiedDataService {
  // Signals
  readonly spaces = signal<Space[]>([]);
  readonly universes = signal<Universe[]>([]);
  readonly pages = signal<World[]>([]);
  readonly flows = signal<Flow[]>([]);
  readonly modules = signal<Module[]>([]);
  readonly widgets = signal<SpaceWidget[]>([]);
  
  // Computed cross-references
  readonly universesWithContent = computed(() => { ... });
  readonly modulesWithAssets = computed(() => { ... });
  
  // Load everything for a space
  async loadSpaceData(spaceSlug: string): Promise<void> { ... }
}

Phase 2: Flow → Page Connection (HIGH - 2-3 days)

Components to Create:

  1. FlowAttachmentService
  2. FlowAttachmentPanelComponent (Editor UI)
  3. Update World interface to include attachedFlowIds: string[]

Phase 3: Widget I/O + Data Pipeline (HIGH - 3-4 days)

Components to Create:

  1. DataPipelineService
  2. WidgetDataBinding interface
  3. FlowExecutionEngine (if doesn't exist)
  4. Update widgets to subscribe to data sources

Phase 4: Module → Editor Integration (MEDIUM - 2-3 days)

Components to Create:

  1. ModuleInserterComponent
  2. ModuleInstance type
  3. ModuleZoneComponent (render modules on canvas)
  4. Update EditorService to handle module instances

Phase 5: Route Reorganization (MEDIUM - 2-3 days)

Implementation:

  1. Create space-first routing
  2. Add route guards
  3. Update all navigation
  4. Add redirects

Phase 6: Editor Enhancements (LOW - 2-3 days)

Components to Create:

  1. Module Inserter panel (sidebar tab)
  2. Flow Inserter panel (sidebar tab)
  3. "Edit in Editor" buttons in Space Map

Phase 7: JSON Export/Import Unification (LOW - 2-3 days)

Implementation:

  1. Unified export format
  2. Import UI components
  3. Backend endpoints
  4. Vibe coding workflow

NEXT STEPS

Based on this analysis, the implementation should follow this order:

  1. ✅ Create UnifiedDataService - Single source of truth
  2. ✅ Fix Launch Station - Connect to unified data
  3. ✅ Add Flow Attachment - Connect Singularity to Editor
  4. ✅ Build Data Pipeline - Widget I/O + flow execution
  5. ✅ Module Integration - Insert modules in Editor
  6. ✅ Route Reorganization - Space-first architecture
  7. ✅ Editor Enhancements - Module/Flow inserters
  8. ✅ Export/Import System - Unified JSON workflow

Status: Analysis COMPLETE ✅
Ready for: Implementation Planning