@dbs-portal/core-module-registry/README.md

Core module registry system for automatic module discovery and registration

# @dbs-portal/core-module-registry

Core module registry system for automatic module discovery and registration in the DBS Portal framework.

## Features

- 🔍 **Automatic Module Discovery** - Discovers modules from packages, configs, and runtime registration
- 📝 **Module Metadata Management** - Complete module metadata schema with validation
- ⚡ **High-Performance Caching** - Built-in caching system with TTL and memory management
- 🎯 **Event-Driven Architecture** - Real-time notifications for module changes
- 🔒 **Permission Integration** - Built-in permission and role-based filtering
- 📊 **Statistics & Monitoring** - Comprehensive stats and performance monitoring
- 🛡️ **TypeScript-First** - Full TypeScript support with strict typing
- 🌐 **Universal Compatibility** - Works in both browser and Node.js environments

## Installation

```bash
yarn add @dbs-portal/core-module-registry
```

## Quick Start

```typescript
import { ModuleRegistry } from '@dbs-portal/core-module-registry'

// Initialize registry
const registry = ModuleRegistry.getInstance()
await registry.initialize()

// Get all active modules
const modules = registry.getActiveModules()
console.log(`Found ${modules.length} active modules`)

// Register a new module
await registry.registerModule({
  id: 'my-module',
  name: 'My Module',
  version: '1.0.0',
  description: 'A sample module',
  category: 'business',
  icon: 'AppstoreOutlined',
  permissions: ['MyModule.View'],
  routes: [{
    path: '/my-module',
    component: 'MyModulePage'
  }],
  navigation: [{
    key: '/my-module',
    label: 'My Module',
    icon: 'AppstoreOutlined',
    path: '/my-module',
    category: 'business',
    order: 1
  }],
  dependencies: [],
  status: 'active',
  priority: 100,
  author: 'Your Name',
  license: 'MIT'
})
```

## Module Configuration

Create a `module.config.ts` file in your module directory:

```typescript
import { ModuleMetadata, ModuleCategory } from '@dbs-portal/core-module-registry'

export const moduleConfig: ModuleMetadata = {
  id: 'file-management',
  name: 'File Management',
  version: '1.0.0',
  description: 'Comprehensive file management system',
  category: ModuleCategory.CONTENT,
  icon: 'FileOutlined',
  permissions: ['FileManagement.View', 'FileManagement.Upload'],
  routes: [
    {
      path: '/files',
      component: 'FileManagementPage',
      permissions: ['FileManagement.View']
    }
  ],
  navigation: [
    {
      key: '/files',
      label: 'File Management',
      icon: 'FileOutlined',
      path: '/files',
      category: 'content',
      order: 1
    }
  ],
  dependencies: ['@dbs-portal/core-ui'],
  status: 'active',
  priority: 100,
  author: 'DBS Portal Team',
  license: 'MIT'
}
```

## API Reference

### ModuleRegistry

The main registry class for managing modules.

#### Methods

- `getInstance(options?)` - Get singleton instance
- `initialize()` - Initialize with automatic discovery
- `registerModule(metadata, source?)` - Register a module
- `unregisterModule(moduleId)` - Unregister a module
- `getModule(moduleId)` - Get specific module
- `getAllModules()` - Get all modules
- `getActiveModules()` - Get active modules only
- `getModulesByCategory(category)` - Get modules by category
- `searchModules(query)` - Search modules
- `addListener(listener)` - Add event listener

#### Events

```typescript
interface RegistryListener {
  onModuleRegistered?(module: ModuleMetadata): void
  onModuleUnregistered?(module: ModuleMetadata): void
  onModuleUpdated?(module: ModuleMetadata): void
  onRegistryInitialized?(modules: ModuleMetadata[]): void
  onRegistryError?(error: Error, moduleId?: string): void
}
```

### ModuleDiscoveryService

Service for discovering modules from various sources.

#### Discovery Strategies

1. **Package Scanning** - Scans for `@dbs-portal/module-*` packages
2. **Config Detection** - Finds `module.config.ts` files
3. **Runtime Registration** - Allows manual registration

#### Options

```typescript
interface DiscoveryOptions {
  packageScanPaths?: string[]
  configScanPaths?: string[]
  packageNamePattern?: string
  configFilePattern?: string
  enablePackageScanning?: boolean
  enableConfigDetection?: boolean
  enableRuntimeRegistration?: boolean
  validateModules?: boolean
  ignorePatterns?: string[]
}
```

### Module Metadata Schema

Complete module configuration schema:

```typescript
interface ModuleMetadata {
  // Core identification
  id: string
  name: string
  version: string
  description: string

  // Categorization
  category: ModuleCategory
  tags: string[]

  // Visual configuration
  icon: string
  color?: string

  // Security
  permissions: string[]
  roles?: string[]

  // Routing
  routes: ModuleRoute[]
  
  // Navigation
  navigation: NavigationItem[]

  // Dependencies
  dependencies: string[]

  // Status and metadata
  status: ModuleStatus
  priority: number
  author: string
  license: string

  // Optional features
  features?: Record<string, boolean>
  config?: Record<string, any>
}
```

## Advanced Usage

### Custom Discovery

```typescript
import { ModuleDiscoveryService } from '@dbs-portal/core-module-registry'

const discovery = new ModuleDiscoveryService({
  packageScanPaths: ['custom/modules/*'],
  configFilePattern: 'my-module.config.ts',
  validateModules: true
})

const modules = await discovery.discoverModules()
```

### Permission Filtering

```typescript
import { filterModulesByPermissions } from '@dbs-portal/core-module-registry'

const userPermissions = ['FileManagement.View', 'Chat.View']
const accessibleModules = filterModulesByPermissions(modules, userPermissions)
```

### Caching

```typescript
import { ModuleCache } from '@dbs-portal/core-module-registry'

const cache = new ModuleCache(10 * 60 * 1000) // 10 minutes TTL
cache.set('my-key', { data: 'value' })
const value = cache.get('my-key')
```

### Performance Monitoring

```typescript
import { measurePerformance } from '@dbs-portal/core-module-registry'

const { result, duration } = await measurePerformance(
  () => registry.discoverModules(),
  'Module Discovery'
)
```

## Integration with DBS Portal

### Router Integration

```typescript
// src/routes/dynamic.routes.ts
import { ModuleRegistry } from '@dbs-portal/core-module-registry'

export const createDynamicRoutes = async () => {
  const registry = ModuleRegistry.getInstance()
  const modules = registry.getActiveModules()
  
  return modules.flatMap(module => 
    module.routes.map(route => ({
      path: route.path,
      component: lazy(() => import(route.component))
    }))
  )
}
```

### Navigation Integration

```typescript
// src/components/navigation/DynamicNavigation.tsx
import { ModuleRegistry, groupModulesByCategory } from '@dbs-portal/core-module-registry'

export const DynamicNavigation = () => {
  const registry = ModuleRegistry.getInstance()
  const modules = registry.getActiveModules()
  const groupedModules = groupModulesByCategory(modules)
  
  return (
    <Menu>
      {Object.entries(groupedModules).map(([category, categoryModules]) => (
        <SubMenu key={category} title={category}>
          {categoryModules.flatMap(module => 
            module.navigation.map(nav => (
              <Menu.Item key={nav.key} icon={nav.icon}>
                {nav.label}
              </Menu.Item>
            ))
          )}
        </SubMenu>
      ))}
    </Menu>
  )
}
```

## Development

```bash
# Install dependencies
yarn install

# Build the package
yarn build

# Run tests
yarn test

# Type checking
yarn type-check

# Linting
yarn lint
```

## License

MIT © DBS Portal Team