Module System Architecture

Why we use BrowserModuleContract and hybrid routing strategy

Module System Architecture

Decision Date: November 1, 2025
Decision Owner: Platform Team
Status: Approved - Implementation in Progress

Executive Summary

Decision: Use BrowserModuleContract from @libs-core/module-base as the single, unified module system across the entire platform.

Replace: EditorModuleContract from @libs-foundational/core-angular

Approach: Hybrid routing - Static routes for platform tools, dynamic routes for user-created modules.

The Decision: Hybrid Approach + BrowserModuleContract

Platform Tools (Static Routes)

User Modules (Dynamic Routes)

Why BrowserModuleContract?

1. Maturity and Feature Completeness

BrowserModuleContract (from gograb-space monorepo):

EditorModuleContract (from editor monorepo):

2. AI Training Simplification

Single Pattern:

Multiple Patterns (Current):

3. Type Safety

BrowserModuleContract:

export interface BrowserModuleContract {
  readonly manifest: ModuleManifest;
  readonly routes?: Routes;
  readonly embeddableComponents?: EmbeddableComponent[];
  readonly publicActions?: ModuleAction[];
  
  configure<T = Record<string, unknown>>(config: T): Observable<void>;
  initialize(): Observable<void>;
  start(): Observable<void>;
  stop(): Observable<void>;
  destroy(): Observable<void>;
}

EditorModuleContract:

export interface EditorModuleContract {
  readonly manifest: EditorModuleManifest;
  
  configure(config: ModuleConfig): Observable<void>;
  initialize(): Observable<void>;
  start(): Observable<void>;
  stop(): Observable<void>;
  destroy(): Observable<void>;
}

Advantages:

4. Ecosystem Alignment

Alternatives Considered

Alternative 1: Keep Both Systems

Pros:

Cons:

Verdict: ❌ Rejected - Tech debt too high

Alternative 2: Create New Unified System

Pros:

Cons:

Verdict: ❌ Rejected - Too time-consuming

Alternative 3: Use EditorModuleContract Everywhere

Pros:

Cons:

Verdict: ❌ Rejected - Less capable

Alternative 4: Hybrid with BrowserModuleContract (CHOSEN)

Pros:

Cons:

Verdict: ✅ SELECTED - Best long-term solution

Migration Strategy

Phase 1: Copy Infrastructure

# Copy module-base from gograb-space to editor monorepo
# Already exists at: libs/core/module-base

Status: ✅ Complete (module-base already exists)

Phase 2: Update User Management Module

File: modules/user-management/src/lib/user-management.module.ts

Changes:

  1. Replace import:

    // OLD
import { EditorModuleContract, Module } from '@libs-foundational/core-angular';

// NEW
import { BrowserModuleContract, ModuleDecorator } from '@libs-core/module-base';

  2. Replace decorator:

    // OLD
@Module({ manifest: USER_MODULE_MANIFEST })

// NEW
@ModuleDecorator({
  id: 'user-management',
  version: '1.0.0',
  name: 'User Management'
})

  3. Implement new contract:

    // OLD
export class UserManagementModule implements EditorModuleContract

// NEW
export class UserManagementModule implements BrowserModuleContract

  4. Add rich parameters to manifest:

    publicActions: [
  {
    id: 'users:create',
    displayName: 'Create User',
    parameters: [
      ModuleParameterBuilder.string('name')
        .required('Name is required')
        .minLength(2)
        .maxLength(100)
        .build(),
      ModuleParameterBuilder.email('email')
        .required('Email is required')
        .build()
    ],
    handler: (params) => of(this.createUser(params))
  }
]

Status: ⏳ Pending

Phase 3: Remove EditorModuleContract

Files to Update:

  1. libs/core-angular/src/lib/contracts/editor-module-contract.ts - DELETE
  2. libs/core-angular/src/index.ts - Remove export
  3. libs/core-angular/src/lib/services/editor-module-integrator.service.ts - UPDATE or REMOVE

Status: ⏳ Pending

Phase 4: Update Documentation

Files to Update:

  1. modules/README.md - Update references
  2. modules/index.md - Update references
  3. Any other docs mentioning EditorModuleContract

Status: ⏳ Pending

Implementation Impact

Files Affected

Estimated Effort

Risk Assessment

Risk Level: Medium

Risks:

  1. Module registration may break - Mitigation: Test thoroughly
  2. Integration service may need rewrite - Mitigation: May not be needed with new approach
  3. Hidden dependencies - Mitigation: Run comprehensive tests

Routing Strategy

Building Mode (Platform Builders)

URL Pattern: /:spaceSlug/tool

/:spaceSlug/dashboard
/:spaceSlug/editor
/:spaceSlug/space-map
/:spaceSlug/singularity
/:spaceSlug/modularity
/:spaceSlug/launch-station
/:spaceSlug/ui-builder

Characteristics:

Deployed Mode (End Users)

URL Pattern: subdomain.gograb.space/route

myUniverse.gograb.space/
myUniverse.gograb.space/about
myUniverse.gograb.space/products
myUniverse.gograb.space/contact

Characteristics:

User Module Routes (Dynamic)

Registration: Runtime via DynamicRouteService

// Module manifest defines routes
const manifest: ModuleManifest = {
  routes: [
    {
      path: 'users',
      loadComponent: () => import('./user-list.component')
    },
    {
      path: 'users/:id',
      loadComponent: () => import('./user-detail.component')
    }
  ]
};

// Routes registered when module deployed
await dynamicRouteService.registerModuleRoutes(manifest);

Benefits of This Architecture

1. Simplicity

2. Flexibility

3. Maintainability

4. AI-Friendly

5. Production-Ready

Verification Checklist

After migration:

Build Verification

Runtime Verification

Documentation Verification

Future Considerations

Phase 2: Module Generator

Once BrowserModuleContract is established:

Phase 5: AI Training

With single contract:

Phase 6: Subdomain Deployment

With clear routing:

Documentation Links

Related Documents:

Code References:

Decision Status: ✅ Approved
Implementation Status: 🎯 In Progress
Expected Completion: Week 1 (November 8, 2025)
Owner: Platform Team