Modules Naming Convention

Ecosistema completo para organización y gestión de contenido con interfaces espaciales

GoGrab Space - Module Naming Convention

Overview

All GoGrab Space feature modules use the @module/ namespace prefix to provide clear distinction between foundational libraries and business modules.

Established: October 23, 2025
Last Updated: December 3, 2025 - 10:00 PM EST Session ID: 3 Status: ✅ Standard Convention - Visual + Code-First

Naming Convention

Modules (Feature Modules)

Format: @module/<module-name>

Examples:

✅ @module/user-management
✅ @module/product-catalog
✅ @module/analytics
✅ @module/reporting

Libraries (Foundational)

Format: @<library-name> (no prefix)

Examples:

✅ @libs-foundational/core-angular
✅ @storage-system
✅ @theme-system
✅ @editor-web-lib

Why This Convention?

1. Instant Clarity

// ✅ Immediately obvious it's a module
import { UserManagementModule } from '@module/user-management';

// ✅ Immediately obvious it's a foundational library
import { StorageService } from '@storage-system';

2. Namespace Organization

{
  "dependencies": {
    "@module/user-management": "1.0.0",
    "@module/product-catalog": "1.0.0",
    "@module/analytics": "1.0.0",
    "@storage-system": "1.0.0",
    "@theme-system": "1.0.0"
  }
}

All modules group together alphabetically!

3. Scalability

Can have 100+ modules under @module/ namespace
No naming conflicts with foundational libraries
Clear separation in package registries

4. Discoverability

# List all modules
npm search @module/

# List all foundational libraries  
npm search @editor-web-lib @storage-system @theme-system

5. Team Ownership

Easy to set up CODEOWNERS for all modules: modules/ @modules-team
Clear boundaries for code ownership
Simpler permission management

Implementation

1. Package Name

// modules/new-user-management/package.json
{
  "name": "@module/new-user-management",
  "version": "1.0.0",
  "description": "User Management module for GoGrab Space"
}

2. TypeScript Path Mapping

// tsconfig.base.json
{
  "compilerOptions": {
    "paths": {
      "@module/user-management": ["modules/user-management/src/index"],
      "@module/user-management/*": ["modules/user-management/src/*"]
    }
  }
}

3. Import Usage

// ✅ Correct
import { UserManagementModule } from '@module/user-management';
import { UserListComponent } from '@module/user-management';

// ❌ Incorrect (old style)
import { UserManagementModule } from '@user-management';

4. Documentation

All module READMEs should start with:

# @module/user-management

**Namespace**: All GoGrab Space modules use the `@module/` prefix.

**Module System**: Implements `BrowserModuleContract` from `@libs-core/module-base`.

Directory Structure

editor/
├── libs/                           # Foundational libraries (no prefix)
│   ├── core-angular/              → @libs-foundational/core-angular
│   ├── storage-system/            → @storage-system
│   ├── theme-system/              → @theme-system
│   ├── editor-web-lib/            → @editor-web-lib
│   └── space-map-lib/             → @space-map-lib
│
└── modules/                        # Feature modules (@module/ prefix)
    ├── user-management/           → @module/user-management
    ├── product-catalog/           → @module/product-catalog
    └── analytics/                 → @module/analytics

Build Output

dist/
├── libs/                           # Foundational libraries
│   ├── core-angular/
│   ├── storage-system/
│   └── theme-system/
│
└── modules/                        # Feature modules
    ├── user-management/
    │   └── package.json            → "name": "@module/user-management"
    ├── product-catalog/
    │   └── package.json            → "name": "@module/product-catalog"
    └── analytics/
        └── package.json            → "name": "@module/analytics"

Creating New Modules

Method 1: Visual Builder (Recommended)

Navigate to /modularity in GoGrab Space
Click "New Module"
Build your module visually
Export → The system automatically:
- Generates proper @module/my-module naming
- Creates all required configuration files
- Sets up proper path mappings

Method 2: Manual (Code-First)

Step 1: Generate Module

cd modules
npx nx g @nx/angular:library my-new-module

Step 2: Update package.json

{
  "name": "@module/my-new-module",
  "version": "0.0.1"
}

Step 3: Add to tsconfig.base.json

{
  "paths": {
    "@module/my-new-module": ["modules/my-new-module/src/index"],
    "@module/my-new-module/*": ["modules/my-new-module/src/*"]
  }
}

Step 4: Use in Code

import { MyNewModule } from '@module/my-new-module';

Comparison Table

Aspect	Modules	Libraries
Namespace	`@module/`	`@`
Location	`modules/`	`libs/`
Purpose	Business features	Foundational building blocks
Examples	`@module/user-management`	`@storage-system`
Build Output	`dist/modules/`	`dist/libs/`
Depends On	Libraries + other modules	Only other libraries
Import Pattern	`@module/name`	`@name`

Benefits Summary

✅ Clear Distinction - Instantly know if something is a module or library
✅ Namespace Organization - All modules group together
✅ Scalability - Can have unlimited modules without conflicts
✅ Discoverability - Easy to find and list modules
✅ Team Ownership - Clear code ownership boundaries
✅ NPM Scoping - Follows standard scoped package patterns
✅ Documentation - Self-documenting import statements
✅ Future-Proof - Can add more namespaces if needed (@plugin/, @widget/, etc.)

Examples in Action

Development

// app.component.ts
import { Component, inject } from '@angular/core';

// Foundational libraries (no prefix)
import { StorageService } from '@storage-system';
import { ThemeManagerService } from '@theme-system';

// Feature modules (@module/ prefix)
import { UserManagementModule } from '@module/user-management';
import { ProductCatalogModule } from '@module/product-catalog';

@Component({
  selector: 'app-root',
  template: `<router-outlet></router-outlet>`
})
export class AppComponent {
  private readonly storage = inject(StorageService);
  private readonly theme = inject(ThemeManagerService);
  private readonly userModule = inject(UserManagementModule);
  private readonly productModule = inject(ProductCatalogModule);
}

Package.json

{
  "name": "@myapp/web",
  "dependencies": {
    "@angular/core": "^20.1.0",
    "@libs-foundational/core-angular": "workspace:*",
    "@storage-system": "workspace:*",
    "@theme-system": "workspace:*",
    "@module/user-management": "workspace:*",
    "@module/product-catalog": "workspace:*",
    "@module/analytics": "workspace:*"
  }
}

Migration from Old Names

If you have existing modules without the @module/ prefix:

1. Update package.json

{
- "name": "@user-management",
+ "name": "@module/user-management"
}

2. Update tsconfig.base.json

{
  "paths": {
-   "@user-management": ["modules/user-management/src/index"],
+   "@module/user-management": ["modules/user-management/src/index"],
  }
}

3. Update all imports

- import { UserManagementModule } from '@user-management';
+ import { UserManagementModule } from '@module/user-management';

4. Rebuild

nx build user-management --skip-nx-cache

Future Namespaces

This convention allows for future expansion:

@module/ - Feature modules (current)
@plugin/ - Optional plugins (future)
@widget/ - Standalone widgets (future)
@adapter/ - External system adapters (future)

Conclusion

The @module/ namespace prefix provides:

Immediate clarity on code organization
Perfect scalability for growing platforms
Industry-standard scoped package pattern
Self-documenting import statements

This is now the standard convention for all GoGrab Space modules.

Current Modules Using This Convention

As of November 6, 2025, the following modules use @module/ namespace:

Feature Modules:

@module/new-user-management - User CRUD operations

Structural Modules:

@module/sidebar-nav - Navigation sidebar component
@module/top-nav - Top navigation component
@module/footer - Footer component