Database Collection Naming Convention

Official naming convention for MongoDB collections in GoGrab Space

📛 Database Collection Naming Convention

🚨 The Simple Rule (CRITICAL)

If it has space_ prefix → it belongs to a specific space database
If it has no prefix → it's global/platform-level (in gograb-api database)

📊 Complete Reference Table

Global Database (gograb-api)

Collection Purpose Notes
modules Global platform modules Core Angular modules (page-renderer, sidebar-nav, etc.)
widgets Global widgets Platform-wide widget definitions
flows Global Singularity flows Platform-wide flow templates
templates Global templates Starter templates (restaurant-starter, etc.)
users User accounts Platform users
spaces Space registry Space-builder profiles
sessions Auth sessions JWT sessions
themes Global themes Theme library
ai_chat_history AI conversations Chat history
aiusages AI usage metrics Usage tracking

Space Database (space_{spaceId})

Collection Purpose Notes
space_modules Space-level modules Custom/extended modules
space_widgets Space-level widgets Space-specific widgets
space_flows Space-level flows Space-specific Singularity flows
space_templates Space-level templates Space-specific templates
space_pages Reusable pages Pages within the space
space_metadata Space settings Configuration
universes Universe definitions Contains structure tree
team_members Space team Collaborators
billing Space billing Subscription info
theme_system Theme configuration Active theme state
audit_logs Audit trail Space-wide logs

Universe-Specific Collections (Prefixed)

Collection Pattern Purpose
universe_{id}_metadata Universe settings
universe_{id}_pages Universe pages
universe_{id}_widgets Universe widget instances
universe_{id}_flows Universe flows
universe_{id}_deployments Deployment history
universe_{id}_users App users (deployed apps)
universe_{id}_[custom] Custom data collections

🎯 Why This Convention?

1. AI Training Friendly

2. Clear Scope Identification

modules           → Global (gograb-api)
space_modules     → Space-level (space_{id})
universe_{id}_*   → Universe-specific (space_{id})

3. Consistent Pattern

Scope Prefix Example
Global None modules, widgets, flows
Space space_ space_modules, space_widgets
Universe universe_{id}_ universe_123_pages

⚠️ Common Mistakes

❌ WRONG

// Don't use global_ prefix for global collections
collection('global_modules')  // ❌ Wrong
collection('global_widgets')  // ❌ Wrong

// Don't omit space_ prefix for space collections
collection('modules')  // ❌ Wrong (in space database)
collection('widgets')  // ❌ Wrong (in space database)

✅ CORRECT

// Global database (gograb-api) - clean names
collection('modules')   // ✅ Correct
collection('widgets')   // ✅ Correct
collection('flows')     // ✅ Correct

// Space database (space_{id}) - space_ prefix
collection('space_modules')   // ✅ Correct
collection('space_widgets')   // ✅ Correct
collection('space_flows')     // ✅ Correct

🔄 Migration Endpoints

If existing databases have old collection names:

Space Collections Migration

POST /api/spaces/:spaceId/migrate-collections

Migrates:

Global Modules Migration

POST /api/global-modules/migrate

Migrates:

📝 Code Examples

Backend Service (NestJS)

// ✅ Correct: Global modules
@Injectable()
export class GlobalModulesService {
  constructor(@InjectModel(GlobalModule.name) private model: Model<GlobalModule>) {}
  // Schema uses: collection: 'modules'
}

// ✅ Correct: Space modules
@Injectable()
export class SpaceModulesService {
  getCollection(spaceId: string) {
    const dbName = `space_${spaceId}`;
    return this.connection.useDb(dbName).collection('space_modules');
  }
}

Frontend Service (Angular)

// ✅ Correct: Fetching modules
export class ModuleService {
  // Global modules from gograb-api/modules
  getGlobalModules() {
    return this.http.get<GlobalModule[]>('/api/global-modules');
  }
  
  // Space modules from space_{id}/space_modules
  getSpaceModules(spaceId: string) {
    return this.http.get<SpaceModule[]>(`/api/spaces/${spaceId}/modules`);
  }
}

🔗 Related Documentation

Established: December 1, 2025
Status: ✅ Official Standard
Applies To: All new and existing databases
Maintainer: GoGrab Team