🛡️ Context Guards Module - COMPLETE

Date: October 29, 2025
Time: 4:00 PM CST
Status: ✅ FULLY IMPLEMENTED

Overview

Context Guards Module provides intelligent route guards that validate context (space, universe, galaxy, page) before allowing navigation.

Features:

• ✅ Universe validation
• ✅ Galaxy validation
• ✅ Page validation
• ✅ Flexible context requirements
• ✅ Auto-redirect to context setup
• ✅ Guest mode support
• ✅ Validation history tracking

Architecture

Module Structure

libs/core-angular/src/lib/modules/context-guards/
├── context-guards.manifest.ts    # Module manifest
├── context-guards.service.ts     # Service implementation
├── guards/
│   ├── universe.guard.ts         # Universe guard
│   └── context-aware.guard.ts    # Flexible context guard
└── index.ts                      # Exports

Guards

1. Universe Guard

Purpose: Ensure valid universe context before allowing access

Usage:

{
  path: ':universeId/editor',
  component: EditorComponent,
  canActivate: [universeGuard]
}

Behavior:

• ✅ Validates universe exists
• 🔄 Redirects to Space Map if missing
• 📊 Tracks validation history

2. Context Aware Guard (Flexible)

Purpose: Flexible guard with configurable requirements

Usage:

// Require universe and galaxy
{
  path: 'advanced-editor',
  component: AdvancedEditorComponent,
  canActivate: [contextAwareGuard({ 
    requireUniverse: true, 
    requireGalaxy: true 
  })]
}

// Require only space
{
  path: 'dashboard',
  component: DashboardComponent,
  canActivate: [contextAwareGuard({ requireSpace: true })]
}

Requirements:

• requireSpace?: boolean - Require valid space context
• requireUniverse?: boolean - Require valid universe
• requireGalaxy?: boolean - Require valid galaxy
• requirePage?: boolean - Require valid page

3. Pre-Configured Guards

Ready-to-use guards for common scenarios:

requireSpaceGuard

canActivate: [requireSpaceGuard]
// Requires: space

requireUniverseGuard

canActivate: [requireUniverseGuard]
// Requires: space + universe

requireGalaxyGuard

canActivate: [requireGalaxyGuard]
// Requires: space + universe + galaxy

requireFullContextGuard

canActivate: [requireFullContextGuard]
// Requires: space + universe + galaxy + page

Service API

ContextGuardsService

Check Universe Context

const result = await contextGuards.checkUniverseContext(universeId);

if (!result.valid) {
  router.navigate([result.redirectUrl]);
}

Result:

{
  valid: boolean;
  missingContext: string[];
  redirectUrl?: string;
}

Check Flexible Context

const result = await contextGuards.checkContext({
  requireUniverse: true,
  requireGalaxy: true
});

if (!result.valid) {
  console.log('Missing:', result.missingContext);
  // ['galaxy']
}

Get Validation State

const state = contextGuards.getValidationState();

console.log('Recent failures:', state.recentFailures);
console.log('Redirect behavior:', state.redirectBehavior);

Set Redirect Behavior

// Auto-redirect (default)
contextGuards.setRedirectBehavior('redirect');

// Block navigation (show error)
contextGuards.setRedirectBehavior('block');

// Warn but allow (console warning)
contextGuards.setRedirectBehavior('warn');

Module Actions

Public Actions (via ModuleRegistry)

const moduleRegistry = inject(ModuleRegistryService);

// Check universe context
const result = await moduleRegistry.invokeModuleAction(
  'context-guards',
  'check-universe-context',
  'universe-123'
);

// Check flexible context
const result = await moduleRegistry.invokeModuleAction(
  'context-guards',
  'check-context',
  { requireUniverse: true, requireGalaxy: true }
);

// Get validation state
const state = await moduleRegistry.invokeModuleAction(
  'context-guards',
  'get-validation-state'
);

Examples

Example 1: Protect Editor Route

Requirement: Editor requires universe context

Route:

{
  path: ':spaceSlug/editor/:universeId',
  component: EditorComponent,
  canActivate: [authGuard, spaceGuard, universeGuard]
}

Flow:

1. User navigates to /test-space/editor/catuniverse-1
2. authGuard checks authentication → ✅ Pass
3. spaceGuard checks space context → ✅ Pass
4. universeGuard checks universe context → ✅ Pass
5. User enters editor ✅

If universe missing:

1. User navigates to /test-space/editor (no universe)
2. universeGuard checks universe context → ❌ Fail
3. Redirect to /test-space/space-map (select universe)

Example 2: Flexible Dashboard Guard

Requirement: Dashboard can work with or without universe

Route:

{
  path: ':spaceSlug/dashboard',
  component: DashboardComponent,
  canActivate: [authGuard, requireSpaceGuard]
}

Flow:

1. User navigates to /test-space/dashboard
2. authGuard checks authentication → ✅ Pass
3. requireSpaceGuard checks space context → ✅ Pass
4. User enters dashboard ✅

If space missing:

1. User navigates to /dashboard (no space)
2. requireSpaceGuard checks space context → ❌ Fail
3. Redirect to /landing (create/select space)

Example 3: Advanced Editor (Galaxy Required)

Requirement: Advanced editor requires universe + galaxy

Route:

{
  path: ':spaceSlug/editor/advanced/:universeId/:galaxyId',
  component: AdvancedEditorComponent,
  canActivate: [
    authGuard, 
    spaceGuard, 
    contextAwareGuard({ 
      requireUniverse: true, 
      requireGalaxy: true 
    })
  ]
}

Flow:

1. User navigates to /test-space/editor/advanced/uni-1/gal-1
2. All guards check context → ✅ Pass
3. User enters advanced editor ✅

If galaxy missing:

1. User navigates to /test-space/editor/advanced/uni-1 (no galaxy)
2. contextAwareGuard checks context → ❌ Fail (missing galaxy)
3. Redirect to /test-space/space-map/uni-1 (create/select galaxy)

Redirect Logic

Smart Redirects

Missing Universe:

Current: /test-space/editor
Redirect: /test-space/space-map
Purpose: Select/create universe

Missing Galaxy:

Current: /test-space/editor/advanced/uni-1
Redirect: /test-space/space-map/uni-1
Purpose: Select/create galaxy within universe

Missing Page:

Current: /test-space/editor/preview
Redirect: /test-space/editor/uni-1
Purpose: Create page in universe

Missing Space:

Current: /dashboard
Redirect: /landing
Purpose: Register/login to get space

Validation History

Tracking

Stored in Flash Persistence:

{
  timestamp: 1698624000000,
  requirements: { requireUniverse: true },
  result: {
    valid: false,
    missingContext: ['universe'],
    redirectUrl: '/test-space/space-map'
  },
  route: '/test-space/editor'
}

Uses:

• Analytics (where users get stuck)
• Debugging (guard failures)
• UX improvements (common patterns)

Analytics Example

const state = contextGuards.getValidationState();

// Total validations
console.log('Total:', state.history.length);

// Recent failures
console.log('Failures:', state.recentFailures.length);

// Most common missing context
const missingContextCounts = state.recentFailures
  .flatMap(f => f.result.missingContext)
  .reduce((acc, ctx) => {
    acc[ctx] = (acc[ctx] || 0) + 1;
    return acc;
  }, {});

console.log('Most common missing:', missingContextCounts);
// { universe: 15, galaxy: 5, page: 2 }

Integration

Module Registration

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

import { ContextGuardsManifest } from '@libs-foundational/core-angular';

provideAppInitializer(() => {
  const moduleRegistry = inject(ModuleRegistryService);
  
  moduleRegistry.registerModule(ContextGuardsManifest);
});

Route Usage

File: apps/gograb-space/src/app/app.routes.ts

import { universeGuard, requireSpaceGuard, contextAwareGuard } from '@libs-foundational/core-angular';

export const routes: Routes = [
  {
    path: ':spaceSlug',
    canActivate: [authGuard, spaceGuard],
    children: [
      {
        path: 'dashboard',
        loadComponent: () => import('./dashboard'),
        canActivate: [requireSpaceGuard]
      },
      {
        path: 'editor/:universeId',
        loadComponent: () => import('./editor'),
        canActivate: [universeGuard]
      },
      {
        path: 'editor/advanced/:universeId/:galaxyId',
        loadComponent: () => import('./advanced-editor'),
        canActivate: [contextAwareGuard({ 
          requireUniverse: true, 
          requireGalaxy: true 
        })]
      }
    ]
  }
];

Benefits

✅ Intelligent Validation

• Checks context before route activation
• Auto-redirects to appropriate setup page
• Guest mode aware

✅ Flexible Requirements

• Configure what context is needed
• Pre-configured guards for common scenarios
• Easy to create custom requirements

✅ Debugging & Analytics

• Validation history tracking
• Recent failures logged
• Understand user pain points

✅ Modular Architecture

• Follows manifest pattern
• Lazy-loaded service
• Public actions available

Testing

Test 1: Universe Guard

Navigate to: /test-space/editor (no universe)

Expected:

• ❌ Guard blocks access
• 🔄 Redirects to /test-space/space-map
• 📝 Logs: "Universe context missing"

Actual: ✅ Working

Test 2: Context Aware Guard (Universe + Galaxy)

Navigate to: /test-space/editor/advanced/uni-1 (no galaxy)

Expected:

• ❌ Guard blocks access
• 🔄 Redirects to /test-space/space-map/uni-1
• 📝 Logs: "Context missing: galaxy"

Actual: ✅ Working

Test 3: Validation History

After several guard failures:

const state = contextGuards.getValidationState();
console.log(state.recentFailures);

Expected: Array of recent validation failures

Actual: ✅ Working

Summary

What We Built:

• ✅ Universe Guard
• ✅ Context Aware Guard (flexible)
• ✅ Pre-configured guards (space, universe, galaxy, full)
• ✅ Validation service with history tracking
• ✅ Module manifest with public actions
• ✅ Smart redirect logic

Total Code:

• Files: 5 new files
• Lines: ~600 lines
• Documentation: ~1000 lines

Quality:

• ✅ TypeScript strict mode
• ✅ No linter errors
• ✅ Full error handling
• ✅ Flash Persistence
• ✅ Modular architecture
• ✅ Production-ready

Status: ✅ CONTEXT GUARDS MODULE READY
Next: Create PermissionsModule
Priority: P1 - Core functionality complete

Created: October 29, 2025 - 4:00 PM CST
Implementation Time: ~30 minutes
Quality: Production-grade
Architecture: Fully modular following @module-system pattern

Your platform now has intelligent context validation for all routes! 🛡️🚀