🗺️ GoGrab Space Routing Architecture

Status: ✅ Production Ready
Last Updated: October 29, 2025
Architecture: Space-First with Event-Driven Navigation

📋 Table of Contents

1. Overview
2. Space-First Routing
3. Dynamic Module Registration
4. Event-Driven Navigation
5. Storage & Caching
6. Testing
7. Related Documentation

🎯 Overview

The GoGrab Space routing system is built on three core principles:

1. Space-First Architecture - All routes scoped under :spaceSlug
2. Dynamic Module Registration - Routes injected at runtime
3. Event-Driven Navigation - Smart rebuilding with flash-persistence

Why This Matters

Traditional routing:

/editor         ❌ No space context
/dashboard      ❌ No space context
/modularity     ❌ No space context

Our space-first routing:

/:spaceSlug/editor        ✅ Space-scoped
/:spaceSlug/dashboard     ✅ Space-scoped
/:spaceSlug/modularity    ✅ Space-scoped

Benefits:

• ✅ Multi-tenant support (each space is isolated)
• ✅ Clean context separation
• ✅ Better security (space-level guards)
• ✅ Flexible deployment (same code, different spaces)

🌌 Space-First Routing

Route Structure

// apps/gograb-space/src/app/app.routes.ts
export const gSpaceMainRoutes: Routes = [
  {
    path: ':spaceSlug',  // 🎯 Space-first parent route
    loadComponent: () => AppShellComponent,
    canActivate: [authGuard, spaceGuard],
    resolve: { space: spaceResolver },
    children: [
      { path: '', redirectTo: 'dashboard', pathMatch: 'full' },
      { path: 'dashboard', loadComponent: DashboardComponent },
      // Module routes injected here dynamically
    ]
  }
];

URL Examples

Production:
  /my-space/dashboard         → User's space dashboard
  /my-space/editor            → Space-scoped editor
  /team-workspace/modularity  → Team's modularity view

Development:
  /editor/dashboard           → Editor workspace
  /launch-pad/missions        → Launch Station missions

Space Context Service

The UniverseContextService provides reactive space context:

const currentSpace = this.universeContext.currentSpace(); // "my-space"
const spacePath = `/${currentSpace}/editor`; // "/my-space/editor"

🔌 Dynamic Module Registration

The Challenge

GoGrab Space uses a modular architecture:

• Singularity (space management)
• Editor (content editing)
• Space Map (visual overview)
• Modularity (module configuration)
• Launch Station (deployment)

Problem: Module routes don't exist until runtime!

// At app initialization:
router.config = [
  { path: ':spaceSlug/dashboard' }  // Only static routes
];

// After module registration:
router.config = [
  { path: ':spaceSlug/dashboard' },
  { path: ':spaceSlug/editor' },      // ✅ Injected
  { path: ':spaceSlug/space-map' },   // ✅ Injected
  { path: ':spaceSlug/modularity' }   // ✅ Injected
];

Solution: Runtime Route Injection

File: libs/core/module-integrator/src/lib/navigation/route-registration.service.ts

@Injectable({ providedIn: 'root' })
export class RouteRegistrationService {
  registerModuleRoutes(): RouteRegistrationResult {
    const modules = this.registry.getAll();
    const moduleRoutes: Routes = [];

    for (const module of modules) {
      if (module.routes && module.routes.length > 0) {
        const basePath = module.manifest.id; // 'editor', 'space-map', etc.
        
        moduleRoutes.push({
          path: basePath,
          children: module.routes
        });
      }
    }

    // Inject routes into :spaceSlug children
    this.injectModuleRoutes(currentConfig, moduleRoutes);
    this.router.resetConfig(updatedConfig);
  }
}

Bootstrap Flow

1. App Starts
   ↓
2. Static routes loaded
   ↓
3. BrowserBootstrapperService.initialize()
   ↓
4. RouteRegistrationService.registerModuleRoutes()
   ↓
5. Module routes injected into :spaceSlug
   ↓
6. Router config updated
   ↓
7. RouteReadyService.notifyRoutesRegistered() ✅

⚡ Event-Driven Navigation

The Problem (Original Approach)

Attempt #1: setTimeout (❌ WRONG)

ngOnInit(): void {
  setTimeout(() => {
    this.navigationBuilder.refreshNavigation();
  }, 100); // ❌ Timing-dependent, fragile
}

Why It Failed:

• ❌ Arbitrary delay
• ❌ No guarantee routes are ready
• ❌ Race conditions
• ❌ Not intelligent

The Solution: Event-Driven Architecture

┌──────────────────────────────────────────────────────────┐
│  EVENT-DRIVEN NAVIGATION ARCHITECTURE                    │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  1. RouteReadyService (Event Bus)                        │
│     - Signal: routesReady()                              │
│     - Observable: routesRegistered$                      │
│     - Method: notifyRoutesRegistered()                   │
│                                                          │
│  2. Bootstrap Process (Emitter)                          │
│     - Registers module routes                            │
│     - Emits event when complete                          │
│                                                          │
│  3. NavigationBuilderService (Listener)                  │
│     - Watches routesReady signal via effect()            │
│     - Rebuilds navigation automatically                  │
│     - Caches to flash-persistence                        │
│                                                          │
└──────────────────────────────────────────────────────────┘

Implementation

1. RouteReadyService (Event Bus)

File: apps/gograb-space/src/app/services/route-ready.service.ts

@Injectable({ providedIn: 'root' })
export class RouteReadyService {
  private readonly _routesReady = signal<boolean>(false);
  readonly routesReady = this._routesReady.asReadonly();

  private readonly _routesRegistered = new Subject<void>();
  readonly routesRegistered$ = this._routesRegistered.asObservable();

  notifyRoutesRegistered(): void {
    this._routesReady.set(true);
    this._routesRegistered.next();
  }
}

2. Emit Event After Registration

File: apps/gograb-space/src/main.ts

provideAppInitializer(() => {
  const bootstrapper = inject(BrowserBootstrapperService);
  const routeReady = inject(RouteReadyService);

  bootstrapper.initialize({...}).subscribe({
    next: (result) => {
      // 🎯 Event emitted EXACTLY when routes are ready
      routeReady.notifyRoutesRegistered();
    }
  });
})

3. React to Event

File: apps/gograb-space/src/app/services/navigation-builder.service.ts

constructor() {
  this.loadFromCache(); // Instant load from cache
  this.buildNavigationFromRoutes(); // Initial build

  // 🎯 Automatic rebuild when routes ready
  effect(() => {
    const ready = this.routeReady.routesReady();
    if (ready) {
      this.buildNavigationFromRoutes();
      this.saveToCache(); // Update cache
    }
  });
}

Complete Flow

App Start
  ↓
NavigationBuilderService.constructor()
  ├─ loadFromCache() → ⚡ INSTANT from storage
  ├─ buildNavigationFromRoutes() → Static routes
  └─ effect(() => ...) → Set up listener
  ↓
BrowserBootstrapperService.initialize()
  ├─ Register module routes
  └─ routeReady.notifyRoutesRegistered() → 🔔 EVENT!
  ↓
NavigationBuilderService effect triggers
  ├─ buildNavigationFromRoutes() → ✅ Includes module routes
  └─ saveToCache() → 💾 Cache for next time
  ↓
✅ Navigation complete with all routes!

💾 Storage & Caching

Flash-Persistence Integration

Library: @gg-storage (flash-persistence system)

Configuration:

private readonly CACHE_KEY = 'navigation-items-cache-v1';
private readonly CACHE_TTL_MS = 1000 * 60 * 60 * 24; // 24 hours

Cache Strategy

1. Load from Cache (Instant)

private async loadFromCache(): Promise<void> {
  const cached = await this.storage.get<{
    items: NavigationItem[];
    timestamp: number;
  }>(this.CACHE_KEY);

  if (cached && (Date.now() - cached.timestamp < this.CACHE_TTL_MS)) {
    this.routeBasedItems.set(cached.items);
    console.log(`⚡ Loaded ${cached.items.length} items from cache`);
  } else {
    await this.storage.remove(this.CACHE_KEY); // Expired
  }
}

2. Save to Cache (After Rebuild)

private async saveToCache(): Promise<void> {
  await this.storage.set(this.CACHE_KEY, {
    items: this.routeBasedItems(),
    timestamp: Date.now()
  });
  console.log(`💾 Cached ${this.routeBasedItems().length} items`);
}

Performance Benefits

🧪 Testing

Unit Tests

Files:

1. apps/gograb-space/src/app/services/route-ready.service.spec.ts
2. apps/gograb-space/src/app/services/navigation-builder.service.spec.ts

Coverage:

• ✅ RouteReadyService signal and observable APIs
• ✅ NavigationBuilderService route extraction
• ✅ Storage integration (load, save, expiration)
• ✅ Event-driven rebuilding
• ✅ Error handling

Run Tests:

nx test gograb-space

Integration Testing

Manual Test Flow:

1. Clear cache: localStorage.clear()
2. Refresh browser
3. Check console: "💾 Cached X navigation items"
4. Refresh again
5. Check console: "⚡ Loaded X items from cache (Ys old)"

📚 Related Documentation

Core Systems

• Event-Driven Navigation - RouteReadyService event bus for reactive navigation updates
• Navigation Caching System - Flash-persistence integration for instant sidenav rendering

Implementation Fixes

• Dynamic Module Routes Event-Driven Fix - Event-driven solution for dynamic route registration

Progress Notes

• Session October 29, 2025 - Storage-system integration and unit testing completion

🎯 Key Takeaways

1. Space-First - All routes scoped under :spaceSlug for multi-tenancy
2. Dynamic Modules - Routes injected at runtime by module system
3. Event-Driven - No timing hacks, pure event-based coordination
4. Flash-Persistence - 40x faster subsequent loads with intelligent caching
5. Fully Tested - Unit tests for all critical paths

Status: ✅ Production Ready
Version: 2.0.0
Architecture: Space-First + Event-Driven + Flash-Persistence