Session 17 - Quick Reference

🌱 Seeding Global Modules

Auto-Seed (Default Behavior)

Backend auto-seeds on startup if gograb-api/modules is empty:

// GlobalModulesSeederService.onModuleInit()
// Checks stats.total === 0, then seeds automatically

Manual Seed via API

# Seed all modules (core + business)
POST /api/global-modules/seed

# Seed only core modules
POST /api/global-modules/seed/core

# Seed only business modules
POST /api/global-modules/seed/business

# Force reseed (update existing)
POST /api/global-modules/seed/reseed

# Check seed status
GET /api/global-modules/seed/status

# Clear all (USE WITH CAUTION!)
DELETE /api/global-modules/seed/clear

📁 File Locations

🔄 Module Flow

Local Code Module (modules/)
       ↓
   manifestId links to
       ↓
Global Module (gograb-api/modules)
       ↓
   extendsGlobal references
       ↓
Space Module (space_{id}/space_modules)
       ↓
   moduleId in structure
       ↓
Universe Structure (space_{id}/universes)

📊 Configuration Resolution

// Priority: Global → Space → Instance (later wins)
const config = {
  ...globalModule.defaultConfig,    // Base
  ...spaceModule.defaultConfig,     // Override
  ...structureNode.config           // Instance
};

🔍 Query Global Modules

# Get all modules
GET /api/global-modules

# Get by type
GET /api/global-modules/by-type/navigation

# Get by category
GET /api/global-modules/by-category/layout

# Get core only
GET /api/global-modules/core

# Search by AI capabilities
GET /api/global-modules/by-capabilities?capabilities=navigation,routing

# Full-text search
GET /api/global-modules?search=sidebar

📦 Seeded Module Categories

Core Modules (Always Seeded)

• Navigation: sidebar-nav, top-nav, breadcrumb-nav, footer
• Layout: layout-split-sidebar, layout-header-content-footer, layout-dashboard, layout-two-column-equal, layout-three-column-equal
• Content: page-renderer, form-builder, routes-manager
• Management: user-management, space-management

Business Modules (Optional)

• ecommerce-product-catalog
• blog-posts
• portfolio-showcase
• saas-landing
• fitness-studio

🚀 Testing the Seed

# 1. Start backend
yarn serve:backend

# 2. Check if auto-seeded (look for logs)
# 🌱 No global modules found, auto-seeding...
# ✅ Auto-seed complete: X modules created

# 3. Or manually trigger
curl -X POST http://localhost:3000/api/global-modules/seed \
  -H "Authorization: Bearer YOUR_TOKEN"

# 4. Verify
curl http://localhost:3000/api/global-modules/stats \
  -H "Authorization: Bearer YOUR_TOKEN"

⚠️ Troubleshooting

Modules not appearing?

1. Check backend logs for seeding errors
2. Verify MongoDB connection to gograb-api database
3. Run manual seed: POST /api/global-modules/seed

Duplicate modules?

• Seeder uses upsert, so duplicates shouldn't occur
• Check _id field uniqueness in seed data

Space modules not extending?

• Verify extendsGlobal references correct global module _id
• Check global module exists: GET /api/global-modules/{id}

📚 Related Documentation

• 17.1 Analysis
• Flat Module Architecture
• Session 16 - Backend Integration