GoGrab Space Monorepo Architecture

Complete routing and organizational architecture for the GoGrab Space platform builder

GoGrab Space Monorepo Architecture

🎯 Core Philosophy

"Build with reusable building blocks - modules that create modules"

Key Principles:

Modular Everything: Every feature is a self-contained, reusable module
Clear Separation: Showcases (read-only) vs. Tools (interactive builders)
Parent Routes: Consolidated routes under logical parent paths
AI-Trainable: Consistent patterns enable AI code generation
Performance First: Offline-first, flash persistence, lazy loading

📁 Monorepo Structure

editor/                              # Root monorepo
├── apps/
│   ├── gograb-space/               # Main platform (port 5200)
│   ├── gograb-admin/               # Admin dashboard (port 4300)
│   ├── space-admin/                # Space management (port 5300)
│   ├── docs-angular/               # Documentation (port 5010)
│   └── backend-api/                # Backend API (port 3000)
│
├── libs/
│   ├── libs-widgets/               # 🧩 WIDGET SYSTEM
│   │   ├── widgets/                # Base widget components
│   │   ├── widget-builder/         # Widget Builder tool
│   │   ├── widget-showcase/        # Widget demos & showcases
│   │   └── widgets-manager/        # Widget Manager tool
│   │
│   ├── theme-system/               # 🎨 THEME SYSTEM
│   │   ├── theme-runtime/          # Runtime theme engine
│   │   ├── theme-styles/           # SCSS styles & utilities
│   │   ├── theme-showcase/         # Theme demos & guides
│   │   └── cosmic-backgrounds/     # Visual effects
│   │
│   ├── libs-structural/            # 🏗️ STRUCTURAL TOOLS
│   │   ├── editor-web-lib/         # Page Editor
│   │   ├── modular-universe/       # Universe Builder
│   │   ├── modularity-lib/         # Module Builder
│   │   ├── singularity-lib/        # Logic Blocks
│   │   └── launch-station-lib/     # Deployment
│   │
│   ├── libs-foundational/          # 🔧 FOUNDATION
│   │   ├── core-models/            # Shared types
│   │   ├── storage-system/         # Flash persistence
│   │   ├── core-angular/           # Angular utilities
│   │   └── auth-system/            # Authentication
│   │
│   ├── libs-ui/                    # 🎨 UI LIBRARIES
│   │   ├── demos-lib/         # DEPRECATED - Internal demos only
│   │   ├── ux-ui-feedback/         # Toast, modals, etc.
│   │   └── ux-colors/              # Color utilities
│   │
│   └── libs-ai/                    # 🤖 AI INTEGRATION
│       ├── gograb-ai/              # AI services
│       └── prompt-system/          # Prompt management
│
└── docs/                           # 📚 DOCUMENTATION
    └── english/
        ├── Monorepo-arquitecture/  # This document
        ├── GoGrab-Space/           # Platform docs
        └── public/                 # General docs

🛣️ Routing Architecture

Parent Routes Strategy

Philosophy: Group related functionality under logical parent paths

BEFORE (Scattered):
/widget-builder          ← Tool
/widgets                 ← Manager
/ui-builder/widgets      ← Showcase (confusing!)

AFTER (Organized):
/widgets/                ← Parent route
  ├── /                  ← Showcase (gallery)
  ├── /builder           ← Tool
  └── /manager           ← Tool

Current Parent Routes

1. `/widgets/` - Widget System

Location: libs/libs-widgets/widgets.routes.ts

/widgets/                → Widget Gallery (showcase)
/widgets/guide           → Widget Guide (showcase)
/widgets/:widgetId       → Widget Demo (showcase)
/widgets/builder         → Widget Builder (tool)
/widgets/manager         → Widget Manager (tool)

Categories:

Showcases (read-only): Gallery, guide, demos
Tools (interactive): Builder, manager

Example URLs:

http://localhost:5200/space/space-123/widgets/
http://localhost:5200/space/space-123/widgets/button
http://localhost:5200/space/space-123/widgets/builder
http://localhost:5200/space/space-123/widgets/manager

2. `/theme-system/` - Theme System

Location: libs/theme-system/theme-system.routes.ts

/theme-system/               → Theme Guide (showcase)
/theme-system/guide          → Complete guide (showcase)
/theme-system/create         → Theme creator (showcase - demo)
/theme-system/templates      → Theme templates (showcase)
/theme-system/editor         → Theme editor (showcase - demo)
/theme-system/reference      → CSS reference (showcase)
/theme-system/utilities      → Utility classes (showcase)
/theme-system/best-practices → Design guidelines (showcase)
/theme-system/advanced-effects → Visual effects (showcase)
/theme-system/gradients      → Gradients (showcase)
/theme-system/materials      → Material Design (showcase)
/theme-system/neumorphism    → Neumorphism (showcase)
/theme-system/interactive    → Interactive effects (showcase)

Categories:

Showcases (read-only): All current routes are demos/docs
Tools (future): Interactive theme editor

Example URLs:

http://localhost:5200/space/space-123/theme-system/
http://localhost:5200/space/space-123/theme-system/guide
http://localhost:5200/space/space-123/theme-system/editor

3. `/ui-builder/` - DEPRECATED

Location: libs/libs-ui/demos-lib/src/ui-builder.routes.ts

Status: DEPRECATED - Kept for backward compatibility only

/ui-builder/ux/          → Internal UX demos (deprecated)
/ui-builder/storage/     → Storage demos
/ui-builder/ai/          → AI integration demos

Migration:

Widget demos → /widgets/:widgetId
Theme demos → /theme-system/
Internal demos → Keep in /ui-builder/ temporarily

🧩 Showcases vs. Tools

Philosophy: Clear Separation

Showcases (Read-Only):

Purpose: Learning, inspiration, documentation
Examples: Widget gallery, theme guide, component demos
User Action: View, learn, get inspired
Location: Root of parent route (/widgets/, /theme-system/)

Tools (Interactive):

Purpose: Building, creating, modifying
Examples: Widget builder, module builder, theme editor
User Action: Create, edit, save, publish
Location: Under /builder, /manager, /editor

Examples

Widget System:

SHOWCASES (Read-Only):
- /widgets/              → Browse gallery
- /widgets/guide         → Learn about widgets
- /widgets/button        → View button demo

TOOLS (Interactive):
- /widgets/builder       → Create custom widgets
- /widgets/manager       → Manage widget library

Theme System:

SHOWCASES (Read-Only):
- /theme-system/         → View theme guide
- /theme-system/guide    → Complete documentation
- /theme-system/gradients → View gradient examples

TOOLS (Interactive - Future):
- /theme-system/editor   → Create/edit themes (currently a demo)

🔄 Migration Patterns

From Old Structure to New

Pattern 1: Individual Routes → Parent Route

Before:

// Scattered across app.routes.ts
{ path: 'widgets', loadComponent: () => ... },          // Manager
{ path: 'widget-builder', loadChildren: () => ... },    // Builder
{ path: 'ui-builder/widgets', children: [...] },        // Showcase

After:

// Consolidated in widgets.routes.ts
export const WidgetsParentRoutes: Routes = [
  {
    path: 'widgets',
    children: [
      { path: '', loadComponent: () => ... },           // Gallery
      { path: 'builder', loadChildren: () => ... },     // Builder
      { path: 'manager', loadChildren: () => ... },     // Manager
    ]
  }
];

Pattern 2: Direct Import → Lazy Loading

Before (Circular dependencies):

import { WidgetBuilderRoutes } from '@libs-widgets/widget-builder';
import { WidgetsManagerRoutes } from '@libs-widgets/widgets-manager';

children: [
  { path: 'builder', children: WidgetBuilderRoutes },   // ❌ Direct import
]

After (No circular dependencies):

children: [
  {
    path: 'builder',
    loadChildren: () => import('@libs-widgets/widget-builder')
      .then(m => m.WidgetBuilderRoutes)                 // ✅ Lazy loading
  },
]

📊 Route Organization Table

Parent Route	Type	Location	Purpose	Examples
`/widgets/`	Mixed	`libs-widgets/widgets.routes.ts`	Widget system	`/widgets/`, `/widgets/builder`
`/theme-system/`	Showcase	`theme-system/theme-system.routes.ts`	Theme system	`/theme-system/guide`
`/editor/`	Tool	`editor-web-lib`	Page editor	`/editor/`
`/modular-universe/`	Tool	`modular-universe`	Universe builder	`/modular-universe/`
`/modularity/`	Tool	`modularity-lib`	Module builder	`/modularity/`
`/singularity/`	Tool	`singularity-lib`	Logic blocks	`/singularity/`
`/launch-station/`	Tool	`launch-station-lib`	Deployment	`/launch-station/`
`/ui-builder/`	DEPRECATED	`demos-lib`	Legacy demos	`/ui-builder/ux/`

🎨 Component Organization

Directory Structure Pattern

feature-name/
├── showcases/                  # READ-ONLY demos
│   ├── feature-showcase/       # Gallery/overview
│   ├── feature-demo/           # Interactive demos
│   └── feature-guide/          # Documentation
│
├── components/                 # Reusable components
│   ├── feature-item/
│   ├── feature-list/
│   └── feature-preview/
│
├── services/                   # Business logic
│   ├── feature.service.ts
│   └── feature-storage.service.ts
│
├── models/                     # Type definitions
│   └── feature.types.ts
│
└── feature.routes.ts           # Route definitions

Example: Widget Showcase

widget-showcase/
├── showcases/                  # Read-only demos
│   ├── clipboard-showcase/
│   ├── icons-showcase/
│   └── showcases.routes.ts
│
├── components/                 # Gallery components
│   ├── widget-gallery/         # Main gallery
│   ├── widget-demo/            # Demo viewer
│   ├── widget-guide/           # Guide component
│   └── ux-widget-*/            # Helper components
│
├── demos/                      # Interactive demos
│   └── button-demo/            # Button demo POC
│
├── services/
│   └── button-database.service.ts
│
└── index.ts                    # Public API

🚀 Development Workflow

Adding a New Feature

Step 1: Determine Category

Showcase (read-only)? → Add to showcases/
Tool (interactive)? → Create separate library

Step 2: Choose Location

Widget-related? → libs/libs-widgets/
Theme-related? → libs/theme-system/
Structural tool? → libs/libs-structural/
Foundation? → libs/libs-foundational/

Step 3: Create Structure

# For showcase
nx g @nx/angular:component showcase-name \
  --project=widget-showcase \
  --path=lib/showcases \
  --standalone

# For tool
nx g @nx/angular:library tool-name \
  --directory=libs/libs-widgets \
  --standalone

Step 4: Add Routes

// If showcase: Add to showcases.routes.ts
export const showcasesRoutes: Routes = [
  {
    path: 'new-showcase',
    loadComponent: () => import('./new-showcase/new-showcase.component')
      .then(m => m.NewShowcaseComponent),
    title: 'New Showcase',
  }
];

// If tool: Create parent route or add to existing
export const NewToolRoutes: Routes = [
  {
    path: '',
    loadComponent: () => import('./new-tool.component')
      .then(m => m.NewToolComponent),
  }
];

Step 5: Register in Parent Route

// In widgets.routes.ts or theme-system.routes.ts
{
  path: 'new-feature',
  loadChildren: () => import('@libs-widgets/new-tool')
    .then(m => m.NewToolRoutes),
  title: 'New Tool',
}

Testing Routes

# Start the app
yarn dev:gograb

# Navigate to routes
http://localhost:5200/space/[space-id]/widgets/
http://localhost:5200/space/[space-id]/theme-system/
http://localhost:5200/space/[space-id]/widgets/builder

✅ Best Practices

1. Route Organization

✅ Use parent routes for related functionality
✅ Group showcases vs. tools clearly
✅ Use lazy loading to avoid circular dependencies
❌ Don't mix showcases and tools at the same level

2. Component Structure

✅ Separate showcases (read-only) from components (interactive)
✅ Keep demos in demos/ directory
✅ Export through index.ts for clean imports
❌ Don't create components directly in library root

3. Naming Conventions

Showcases: feature-showcase.component.ts
Tools: feature-builder.component.ts
Demos: feature-demo.component.ts
Guides: feature-guide.component.ts

4. Documentation

✅ Add README.md to each library
✅ Document routes in comments
✅ Use frontmatter in .mdc files
✅ Keep architecture docs updated

🔍 Troubleshooting

Circular Dependency Errors

Problem: Circular dependency detected: charts -> widget-showcase

Solution: Use lazy loading

// ❌ BAD: Direct import
import { WidgetBuilderRoutes } from '@libs-widgets/widget-builder';
children: WidgetBuilderRoutes

// ✅ GOOD: Lazy loading
loadChildren: () => import('@libs-widgets/widget-builder')
  .then(m => m.WidgetBuilderRoutes)

Route Not Found (404)

Problem: Cannot match any routes. URL Segment: 'widgets/button'

Solution: Check route hierarchy

// ✅ CORRECT
/widgets/                → Parent
  /:widgetId             → Dynamic param

// ❌ WRONG
/widgets/button          → Hardcoded (won't match dynamic)

Component Export Errors

Problem: Module has no exported member 'WidgetGalleryComponent'

Solution: Add to index.ts

// components/index.ts
export * from './widget-gallery/widget-gallery.component';
export * from './widget-demo/widget-demo.component';

📚 Related Documentation

🎯 Future Enhancements

Short-Term

Add deprecation warnings to /ui-builder/ux/ routes
Create interactive theme editor tool
Implement widget search/filter in gallery
Add AI-powered widget generation

Long-Term

Extract all UX demos to proper widgets
Remove /ui-builder/ routes entirely
Create widget marketplace
Build theme template library

Last Updated: November 16, 2025 - 6:45 PM EST Status: ✅ Production Ready Version: 2.0.0 Author: GoGrab Space Team

Let's build the Ferrari/Lambo of platform builders! 🏎️💨

GoGrab Space Monorepo Architecture

🎯 Core Philosophy

Key Principles:

📁 Monorepo Structure

🛣️ Routing Architecture

Parent Routes Strategy

Current Parent Routes

1. /widgets/ - Widget System

2. /theme-system/ - Theme System

3. /ui-builder/ - DEPRECATED

🧩 Showcases vs. Tools

Philosophy: Clear Separation

Examples

Widget System:

Theme System:

🔄 Migration Patterns

From Old Structure to New

Pattern 1: Individual Routes → Parent Route

Pattern 2: Direct Import → Lazy Loading

📊 Route Organization Table

🎨 Component Organization

Directory Structure Pattern

Example: Widget Showcase

🚀 Development Workflow

Adding a New Feature

Step 1: Determine Category

Step 2: Choose Location

Step 3: Create Structure

Step 4: Add Routes

Step 5: Register in Parent Route

Testing Routes

✅ Best Practices

1. Route Organization

2. Component Structure

3. Naming Conventions

4. Documentation

🔍 Troubleshooting

Circular Dependency Errors

Route Not Found (404)

Component Export Errors

📚 Related Documentation

🎯 Future Enhancements

Short-Term

Long-Term

1. `/widgets/` - Widget System

2. `/theme-system/` - Theme System

3. `/ui-builder/` - DEPRECATED