📦 Modules - AI Agent Instructions

Directory: docs/english/GoGrab-Space/modules/
Last Updated: December 3, 2025
Session: 4

🎯 This Is the Heart of GoGrab Space

Everything in GoGrab Space is built with modules. Understanding this system is essential.

⚡ Required Reading Order

1. hybrid-module-creation.md - ⭐ START HERE - The revolutionary approach
2. module-creation-guide.md - Complete creation guide
3. module-registration.md - How modules register
4. modules-architechture.md - Why modules are NX libraries
5. public-actions-guide.md - Creating cross-module actions
6. embeddable-components-guide.md - Creating widgets

📁 Directory Contents

modules/
├── AGENTS.md                        <- You are here
├── index.mdc                        # Main index
│
├── hybrid-module-creation.md        # ⭐ The hybrid approach (visual + code)
├── module-creation-guide.md         # Complete guide (both methods)
├── module-registration.md           # Registration & discovery system
├── modules-architechture.md         # Why NX libraries
├── modules-naming-convention.md     # Naming standards
├── public-actions-guide.md          # Action development
├── embeddable-components-guide.md   # Widget development
├── user-management-reference.md     # Reference implementation
│
├── modules-docs/                    # Individual module documentation
│   ├── user-management/             # User Management module
│   ├── product-catalog/             # Product Catalog module
│   ├── analytics/                   # Analytics module
│   └── sidebar/                     # Sidebar module
│
├── architecture/                    # Module-specific architecture docs
├── planning/                        # Planning documents
├── progress-notes/                  # Progress tracking
└── archive/                         # Archived docs (don't use)

🏗️ Two Module Systems

1. BrowserModuleContract (Platform Tools)

Used for: Platform infrastructure like Singularity, Editor, Widget Builder

@ModuleDecorator({ id: 'my-module', version: '1.0.0' })
@Injectable({ providedIn: 'root' })
export class MyModule implements BrowserModuleContract {
  readonly manifest: ModuleManifest = { /* ... */ };
  
  configure(config: any): Observable<void> { /* ... */ }
  initialize(): Observable<void> { /* ... */ }
  start(): Observable<void> { /* ... */ }
  stop(): Observable<void> { /* ... */ }
  destroy(): Observable<void> { /* ... */ }
}

2. UniversalModule (User Content)

Used for: Space-builders creating their platforms

const myModule: UniversalModule = {
  id: 'products-galaxy',
  type: 'galaxy',
  name: 'Products',
  route: '/products',
  children: [/* nested modules */]
};

🔑 Key Concepts

Modules Are NX Libraries

Every module is an NX library in the monorepo. This provides:

• Proper dependency tracking
• Build optimization
• Code isolation
• Easy sharing

Modules Have Three Capabilities

1. Public Actions - Operations other modules can call
2. Embeddable Components - UI widgets for visual pages
3. Routes - Navigation routes they provide

The Module Workbench (modularity-lib)

Visual tool at /modularity with 6 steps:

1. Models - Define entities
2. State - Configure persistence
3. Actions - Create operations
4. UI - Design embeddables
5. Test - Test the module
6. Deploy - Export as NX library

⚠️ Important Notes

1. Read hybrid-module-creation.md first - Understand the approach
2. Modules use existing systems - storage-system, theme-system, backend-api
3. Check modules-docs/ for implementation examples
4. Ignore archive/ - Contains outdated documentation

🔗 Related Documentation

• Architecture: ../architecture/module-system.md
• Libraries: ../libs/libs-core/module-base/
• Current Tasks: ../sessions/ (latest file)

This folder contains the most important documentation for understanding GoGrab Space.