@morojs/moro 1.6.1 → 1.6.2

package/src/moro.ts

@@ -1,124 +1,106 @@
 // Moro Framework - Modern TypeScript API Framework
 // Built for developers who demand performance, elegance, and zero compromises
 // Event-driven • Modular • Enterprise-ready • Developer-first
-import { Moro as MoroCore } from './core/framework';
-import { HttpRequest, HttpResponse, middleware } from './core/http';
-import { ModuleConfig, InternalRouteDefinition } from './types/module';
-import { MoroOptions } from './types/core';
-import { MoroEventBus } from './core/events';
+import { Moro as MoroCore } from './core/framework.js';
+import { HttpRequest, HttpResponse, middleware } from './core/http/index.js';
+import { ModuleConfig, InternalRouteDefinition } from './types/module.js';
+import { MoroOptions } from './types/core.js';
+import { ModuleDefaultsConfig } from './types/config.js';
+import { MoroEventBus } from './core/events/index.js';
+import { createFrameworkLogger, applyLoggingConfiguration } from './core/logger/index.js';
+import { Logger } from './types/logger.js';
+import { MiddlewareManager } from './core/middleware/index.js';
+import { IntelligentRoutingManager } from './core/routing/app-integration.js';
+import { RouteSchema } from './core/routing/index.js';
 import {
-  createFrameworkLogger,
-  logger as globalLogger,
-  applyLoggingConfiguration,
-} from './core/logger';
-import { MiddlewareManager } from './core/middleware';
-import { IntelligentRoutingManager } from './core/routing/app-integration';
-import { RouteBuilder, RouteSchema, CompiledRoute } from './core/routing';
-import { AppDocumentationManager, DocsConfig } from './core/docs';
-import { readdirSync, statSync } from 'fs';
-import { join } from 'path';
+  UnifiedRouter,
+  RouteBuilder as UnifiedRouteBuilder,
+} from './core/routing/unified-router.js';
+import { AppDocumentationManager, DocsConfig } from './core/docs/index.js';
 import { EventEmitter } from 'events';
+import cluster from 'cluster';
+import os from 'os';
+import { normalizeValidationError } from './core/validation/schema-interface.js';
 // Configuration System Integration
-import { initializeConfig, getGlobalConfig, type AppConfig } from './core/config';
+import { initializeConfig, type AppConfig } from './core/config/index.js';
 // Runtime System Integration
-import {
-  RuntimeAdapter,
-  RuntimeType,
-  createRuntimeAdapter,
-  NodeRuntimeAdapter,
-} from './core/runtime';
+import { RuntimeAdapter, RuntimeType, createRuntimeAdapter } from './core/runtime/index.js';
 
 export class Moro extends EventEmitter {
-  private coreFramework: MoroCore;
+  private coreFramework!: MoroCore;
   private routes: InternalRouteDefinition[] = [];
   private moduleCounter = 0;
   private loadedModules = new Set<string>();
+  private lazyModules = new Map<string, ModuleConfig>();
   private routeHandlers: Record<string, Function> = {};
+  private moduleDiscovery?: any; // Store for cleanup
+  private autoDiscoveryOptions: MoroOptions | null = null;
+  private autoDiscoveryInitialized = false;
+  private autoDiscoveryPromise: Promise<void> | null = null;
   // Enterprise event system integration
-  private eventBus: MoroEventBus;
+  private eventBus!: MoroEventBus;
   // Application logger
-  private logger = createFrameworkLogger('App');
-  // Intelligent routing system
-  private intelligentRouting = new IntelligentRoutingManager();
+  private logger!: Logger;
+  // Unified routing system (singleton - shared across all routers)
+  private unifiedRouter!: UnifiedRouter;
+  // Legacy intelligent routing (kept for backward compatibility, now a facade)
+  private intelligentRouting!: IntelligentRoutingManager;
   // Documentation system
   private documentation = new AppDocumentationManager();
   // Configuration system
-  private config: AppConfig;
+  private config!: AppConfig;
+  // Track if user explicitly set logger options (for worker log level handling)
+  private userSetLogger = false;
   // Runtime system
-  private runtimeAdapter: RuntimeAdapter;
-  private runtimeType: RuntimeType;
+  private runtimeAdapter!: RuntimeAdapter;
+  private runtimeType!: RuntimeType;
   // Middleware system
-  private middlewareManager: MiddlewareManager;
+  private middlewareManager!: MiddlewareManager;
+  // Queued WebSocket registrations (for async adapter detection)
+  private queuedWebSocketRegistrations: Array<{
+    namespace: string;
+    handlers: Record<string, Function>;
+    processed: boolean;
+  }> = [];
 
   constructor(options: MoroOptions = {}) {
     super(); // Call EventEmitter constructor
 
-    // Configure logger from environment variables BEFORE config system initialization
-    // This ensures the config loading process respects the log level
+    // Track if user explicitly set logger/logging options
+    this.userSetLogger = !!(options.logger || options.logging);
+
+    // Apply logging configuration BEFORE config loading to avoid DEBUG spam
+    // 1. Environment variables (base level)
     const envLogLevel = process.env.LOG_LEVEL || process.env.MORO_LOG_LEVEL;
     if (envLogLevel) {
       applyLoggingConfiguration({ level: envLogLevel }, undefined);
     }
 
-    // Initialize configuration system - create a deep copy for this instance
-    this.config = JSON.parse(JSON.stringify(initializeConfig()));
-
-    // Apply logging configuration from the loaded config (this happens after config file processing)
-    if (this.config.logging) {
-      applyLoggingConfiguration(this.config.logging, undefined);
-    }
-
-    // Apply additional logging configuration from createApp options (takes precedence)
+    // 2. createApp logger options (highest precedence)
     if (options.logger !== undefined) {
       applyLoggingConfiguration(undefined, options.logger);
     }
 
-    // Apply performance configuration from createApp options (takes precedence)
-    if (options.performance) {
-      if (options.performance.clustering) {
-        this.config.performance.clustering = {
-          ...this.config.performance.clustering,
-          ...options.performance.clustering,
-        };
-      }
-      if (options.performance.compression) {
-        this.config.performance.compression = {
-          ...this.config.performance.compression,
-          ...options.performance.compression,
-        };
-      }
-      if (options.performance.circuitBreaker) {
-        this.config.performance.circuitBreaker = {
-          ...this.config.performance.circuitBreaker,
-          ...options.performance.circuitBreaker,
-        };
-      }
-    }
+    // Create logger AFTER initial configuration
+    this.logger = createFrameworkLogger('App');
 
-    // Apply modules configuration from createApp options (takes precedence)
-    if (options.modules) {
-      if (options.modules.cache) {
-        this.config.modules.cache = {
-          ...this.config.modules.cache,
-          ...options.modules.cache,
-        };
-      }
-      if (options.modules.rateLimit) {
-        this.config.modules.rateLimit = {
-          ...this.config.modules.rateLimit,
-          ...options.modules.rateLimit,
-        };
-      }
-      if (options.modules.validation) {
-        this.config.modules.validation = {
-          ...this.config.modules.validation,
-          ...options.modules.validation,
-        };
-      }
+    // Use simplified global configuration system
+    this.config = initializeConfig(options);
+
+    // Apply final config logging (this includes normalized logger → logging conversion)
+    // Always apply this as it's the authoritative merged config
+    if (this.config.logging) {
+      applyLoggingConfiguration(this.config.logging, undefined);
+      // Recreate logger with updated config
+      this.logger = createFrameworkLogger('App');
     }
 
+    // NOW initialize routing systems AFTER logger is configured
+    this.unifiedRouter = UnifiedRouter.getInstance();
+    this.intelligentRouting = new IntelligentRoutingManager();
+
     this.logger.info(
-      `Configuration system initialized: ${this.config.server.environment}:${this.config.server.port}`
+      `Configuration system initialized: ${process.env.NODE_ENV || 'development'}:${this.config.server.port}`
     );
 
     // Initialize runtime system
@@ -127,10 +109,16 @@ export class Moro extends EventEmitter {
 
     this.logger.info(`Runtime system initialized: ${this.runtimeType}`, 'Runtime');
 
-    // Pass logging configuration from config to framework
+    // Pass configuration from config to framework
     const frameworkOptions: any = {
       ...options,
       logger: this.config.logging,
+      // Enable websockets if either config has it enabled OR user passed websocket options
+      websocket:
+        this.config.websocket.enabled || options.websocket
+          ? options.websocket || this.config.websocket || {}
+          : false,
+      config: this.config,
     };
 
     this.coreFramework = new MoroCore(frameworkOptions);
@@ -162,10 +150,10 @@ export class Moro extends EventEmitter {
       ...options,
     });
 
-    // Auto-discover modules if enabled
-    if (options.autoDiscover !== false) {
-      this.autoDiscoverModules(options.modulesPath || './modules');
-    }
+    // Store auto-discovery options for later initialization
+    // IMPORTANT: Auto-discovery is deferred to ensure user middleware (like auth)
+    // is registered before module middleware that might bypass it
+    this.autoDiscoveryOptions = options.autoDiscover !== false ? options : null;
 
     // Emit initialization event through enterprise event bus
     this.eventBus.emit('framework:initialized', {
@@ -209,84 +197,85 @@ export class Moro extends EventEmitter {
 
   // Intelligent route methods - chainable with automatic middleware ordering
   // Overloads for better TypeScript inference
-  get(path: string): RouteBuilder;
+  get(path: string): UnifiedRouteBuilder;
   get(path: string, handler: (req: HttpRequest, res: HttpResponse) => any, options?: any): this;
   get(
     path: string,
     handler?: (req: HttpRequest, res: HttpResponse) => any,
     options?: any
-  ): RouteBuilder | this {
+  ): UnifiedRouteBuilder | this {
     if (handler) {
       // Direct route registration
       return this.addRoute('GET', path, handler, options);
     }
-    // Chainable route builder
-    return this.intelligentRouting.get(path);
+    // Use unified router for chainable API
+    return this.unifiedRouter.get(path);
   }
 
-  post(path: string): RouteBuilder;
+  post(path: string): UnifiedRouteBuilder;
   post(path: string, handler: (req: HttpRequest, res: HttpResponse) => any, options?: any): this;
   post(
     path: string,
     handler?: (req: HttpRequest, res: HttpResponse) => any,
     options?: any
-  ): RouteBuilder | this {
+  ): UnifiedRouteBuilder | this {
     if (handler) {
       // Direct route registration
       return this.addRoute('POST', path, handler, options);
     }
-    // Chainable route builder
-    return this.intelligentRouting.post(path);
+    // Use unified router for chainable API
+    return this.unifiedRouter.post(path);
   }
 
-  put(path: string): RouteBuilder;
+  put(path: string): UnifiedRouteBuilder;
   put(path: string, handler: (req: HttpRequest, res: HttpResponse) => any, options?: any): this;
   put(
     path: string,
     handler?: (req: HttpRequest, res: HttpResponse) => any,
     options?: any
-  ): RouteBuilder | this {
+  ): UnifiedRouteBuilder | this {
     if (handler) {
       // Direct route registration
       return this.addRoute('PUT', path, handler, options);
     }
-    // Chainable route builder
-    return this.intelligentRouting.put(path);
+    // Use unified router for chainable API
+    return this.unifiedRouter.put(path);
   }
 
-  delete(path: string): RouteBuilder;
+  delete(path: string): UnifiedRouteBuilder;
   delete(path: string, handler: (req: HttpRequest, res: HttpResponse) => any, options?: any): this;
   delete(
     path: string,
     handler?: (req: HttpRequest, res: HttpResponse) => any,
     options?: any
-  ): RouteBuilder | this {
+  ): UnifiedRouteBuilder | this {
     if (handler) {
       // Direct route registration
       return this.addRoute('DELETE', path, handler, options);
     }
-    // Chainable route builder
-    return this.intelligentRouting.delete(path);
+    // Use unified router for chainable API
+    return this.unifiedRouter.delete(path);
   }
 
-  patch(path: string): RouteBuilder;
+  patch(path: string): UnifiedRouteBuilder;
   patch(path: string, handler: (req: HttpRequest, res: HttpResponse) => any, options?: any): this;
   patch(
     path: string,
     handler?: (req: HttpRequest, res: HttpResponse) => any,
     options?: any
-  ): RouteBuilder | this {
+  ): UnifiedRouteBuilder | this {
     if (handler) {
       // Direct route registration
       return this.addRoute('PATCH', path, handler, options);
     }
-    // Chainable route builder
-    return this.intelligentRouting.patch(path);
+    // Use unified router for chainable API
+    return this.unifiedRouter.patch(path);
   }
 
   // Schema-first route method
-  route(schema: RouteSchema): CompiledRoute {
-    return this.intelligentRouting.route(schema);
+  route(schema: RouteSchema): void {
+    // Use unified router for schema-first registration
+    this.unifiedRouter.route(schema);
   }
 
   // Enable automatic API documentation
@@ -394,6 +383,13 @@ export class Moro extends EventEmitter {
         version: moduleOrPath.version || '1.0.0',
       });
     }
+
+    // IMPORTANT: If modules are loaded manually after auto-discovery,
+    // ensure the final module handler is set up to maintain middleware order
+    if (this.autoDiscoveryInitialized) {
+      this.coreFramework.setupFinalModuleHandler();
+    }
+
     return this;
   }
 
@@ -409,34 +405,45 @@ export class Moro extends EventEmitter {
 
   // WebSocket helper with events
   websocket(namespace: string, handlers: Record<string, Function>) {
+    // Queue the registration to be processed after adapter initialization
+    const registration = { namespace, handlers, processed: false };
+    this.queuedWebSocketRegistrations.push(registration);
+
+    // Try to process immediately if adapter is already ready
     const adapter = this.coreFramework.getWebSocketAdapter();
-    if (!adapter) {
-      throw new Error(
-        'WebSocket features require a WebSocket adapter. Install socket.io or configure an adapter:\n' +
-          'npm install socket.io\n' +
-          'or\n' +
-          'new Moro({ websocket: { adapter: new SocketIOAdapter() } })'
-      );
+    if (adapter && !registration.processed) {
+      // Adapter is ready, process immediately
+      this.processWebSocketRegistration(namespace, handlers, adapter);
+      registration.processed = true;
     }
+    // Otherwise, it will be processed when the server starts
 
+    return this;
+  }
+
+  private processWebSocketRegistration(
+    namespace: string,
+    handlers: Record<string, Function>,
+    adapter: any
+  ) {
     this.emit('websocket:registering', { namespace, handlers });
 
     const ns = adapter.createNamespace(namespace);
 
     Object.entries(handlers).forEach(([event, handler]) => {
-      ns.on('connection', socket => {
+      ns.on('connection', (socket: any) => {
         this.emit('websocket:connection', { namespace, event, socket });
 
-        socket.on(event, (data, callback) => {
+        socket.on(event, (data: any, callback: any) => {
           this.emit('websocket:event', { namespace, event, data });
 
           Promise.resolve(handler(socket, data))
-            .then(result => {
+            .then((result: any) => {
               this.emit('websocket:response', { namespace, event, result });
               if (callback) callback(result);
               else if (result) socket.emit(`${event}:response`, result);
             })
-            .catch(error => {
+            .catch((error: any) => {
               this.emit('websocket:error', { namespace, event, error });
               const errorResponse = { success: false, error: error.message };
               if (callback) callback(errorResponse);
@@ -447,7 +454,40 @@ export class Moro extends EventEmitter {
     });
 
     this.emit('websocket:registered', { namespace, handlers });
-    return this;
+  }
+
+  private async processQueuedWebSocketRegistrations() {
+    // Wait for WebSocket adapter to be ready
+    await this.coreFramework.ensureWebSocketReady();
+
+    const adapter = this.coreFramework.getWebSocketAdapter();
+
+    // Check if any unprocessed registrations exist
+    const unprocessedRegistrations = this.queuedWebSocketRegistrations.filter(r => !r.processed);
+
+    if (!adapter && unprocessedRegistrations.length > 0) {
+      throw new Error(
+        'WebSocket features require a WebSocket adapter.\n\n' +
+          'Option 1: Install socket.io (auto-detected):\n' +
+          '  npm install socket.io\n' +
+          '  const app = new Moro({ websocket: {} });\n\n' +
+          'Option 2: Configure a specific adapter:\n' +
+          "  import { SocketIOAdapter } from '@morojs/moro';\n" +
+          '  const app = new Moro({ websocket: { adapter: new SocketIOAdapter() } });\n\n' +
+          'Option 3: Enable in config file (moro.config.js):\n' +
+          '  export default { websocket: { enabled: true } };'
+      );
+    }
+
+    if (adapter) {
+      // Process all unprocessed registrations
+      for (const registration of this.queuedWebSocketRegistrations) {
+        if (!registration.processed) {
+          this.processWebSocketRegistration(registration.namespace, registration.handlers, adapter);
+          registration.processed = true;
+        }
+      }
+    }
   }
 
   // Start server with events (Node.js only)
@@ -503,9 +543,21 @@ export class Moro extends EventEmitter {
     }
 
     // Check if clustering is enabled for massive performance gains
+    // NOTE: uWebSockets.js does NOT support Node.js clustering - it's single-threaded only
+    const usingUWebSockets = this.config.server?.useUWebSockets || false;
+
     if (this.config.performance?.clustering?.enabled) {
-      this.startWithClustering(port, host as string, callback);
-      return;
+      if (usingUWebSockets) {
+        this.logger.warn(
+          'Clustering is not supported with uWebSockets.js - running in single-threaded mode. ' +
+            'uWebSockets is so fast that single-threaded performance often exceeds multi-threaded Node.js!',
+          'Cluster'
+        );
+        // Continue without clustering
+      } else {
+        this.startWithClustering(port, host as string, callback);
+        return;
+      }
     }
     this.eventBus.emit('server:starting', { port, runtime: this.runtimeType });
 
@@ -519,50 +571,200 @@ export class Moro extends EventEmitter {
       this.logger.debug('Documentation not enabled', 'Documentation');
     }
 
-    // Add intelligent routing middleware to handle chainable routes
-    this.coreFramework.addMiddleware(
-      async (req: HttpRequest, res: HttpResponse, next: () => void) => {
-        // Try intelligent routing first
-        const handled = await this.intelligentRouting.handleIntelligentRoute(req, res);
-        if (!handled) {
-          next(); // Fall back to direct routes
+    // Add unified routing middleware (handles both chainable and direct routes)
+    // Optimized: call router without extra async wrapper when possible
+    this.coreFramework.addMiddleware((req: HttpRequest, res: HttpResponse, next: () => void) => {
+      // Try unified router first (handles all route types)
+      const handled = this.unifiedRouter.handleRequest(req, res);
+
+      // Check if it's a promise (async route) or sync
+      if (handled && typeof (handled as any).then === 'function') {
+        // Async - await the result
+        (handled as Promise<boolean>)
+          .then(isHandled => {
+            if (!isHandled) {
+              next(); // Fall back to legacy routes if any
+            }
+          })
+          .catch(() => next());
+      } else {
+        // Sync - check immediately
+        if (!(handled as boolean)) {
+          next();
         }
       }
-    );
+    });
 
-    // Register direct routes with the HTTP server
+    // Register legacy direct routes with the HTTP server (for backward compatibility)
     if (this.routes.length > 0) {
       this.registerDirectRoutes();
     }
 
-    const actualCallback = () => {
-      const displayHost = host || 'localhost';
-      this.logger.info('Moro Server Started', 'Server');
-      this.logger.info(`Runtime: ${this.runtimeType}`, 'Server');
-      this.logger.info(`HTTP API: http://${displayHost}:${port}`, 'Server');
-      this.logger.info(`WebSocket: ws://${displayHost}:${port}`, 'Server');
-      this.logger.info('Native Node.js HTTP • Zero Dependencies • Maximum Performance', 'Server');
-      this.logger.info('Learn more at https://morojs.com', 'Server');
-
-      // Log intelligent routes info
-      const intelligentRoutes = this.intelligentRouting.getIntelligentRoutes();
-      if (intelligentRoutes.length > 0) {
-        this.logger.info(`Intelligent Routes: ${intelligentRoutes.length} registered`, 'Server');
+    const startServer = () => {
+      const actualCallback = () => {
+        const displayHost = host || 'localhost';
+        this.logger.info('Moro Server Started', 'Server');
+        this.logger.info(`Runtime: ${this.runtimeType}`, 'Server');
+        this.logger.info(`HTTP API: http://${displayHost}:${port}`, 'Server');
+        if (this.config.websocket.enabled) {
+          this.logger.info(`WebSocket: ws://${displayHost}:${port}`, 'Server');
+        }
+        this.logger.info('Learn more at https://morojs.com', 'Server');
+
+        // Log unified router stats
+        const routeCount = this.unifiedRouter.getRouteCount();
+        if (routeCount > 0) {
+          this.logger.info(`Unified Router: ${routeCount} routes registered`, 'Server');
+          // Log performance stats
+          this.unifiedRouter.logPerformanceStats();
+        }
+
+        this.eventBus.emit('server:started', { port, runtime: this.runtimeType });
+        if (callback) callback();
+      };
+
+      if (host && typeof host === 'string') {
+        this.coreFramework.listen(port, host, actualCallback);
+      } else {
+        this.coreFramework.listen(port, actualCallback);
       }
+    };
 
-      this.eventBus.emit('server:started', { port, runtime: this.runtimeType });
-      if (callback) callback();
+    // Ensure auto-discovery and WebSocket setup is complete before starting server
+    Promise.all([this.ensureAutoDiscoveryComplete(), this.processQueuedWebSocketRegistrations()])
+      .then(() => {
+        startServer();
+      })
+      .catch(error => {
+        this.logger.error('Initialization failed during server start', 'Framework', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+        // For auto-discovery failures, start server anyway
+        // For WebSocket failures with queued registrations, error will propagate
+        if (
+          error instanceof Error &&
+          error.message.includes('WebSocket features require a WebSocket adapter')
+        ) {
+          throw error;
+        }
+        startServer();
+      });
+  }
+
+  // Public method to manually initialize auto-discovery
+  // Useful for ensuring auth middleware is registered before auto-discovery
+  async initializeAutoDiscoveryNow(): Promise<void> {
+    return this.ensureAutoDiscoveryComplete();
+  }
+
+  // Public API: Initialize modules explicitly after middleware setup
+  // This provides users with explicit control over module loading timing
+  // IMPORTANT: This forces module loading even if autoDiscovery.enabled is false
+  // Usage: app.initModules() or app.initModules({ paths: ['./my-modules'] })
+  initModules(options?: {
+    paths?: string[];
+    patterns?: string[];
+    recursive?: boolean;
+    loadingStrategy?: 'eager' | 'lazy' | 'conditional';
+    watchForChanges?: boolean;
+    ignorePatterns?: string[];
+    loadOrder?: 'alphabetical' | 'dependency' | 'custom';
+    failOnError?: boolean;
+    maxDepth?: number;
+  }): void {
+    this.logger.info('User-requested module initialization', 'ModuleSystem');
+
+    // If already initialized, do nothing
+    if (this.autoDiscoveryInitialized) {
+      this.logger.debug('Auto-discovery already completed, skipping', 'ModuleSystem');
+      return;
+    }
+
+    // Store the options and mark that we want to force initialization
+    this.autoDiscoveryOptions = {
+      autoDiscover: {
+        enabled: true, // Force enabled regardless of original config
+        paths: options?.paths || ['./modules', './src/modules'],
+        patterns: options?.patterns || [
+          '**/*.module.{ts,js}',
+          '**/index.{ts,js}',
+          '**/*.config.{ts,js}',
+        ],
+        recursive: options?.recursive ?? true,
+        loadingStrategy: options?.loadingStrategy || ('eager' as const),
+        watchForChanges: options?.watchForChanges ?? false,
+        ignorePatterns: options?.ignorePatterns || [
+          '**/*.test.{ts,js}',
+          '**/*.spec.{ts,js}',
+          '**/node_modules/**',
+        ],
+        loadOrder: options?.loadOrder || ('dependency' as const),
+        failOnError: options?.failOnError ?? false,
+        maxDepth: options?.maxDepth ?? 5,
+      },
     };
 
-    if (host && typeof host === 'string') {
-      this.coreFramework.listen(port, host, actualCallback);
-    } else {
-      this.coreFramework.listen(port, actualCallback);
+    this.logger.debug(
+      'Module initialization options stored, will execute on next listen/getHandler call',
+      'ModuleSystem'
+    );
+  }
+
+  // Robust method to ensure auto-discovery is complete, handling race conditions
+  private async ensureAutoDiscoveryComplete(): Promise<void> {
+    // If already initialized, nothing to do
+    if (this.autoDiscoveryInitialized) {
+      return;
+    }
+
+    // If auto-discovery is disabled, mark as initialized
+    if (!this.autoDiscoveryOptions) {
+      this.autoDiscoveryInitialized = true;
+      return;
+    }
+
+    // If already in progress, wait for it to complete
+    if (this.autoDiscoveryPromise) {
+      return this.autoDiscoveryPromise;
+    }
+
+    // Start auto-discovery
+    this.autoDiscoveryPromise = this.performAutoDiscovery();
+
+    try {
+      await this.autoDiscoveryPromise;
+      this.autoDiscoveryInitialized = true;
+    } catch (error) {
+      // Reset promise on error so it can be retried
+      this.autoDiscoveryPromise = null;
+      throw error;
+    } finally {
+      this.autoDiscoveryOptions = null; // Clear after attempt
     }
   }
 
+  // Perform the actual auto-discovery work
+  private async performAutoDiscovery(optionsOverride?: MoroOptions): Promise<void> {
+    const optionsToUse = optionsOverride || this.autoDiscoveryOptions;
+    if (!optionsToUse) return;
+
+    this.logger.debug('Starting auto-discovery initialization', 'AutoDiscovery');
+
+    await this.initializeAutoDiscovery(optionsToUse);
+
+    this.logger.debug('Auto-discovery initialization completed', 'AutoDiscovery');
+  }
+
   // Get handler for non-Node.js runtimes
   getHandler() {
+    // Ensure auto-discovery is complete for non-Node.js runtimes
+    // This handles the case where users call getHandler() immediately after createApp()
+    this.ensureAutoDiscoveryComplete().catch(error => {
+      this.logger.error('Auto-discovery initialization failed for runtime handler', 'Framework', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    });
+
     // Create a unified request handler that works with the runtime adapter
     const handler = async (req: HttpRequest, res: HttpResponse) => {
       // Add documentation middleware first (if enabled)
@@ -574,11 +776,11 @@ export class Moro extends EventEmitter {
         // Documentation not enabled, that's fine
       }
 
-      // Try intelligent routing first
-      const handled = await this.intelligentRouting.handleIntelligentRoute(req, res);
+      // Try unified router first (handles all routes)
+      const handled = await this.unifiedRouter.handleRequest(req, res);
       if (handled) return;
 
-      // Handle direct routes
+      // Handle legacy direct routes (backward compatibility)
       if (this.routes.length > 0) {
         await this.handleDirectRoutes(req, res);
       }
@@ -745,8 +947,11 @@ export class Moro extends EventEmitter {
 
   // Private methods
   private addRoute(method: string, path: string, handler: Function, options: any = {}) {
-    const handlerName = `handler_${this.routes.length}`;
+    // Register with unified router (primary routing system)
+    this.unifiedRouter.addRoute(method as any, path, handler as any, options.middleware || []);
 
+    // Also store in legacy routes array for backward compatibility
+    const handlerName = `handler_${this.routes.length}`;
     const route = {
       method: method as any,
       path,
@@ -759,10 +964,10 @@ export class Moro extends EventEmitter {
 
     this.routes.push(route);
 
-    // Organize routes for optimal lookup
+    // Organize routes for optimal lookup (legacy)
     this.organizeRouteForLookup(route);
 
-    // Store handler for later module creation
+    // Store handler for later module creation (legacy)
     this.routeHandlers[handlerName] = handler;
 
     return this;
@@ -807,7 +1012,6 @@ export class Moro extends EventEmitter {
               req.body = validated;
             } catch (error: any) {
               // Handle universal validation errors
-              const { normalizeValidationError } = require('./core/validation/schema-interface');
               const normalizedError = normalizeValidationError(error);
               res.status(400).json({
                 success: false,
@@ -886,20 +1090,33 @@ export class Moro extends EventEmitter {
   }
 
   private setupDefaultMiddleware(options: MoroOptions) {
-    // CORS
-    if (options.cors !== false) {
-      const corsOptions = typeof options.cors === 'object' ? options.cors : {};
+    // CORS - check config enabled property OR options.security.cors.enabled === true
+    if (this.config.security.cors.enabled || options.security?.cors?.enabled === true) {
+      const corsOptions =
+        typeof options.cors === 'object'
+          ? options.cors
+          : this.config.security.cors
+            ? this.config.security.cors
+            : {};
       this.use(middleware.cors(corsOptions));
     }
 
-    // Helmet
-    if (options.helmet !== false) {
+    // Helmet - check config enabled property OR options.security.helmet.enabled === true
+    if (this.config.security.helmet.enabled || options.security?.helmet?.enabled === true) {
       this.use(middleware.helmet());
     }
 
-    // Compression
-    if (options.compression !== false) {
-      const compressionOptions = typeof options.compression === 'object' ? options.compression : {};
+    // Compression - check config enabled property OR options.performance.compression.enabled === true
+    if (
+      this.config.performance.compression.enabled ||
+      options.performance?.compression?.enabled === true
+    ) {
+      const compressionOptions =
+        typeof options.compression === 'object'
+          ? options.compression
+          : this.config.performance.compression
+            ? this.config.performance.compression
+            : {};
       this.use(middleware.compression(compressionOptions));
     }
 
@@ -907,27 +1124,216 @@ export class Moro extends EventEmitter {
     this.use(middleware.bodySize({ limit: '10mb' }));
   }
 
-  private autoDiscoverModules(modulesPath: string) {
+  // Enhanced auto-discovery initialization
+  private async initializeAutoDiscovery(options: MoroOptions): Promise<void> {
+    const { ModuleDiscovery } = await import('./core/modules/auto-discovery.js');
+
+    // Merge auto-discovery configuration
+    const autoDiscoveryConfig = this.mergeAutoDiscoveryConfig(options);
+
+    if (!autoDiscoveryConfig.enabled) {
+      return;
+    }
+
+    this.moduleDiscovery = new ModuleDiscovery(process.cwd());
+
     try {
-      if (!statSync(modulesPath).isDirectory()) return;
-
-      const items = readdirSync(modulesPath);
-      items.forEach(item => {
-        const fullPath = join(modulesPath, item);
-        if (statSync(fullPath).isDirectory()) {
-          const indexPath = join(fullPath, 'index.ts');
-          try {
-            statSync(indexPath);
-            // Module directory found, will be loaded later
-            this.logger.debug(`Discovered module: ${item}`, 'ModuleDiscovery');
-          } catch {
-            // No index.ts, skip
+      // Discover modules based on configuration
+      const modules = await this.moduleDiscovery.discoverModulesAdvanced(autoDiscoveryConfig);
+
+      // Load modules based on strategy
+      await this.loadDiscoveredModules(modules, autoDiscoveryConfig);
+
+      // Setup final module handler to run after user middleware (like auth)
+      this.coreFramework.setupFinalModuleHandler();
+
+      // Setup file watching if enabled
+      if (autoDiscoveryConfig.watchForChanges) {
+        this.moduleDiscovery.watchModulesAdvanced(
+          autoDiscoveryConfig,
+          async (updatedModules: ModuleConfig[]) => {
+            await this.handleModuleChanges(updatedModules);
           }
+        );
+      }
+
+      this.logger.info(
+        `Auto-discovery completed: ${modules.length} modules loaded`,
+        'ModuleDiscovery'
+      );
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+
+      if (autoDiscoveryConfig.failOnError) {
+        throw new Error(`Module auto-discovery failed: ${errorMsg}`);
+      } else {
+        this.logger.warn(`Module auto-discovery failed: ${errorMsg}`, 'ModuleDiscovery');
+      }
+    }
+  }
+
+  // Merge auto-discovery configuration from multiple sources
+  private mergeAutoDiscoveryConfig(options: MoroOptions) {
+    const defaultConfig = this.config.modules.autoDiscovery;
+
+    // Handle legacy modulesPath option
+    if (options.modulesPath && !options.autoDiscover) {
+      return {
+        ...defaultConfig,
+        paths: [options.modulesPath],
+      };
+    }
+
+    // Handle boolean autoDiscover option
+    if (typeof options.autoDiscover === 'boolean') {
+      return {
+        ...defaultConfig,
+        enabled: options.autoDiscover,
+      };
+    }
+
+    // Handle object autoDiscover option
+    if (typeof options.autoDiscover === 'object') {
+      return {
+        ...defaultConfig,
+        ...options.autoDiscover,
+      };
+    }
+
+    return defaultConfig;
+  }
+
+  // Load discovered modules based on strategy
+  private async loadDiscoveredModules(
+    modules: ModuleConfig[],
+    config: ModuleDefaultsConfig['autoDiscovery']
+  ): Promise<void> {
+    switch (config.loadingStrategy) {
+      case 'eager':
+        // Load all modules immediately
+        for (const module of modules) {
+          await this.loadModule(module);
         }
-      });
-    } catch {
-      // Modules directory doesn't exist, that's fine
+        break;
+
+      case 'lazy':
+        // Register modules for lazy loading
+        this.registerLazyModules(modules);
+        break;
+
+      case 'conditional':
+        // Load modules based on conditions
+        await this.loadConditionalModules(modules);
+        break;
+
+      default:
+        // Default to eager loading
+        for (const module of modules) {
+          await this.loadModule(module);
+        }
+    }
+  }
+
+  // Register modules for lazy loading
+  private registerLazyModules(modules: ModuleConfig[]): void {
+    modules.forEach(module => {
+      // Store module for lazy loading when first route is accessed
+      this.lazyModules.set(module.name, module);
+
+      // Register placeholder routes that trigger lazy loading
+      if (module.routes) {
+        module.routes.forEach(route => {
+          const basePath = `/api/v${module.version}/${module.name}`;
+          const fullPath = `${basePath}${route.path}`;
+
+          // Note: Lazy loading will be implemented when route is accessed
+          // For now, we'll store the module for later loading
+          this.logger.debug(
+            `Registered lazy route: ${route.method} ${fullPath}`,
+            'ModuleDiscovery'
+          );
+        });
+      }
+    });
+
+    this.logger.info(`Registered ${modules.length} modules for lazy loading`, 'ModuleDiscovery');
+  }
+
+  // Load modules conditionally based on environment or configuration
+  private async loadConditionalModules(modules: ModuleConfig[]): Promise<void> {
+    for (const module of modules) {
+      const shouldLoad = this.shouldLoadModule(module);
+
+      if (shouldLoad) {
+        await this.loadModule(module);
+      } else {
+        this.logger.debug(`Skipping module ${module.name} due to conditions`, 'ModuleDiscovery');
+      }
+    }
+  }
+
+  // Determine if a module should be loaded based on conditions
+  private shouldLoadModule(module: ModuleConfig): boolean {
+    const moduleConfig = module.config as any;
+
+    // Check environment conditions
+    if (moduleConfig?.conditions?.environment) {
+      const requiredEnv = moduleConfig.conditions.environment;
+      const currentEnv = process.env.NODE_ENV || 'development';
+
+      if (Array.isArray(requiredEnv)) {
+        if (!requiredEnv.includes(currentEnv)) {
+          return false;
+        }
+      } else if (requiredEnv !== currentEnv) {
+        return false;
+      }
+    }
+
+    // Check feature flags
+    if (moduleConfig?.conditions?.features) {
+      const requiredFeatures = moduleConfig.conditions.features;
+
+      for (const feature of requiredFeatures) {
+        if (!process.env[`FEATURE_${feature.toUpperCase()}`]) {
+          return false;
+        }
+      }
+    }
+
+    // Check custom conditions
+    if (moduleConfig?.conditions?.custom) {
+      const customCondition = moduleConfig.conditions.custom;
+
+      if (typeof customCondition === 'function') {
+        return customCondition();
+      }
     }
+
+    return true;
+  }
+
+  // Handle module changes during development
+  private async handleModuleChanges(modules: ModuleConfig[]): Promise<void> {
+    this.logger.info('Module changes detected, reloading...', 'ModuleDiscovery');
+
+    // Unload existing modules (if supported)
+    // For now, just log the change
+    this.eventBus.emit('modules:changed', {
+      modules: modules.map(m => ({ name: m.name, version: m.version })),
+      timestamp: new Date(),
+    });
+  }
+
+  // Legacy method for backward compatibility
+  private autoDiscoverModules(modulesPath: string) {
+    // Redirect to new system
+    this.initializeAutoDiscovery({
+      autoDiscover: {
+        enabled: true,
+        paths: [modulesPath],
+      },
+    });
   }
 
   private async importModule(modulePath: string): Promise<ModuleConfig> {
@@ -935,55 +1341,81 @@ export class Moro extends EventEmitter {
     return module.default || module;
   }
 
-  // Clustering support for massive performance gains with proper cleanup
+  /**
+   * Node.js Clustering Implementation
+   * This clustering algorithm is based on published research and Node.js best practices.
+   *
+   * IPC (Inter-Process Communication) Considerations:
+   * - Excessive workers create IPC bottlenecks (Source: BetterStack Node.js Guide)
+   * - Round-robin scheduling provides better load distribution (Node.js Documentation)
+   * - Message passing overhead increases significantly with worker count
+   *
+   * Memory Management:
+   * - ~2GB per worker prevents memory pressure and GC overhead
+   * - Conservative heap limits reduce memory fragmentation
+   *
+   * References:
+   * - Node.js Cluster Documentation: https://nodejs.org/api/cluster.html
+   * - BetterStack Node.js Clustering: https://betterstack.com/community/guides/scaling-nodejs/node-clustering/
+   */
   private clusterWorkers = new Map<number, any>();
-  private startWithClustering(port: number, host?: string, callback?: () => void): void {
-    const cluster = require('cluster');
-    const os = require('os');
 
-    // Smart worker count calculation based on actual bottlenecks
+  private startWithClustering(port: number, host?: string, callback?: () => void): void {
+    // Worker count calculation - respect user choice
     let workerCount = this.config.performance?.clustering?.workers || os.cpus().length;
 
-    // Auto-optimize worker count based on system characteristics
-    if (workerCount === 'auto' || workerCount > 8) {
-      // For high-core machines, limit workers to prevent IPC/memory bottlenecks
+    // Only auto-optimize if user hasn't specified a number or set it to 'auto'
+    if (workerCount === 'auto') {
       const cpuCount = os.cpus().length;
       const totalMemoryGB = os.totalmem() / (1024 * 1024 * 1024);
 
-      // Optimal worker count formula based on research
-      if (cpuCount >= 16) {
-        // High-core machines: focus on memory/IPC efficiency
-        workerCount = Math.min(Math.ceil(totalMemoryGB / 2), 4); // 2GB per worker max, cap at 4
-      } else if (cpuCount >= 8) {
-        // Mid-range machines: balanced approach
-        workerCount = Math.min(cpuCount / 2, 4);
-      } else {
-        // Low-core machines: use all cores
-        workerCount = cpuCount;
+      // Get memory per worker from config - if not set by user, calculate dynamically
+      let memoryPerWorkerGB = this.config.performance?.clustering?.memoryPerWorkerGB;
+
+      if (!memoryPerWorkerGB) {
+        // Dynamic calculation: (Total RAM - 4GB headroom) / CPU cores
+        const headroomGB = 4;
+        memoryPerWorkerGB = Math.max(0.5, Math.floor((totalMemoryGB - headroomGB) / cpuCount));
       }
 
+      // Conservative formula based on general guidelines:
+      // - Don't exceed CPU cores
+      // - Respect user's memory allocation preference
+      // - Let the system resources determine the limit
+      workerCount = Math.min(
+        cpuCount, // Don't exceed CPU cores
+        Math.floor(totalMemoryGB / memoryPerWorkerGB) // User-configurable memory per worker
+      );
+
       this.logger.info(
-        `Auto-optimized workers: ${workerCount} (CPU: ${cpuCount}, RAM: ${totalMemoryGB.toFixed(1)}GB)`,
+        `Auto-calculated worker count: ${workerCount} (CPU: ${cpuCount}, RAM: ${totalMemoryGB.toFixed(1)}GB, ${memoryPerWorkerGB}GB per worker)`,
         'Cluster'
       );
+    } else if (typeof workerCount === 'number') {
+      // User specified a number - respect their choice
+      this.logger.info(`Using user-specified worker count: ${workerCount}`, 'Cluster');
     }
 
     if (cluster.isPrimary) {
-      this.logger.info(`🚀 Starting ${workerCount} workers for maximum performance`, 'Cluster');
+      this.logger.info(`Starting ${workerCount} workers`, 'Cluster');
 
       // Optimize cluster scheduling for high concurrency
-      cluster.schedulingPolicy = cluster.SCHED_RR; // Round-robin scheduling
+      // Round-robin is the default on all platforms except Windows (Node.js docs)
+      // Provides better load distribution than shared socket approach
+      cluster.schedulingPolicy = cluster.SCHED_RR;
 
       // Set cluster settings for better performance
       cluster.setupMaster({
-        exec: process.argv[1],
+        exec: process.argv[1] || process.execPath,
         args: process.argv.slice(2),
         silent: false,
       });
 
-      // Optimize IPC to reduce communication overhead
+      // IPC Optimization: Reduce communication overhead between master and workers
+      // Research shows excessive IPC can create bottlenecks in clustered applications
+      // (Source: BetterStack - Node.js Clustering Guide)
       process.env.NODE_CLUSTER_SCHED_POLICY = 'rr'; // Ensure round-robin
-      process.env.NODE_DISABLE_COLORS = '1'; // Reduce IPC message size
+      process.env.NODE_DISABLE_COLORS = '1'; // Reduce IPC message size by disabling color codes
 
       // Graceful shutdown handler
       const gracefulShutdown = () => {
@@ -1004,37 +1436,32 @@ export class Moro extends EventEmitter {
       process.on('SIGINT', gracefulShutdown);
       process.on('SIGTERM', gracefulShutdown);
 
-      // Fork workers with proper tracking and CPU affinity
+      // Fork workers with basic tracking
       for (let i = 0; i < workerCount; i++) {
-        const worker = cluster.fork({
-          WORKER_ID: i,
-          WORKER_CPU_AFFINITY: i % os.cpus().length, // Distribute workers across CPUs
-        });
+        const worker = cluster.fork();
         this.clusterWorkers.set(worker.process.pid!, worker);
-        this.logger.info(
-          `Worker ${worker.process.pid} started (CPU ${i % os.cpus().length})`,
-          'Cluster'
-        );
+        this.logger.info(`Worker ${worker.process.pid} started`, 'Cluster');
 
-        // Handle individual worker messages (reuse handler)
+        // Handle individual worker messages
         worker.on('message', this.handleWorkerMessage.bind(this));
       }
 
-      // Handle worker exits with cleanup
+      // Simple worker exit handling
       cluster.on('exit', (worker: any, code: number, signal: string) => {
-        // Clean up worker tracking
-        this.clusterWorkers.delete(worker.process.pid);
-
-        this.logger.warn(
-          `Worker ${worker.process.pid} died (${signal || code}). Restarting...`,
-          'Cluster'
-        );
-
-        // Restart worker with proper tracking
-        const newWorker = cluster.fork();
-        this.clusterWorkers.set(newWorker.process.pid!, newWorker);
-        newWorker.on('message', this.handleWorkerMessage.bind(this));
-        this.logger.info(`Worker ${newWorker.process.pid} started`, 'Cluster');
+        const pid = worker.process.pid;
+        this.clusterWorkers.delete(pid);
+
+        if (code !== 0 && !worker.exitedAfterDisconnect) {
+          this.logger.warn(
+            `Worker ${pid} died unexpectedly (${signal || code}). Restarting...`,
+            'Cluster'
+          );
+
+          // Simple restart
+          const newWorker = cluster.fork();
+          this.clusterWorkers.set(newWorker.process.pid!, newWorker);
+          this.logger.info(`Worker ${newWorker.process.pid} restarted`, 'Cluster');
+        }
       });
 
       // Master process callback
@@ -1047,17 +1474,33 @@ export class Moro extends EventEmitter {
       process.env.UV_THREADPOOL_SIZE = '64';
 
       // Reduce logging contention in workers (major bottleneck)
-      if (this.config.logging) {
-        // Workers log less frequently to reduce I/O contention
-        this.config.logging.level = 'warn'; // Only warnings and errors
+      // Multiple workers writing to same log files creates I/O contention
+      // ONLY reduce log level if user didn't explicitly set one
+      if (!this.userSetLogger) {
+        // Workers log less frequently to reduce I/O contention (only if not explicitly configured)
+        applyLoggingConfiguration(undefined, { level: 'warn' }); // Only warnings and errors
       }
 
-      // Memory optimization for workers
-      process.env.NODE_OPTIONS = '--max-old-space-size=1024'; // Limit memory per worker
+      // Research-based memory optimization for workers
+      const totalMemoryGB = os.totalmem() / (1024 * 1024 * 1024);
+      const workerCount = Object.keys(cluster.workers || {}).length || 1;
+
+      // Conservative memory allocation
+      const heapSizePerWorkerMB = Math.min(
+        Math.floor(((totalMemoryGB * 1024) / workerCount) * 0.8), // 80% of available memory
+        1536 // Cap at 1.5GB (GC efficiency threshold from research)
+      );
+
+      process.env.NODE_OPTIONS = `--max-old-space-size=${heapSizePerWorkerMB}`;
 
-      // Optimize V8 flags for better performance (Rust-level optimizations)
+      this.logger.debug(
+        `Worker memory allocated: ${heapSizePerWorkerMB}MB heap (${workerCount} workers, ${totalMemoryGB.toFixed(1)}GB total)`,
+        'Worker'
+      );
+
+      // Optimize V8 flags for better performance
       if (process.env.NODE_ENV === 'production') {
-        // Ultra-aggressive V8 optimizations for maximum performance
+        // Aggressive V8 optimizations for maximum performance
         const v8Flags = [
           '--optimize-for-size', // Trade memory for speed
           '--always-opt', // Always optimize functions
@@ -1116,17 +1559,31 @@ export class Moro extends EventEmitter {
         // Documentation not enabled, that's fine
       }
 
-      // Add intelligent routing middleware
-      this.coreFramework.addMiddleware(
-        async (req: HttpRequest, res: HttpResponse, next: () => void) => {
-          const handled = await this.intelligentRouting.handleIntelligentRoute(req, res);
-          if (!handled) {
+      // Add unified routing middleware (handles both chainable and direct routes)
+      // Optimized: call router without extra async wrapper when possible
+      this.coreFramework.addMiddleware((req: HttpRequest, res: HttpResponse, next: () => void) => {
+        // Try unified router first (handles all route types)
+        const handled = this.unifiedRouter.handleRequest(req, res);
+
+        // Check if it's a promise (async route) or sync
+        if (handled && typeof (handled as any).then === 'function') {
+          // Async - await the result
+          (handled as Promise<boolean>)
+            .then(isHandled => {
+              if (!isHandled) {
+                next(); // Fall back to legacy routes if any
+              }
+            })
+            .catch(() => next());
+        } else {
+          // Sync - check immediately
+          if (!(handled as boolean)) {
             next();
           }
         }
-      );
+      });
 
-      // Register direct routes
+      // Register legacy direct routes with the HTTP server (for backward compatibility)
       if (this.routes.length > 0) {
         this.registerDirectRoutes();
       }
@@ -1141,15 +1598,37 @@ export class Moro extends EventEmitter {
         });
       };
 
-      if (host) {
-        this.coreFramework.listen(port, host, workerCallback);
-      } else {
-        this.coreFramework.listen(port, workerCallback);
-      }
+      // Ensure WebSocket setup is complete before starting worker
+      this.processQueuedWebSocketRegistrations()
+        .then(() => {
+          if (host) {
+            this.coreFramework.listen(port, host, workerCallback);
+          } else {
+            this.coreFramework.listen(port, workerCallback);
+          }
+        })
+        .catch(error => {
+          this.logger.error('WebSocket initialization failed in worker', 'Worker', {
+            error: error instanceof Error ? error.message : String(error),
+          });
+          // For WebSocket failures with queued registrations, error will propagate
+          if (
+            error instanceof Error &&
+            error.message.includes('WebSocket features require a WebSocket adapter')
+          ) {
+            throw error;
+          }
+          // Start anyway for other errors
+          if (host) {
+            this.coreFramework.listen(port, host, workerCallback);
+          } else {
+            this.coreFramework.listen(port, workerCallback);
+          }
+        });
     }
   }
 
-  // Reusable worker message handler (avoids creating new functions)
+  // Simple worker message handler
   private handleWorkerMessage(message: any): void {
     // Handle inter-worker communication if needed
     if (message.type === 'health-check') {
@@ -1160,6 +1639,58 @@ export class Moro extends EventEmitter {
     // Log other worker messages
     this.logger.debug(`Worker message: ${JSON.stringify(message)}`, 'Cluster');
   }
+
+  /**
+   * Gracefully close the application and clean up resources
+   * This should be called in tests and during shutdown
+   */
+  async close(): Promise<void> {
+    this.logger.debug('Closing Moro application...');
+
+    // Flush logger buffer before shutdown
+    try {
+      // Use flushBuffer for immediate synchronous flush
+      this.logger.flushBuffer();
+    } catch (error) {
+      // Ignore flush errors during shutdown
+    }
+
+    // Close the core framework with timeout
+    if (this.coreFramework && (this.coreFramework as any).httpServer) {
+      try {
+        await Promise.race([
+          new Promise<void>(resolve => {
+            (this.coreFramework as any).httpServer.close(() => {
+              resolve();
+            });
+          }),
+          new Promise<void>(resolve => setTimeout(resolve, 2000)), // 2 second timeout
+        ]);
+      } catch (error) {
+        // Force close if graceful close fails
+        this.logger.warn('Force closing HTTP server due to timeout');
+      }
+    }
+
+    // Clean up module discovery watchers
+    if (this.moduleDiscovery && typeof this.moduleDiscovery.cleanup === 'function') {
+      try {
+        this.moduleDiscovery.cleanup();
+      } catch (error) {
+        // Ignore cleanup errors
+      }
+    }
+
+    // Clean up event listeners
+    try {
+      this.eventBus.removeAllListeners();
+      this.removeAllListeners();
+    } catch (error) {
+      // Ignore cleanup errors
+    }
+
+    this.logger.debug('Moro application closed successfully');
+  }
 }
 
 // Export convenience function