@wildo-ai/saas-backend-lib 1.0.1

package/src/runtime/services/start-application.backend.service.ts

@@ -0,0 +1,1109 @@
+import 'reflect-metadata';
+import { injectable, inject } from 'inversify';
+import type { ResourceConfiguration_InitializationFactoryMap, ResourceRelationship, ResourcesRegistry, ResourceType, RolesConfiguration, FlowsActors_Agent, ResourceConfiguration, FeatureDefinitionWithAutoRegister, FeatureConfiguration, ScopeFeatures, MilestoneDefinition } from '@wildo-ai/saas-models';
+import type { FlowActorSystem_InitializationFactoryMap } from '~wildo-backend-lib/flows-actors/models/flows-actors.backend.schemas';
+import type { ProviderCatalog } from '@wildo-ai/external-connectors-models';
+import { ErrorType, ErrorCustomMessageReference, FeatureUnavailabilityBehavior, FeatureUnavailabilityReason, BILLING_RESOURCE_TYPES, BILLING_SCOPE_RESOURCE_TYPES, BILLING_SCOPES, LIFECYCLE_RESOURCE_TYPES, ActivationCriterionType, ResourcePrimaryScope, CoreResourceType } from '@wildo-ai/saas-models';
+import type { LifecycleConfig } from '@wildo-ai/saas-models';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { AppConfigurationService } from '~wildo-backend-lib/config/services/app-configuration.backend.service';
+import { ApplicationStartupConfigValidatorService } from '~wildo-backend-lib/config/services/application-startup-config-validator.backend.service';
+import type { AppConfiguration } from '~wildo-backend-lib/config/models/app-config.backend.schemas';
+import type { AppConfiguration_BackendAuthored } from '~wildo-backend-lib/config/models/app-config.backend-authored.definitions';
+import { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';
+import { ExternalProvidersRegistryBackendService } from '~wildo-backend-lib/external-providers/services/external-providers-registry.backend.service';
+import { LazyProviderRegistryBackendService } from '~wildo-backend-lib/external-providers/services/lazy-provider-registry.backend.service';
+import { CapabilityBindingsBackendService } from '~wildo-backend-lib/external-providers/services/feature-bindings.backend.service';
+import { FeatureDefinitionRegistryBackendService } from '~wildo-backend-lib/features/services/feature-definition-registry.backend.service';
+import { MilestoneDefinitionRegistryBackendService } from '~wildo-backend-lib/guidance/services/milestone-definition-registry.backend.service';
+import { MilestoneConditionRegistryBackendService } from '~wildo-backend-lib/guidance/services/milestone-condition-registry.backend.service';
+import type { MilestoneConditionFn } from '~wildo-backend-lib/guidance/services/milestone-condition-registry.backend.service';
+import { LifecycleEvaluatorBackendService } from '~wildo-backend-lib/guidance/services/lifecycle-evaluator.backend.service';
+import { initializeLifecycleCustomImplementations } from '~wildo-backend-lib/guidance/services/lifecycle-custom-implementations.backend';
+import { createDormancyDetectionBatch, DORMANCY_DETECTION_BATCH_REF } from '~wildo-backend-lib/guidance/batches/dormancy-detection.batch.backend.service';
+import { FlowsActorsRegistryService } from '~wildo-backend-lib/flows-actors/services/flows-actors-registry.service';
+import { RepositoriesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/repositories/repositories-registry-handler.backend.service';
+import { ServicesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/services/services-registry-handler.backend.service';
+import { ControllersRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/controllers/controllers-registry-handler.backend.service';
+import { AbstractControllerBackendService } from '~wildo-backend-lib/base-classes/services/controllers/abstract-controller.backend.service';
+import { getManualControllersBackend } from '~wildo-backend-lib/base-classes/models/manual-controllers.backend.definition';
+import { HttpServerBackendService } from './http-server.backend.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import { ErrorHandlerService } from '~wildo-backend-lib/errors/services/error-handler.backend.service';
+import { AuthorizationsBackendService } from '~wildo-backend-lib/security/authorizations/services/authorizations.backend.service';
+import { BatchesCronjobsExecutor_BackendService } from '~wildo-backend-lib/base-classes/services/batches/batches-cronjobs-executor.backend.service';
+import { BatchesCronjobsCustomExecution_Service } from '~wildo-backend-lib/base-classes/services/batches/batches-cronjobs-custom-execution.service';
+import { ExecutionContextCreatorBackendService } from '~wildo-backend-lib/runtime/services/execution-context-creator.backend.service';
+import { ResourceOperationCustomImplementationRegistryBackendService } from '~wildo-backend-lib/base-classes/services/services/resource-operation-custom-implementation-registry.backend.service';
+import { CoreBackend_ServiceImplementationsFactories } from '~wildo-backend-lib/resources/models/custom-service-implementations.backend.definition';
+import { createFilesCleanupBatch, FILES_CLEANUP_BATCH_REF } from '~wildo-backend-lib/files/batches/files-cleanup.batch.backend.service';
+import { createConsumableTokensCleanupBatch, CONSUMABLE_TOKENS_CLEANUP_BATCH_REF } from '~wildo-backend-lib/security/consumable-tokens/batches/consumable-tokens-cleanup.batch.backend.service';
+import { createAnonymousSessionCleanupBatch, ANONYMOUS_SESSION_CLEANUP_BATCH_REF } from '~wildo-backend-lib/security/authentications/batches/anonymous-session-cleanup.batch.backend.service';
+import { SAAS_SERVICE_TYPES as TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { ResourceCustomServiceImplementationFactory } from '~wildo-backend-lib/base-classes/services/services/resource-operation-custom-implementation.factory.backend';
+import { MongoDBService } from '~wildo-backend-lib/databases/services/mongodb.service';
+import { RedisService } from '~wildo-backend-lib/databases/services/redis.service';
+import { I18nBackendService, CustomLabelsMap } from '~wildo-backend-lib/i18n/services/i18n.backend.service';
+import { FileStorageRouterBackendService } from '~wildo-backend-lib/files/storage/file-storage-router.backend.service';
+import { QueueWorkerInitializerBackendService } from '~wildo-backend-lib/queue/queue-worker-initializer.backend.service';
+import { CronJobSyncBackendService } from '~wildo-backend-lib/queue/cron-job-sync.backend.service';
+import type { ProductCatalogSyncBackendService } from '~wildo-backend-lib/billing/services/back-office/product-catalog-sync.backend.service';
+import type { UsageMeteringBackendService } from '~wildo-backend-lib/billing/services/back-office/usage-metering.backend.service';
+import type { BillingFeatureSyncBackendService } from '~wildo-backend-lib/billing/services/back-office/billing-feature-sync.backend.service';
+import { initializeBillingCustomImplementations, registerBillingPostOperationHooks, setBillingWebSocketService } from '~wildo-backend-lib/billing/services/custom-impl/billing-custom-implementations.backend';
+import type { StandardBilling_Interface } from '@wildo-ai/external-connectors-models';
+import type { WebhookHandlerBackendService } from '~wildo-backend-lib/notifications/webhooks/services/webhook-handler.backend.service';
+import type { WebhookAutoControllerBackendService } from '~wildo-backend-lib/notifications/webhooks/controllers/webhook-auto-controller.backend.service';
+import { BillingWebhookAdapter } from '~wildo-backend-lib/billing/services/webhooks/billing-webhook-adapter.backend.service';
+import { BillingWebhookCapabilityHandler } from '~wildo-backend-lib/billing/services/webhooks/billing-webhook-capability-handler.backend.service';
+import { BillingWebhookEventRouterBackendService } from '~wildo-backend-lib/billing/services/webhooks/billing-webhook-event-router.backend.service';
+import type { WebSocketService } from '~wildo-backend-lib/requests/service/websocket.service';
+import type { BillingConfiguration, ProductDefinition, ChartDefinition, GuidanceFlowDefinition } from '@wildo-ai/saas-models';
+import { ChartRegistryBackendService } from '~wildo-backend-lib/charts/services/chart-registry.backend.service';
+import { GuidanceTriggerEvaluatorBackendService } from '~wildo-backend-lib/guidance/services/guidance-trigger-evaluator.backend.service';
+import { EmailTemplateRegistryBackendService } from '~wildo-backend-lib/notifications/email/services/email-template-registry.backend.service';
+import type { EmailTemplateDefinitionsMap } from '~wildo-backend-lib/notifications/email/models/email-template-definition';
+import { BillingStateBackendService } from '~wildo-backend-lib/billing/services/back-office/billing-state.backend.service';
+
+/**
+ * Configuration object for {@link StartApplicationBackendService.initialize}.
+ *
+ * Groups the 25+ positional parameters into a single typed config,
+ * preventing silent mis-ordering bugs (e.g. `customLabels` passed as `undefined`
+ * at the wrong positional slot).
+ */
+export interface ApplicationInitializationConfig {
+    sharedResourceConfigurations: ResourceConfiguration_InitializationFactoryMap;
+    sharedResourceFieldIdentifiers?: Record<string, string>;
+    sharedResourceRelationships: ResourceRelationship[];
+
+    backendResourceConfigurations?: ResourceConfiguration_InitializationFactoryMap;
+    backendResourceFieldIdentifiers?: Record<string, string>;
+    backendResourceRelationships?: ResourceRelationship[];
+
+    customServiceImplementations: ResourceCustomServiceImplementationFactory[];
+
+    customRoles?: RolesConfiguration;
+    customControllers?: AbstractControllerBackendService[];
+    container?: any;
+    controllerWhiteList?: string[];
+    isPlatformApplication?: boolean;
+
+    customBatchesFactory?: (deps: {
+        logger: LoggerService;
+        errorBuilder: ErrorBuilderBackendService;
+        errorHandler: ErrorHandlerService;
+        executionContextCreatorService: ExecutionContextCreatorBackendService;
+        resourcesRegistryService: ResourcesRegistryBackendService;
+        repositoriesRegistryService: RepositoriesRegistryHandlerBackendService;
+        servicesRegistryService: ServicesRegistryHandlerBackendService;
+    }) => Map<string, BatchesCronjobsCustomExecution_Service<any, any>>;
+
+    flowsActorsRegistry?: {
+        flowActorSystemsFactoryMap?: FlowActorSystem_InitializationFactoryMap;
+        agents?: FlowsActors_Agent[];
+    };
+
+    customLabels?: CustomLabelsMap;
+    providerCatalog?: ProviderCatalog;
+
+    customFeatureDefinitions?: FeatureDefinitionWithAutoRegister[];
+    customFeatureConfiguration?: {
+        profiles?: Record<string, ScopeFeatures>;
+        defaultProfile?: string;
+        unavailabilityPolicy?: Partial<FeatureConfiguration['unavailabilityPolicy']>;
+    };
+
+    chartDefinitions?: ChartDefinition[];
+    customMilestoneDefinitions?: MilestoneDefinition[];
+    customMilestoneConditions?: Array<{ ref: string; fn: MilestoneConditionFn }>;
+    productDefinitions?: ProductDefinition[];
+    emailTemplateDefinitions?: EmailTemplateDefinitionsMap;
+    backendConfig?: AppConfiguration_BackendAuthored;
+    guidanceFlowDefinitions?: GuidanceFlowDefinition[];
+
+    /** Skip HTTP server initialization (used by apps-manager for E2E testing) */
+    headlessMode?: boolean;
+}
+
+/**
+ * Start Application Backend Service
+ *
+ * Orchestrates the initialization of the backend application by:
+ * 1. Initializing application configuration
+ * 1.5. Initializing roles configuration (defaults + custom roles)
+ * 2. Initializing resources registry with all 4 sources
+ * 3. Initializing repositories registry with mongoose models
+ * 4. Initializing services registry with business logic layer
+ * 5. Initializing controllers registry with HTTP endpoints layer
+ * 6. Initializing HTTP server with Express.js and middleware
+ * 7. Validating all components are properly initialized
+ *
+ * This service ensures proper startup sequence and dependency management.
+ */
+@injectable()
+export class StartApplicationBackendService {
+    protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+    protected isInitialized = false;
+    private isPlatformMode = false;
+
+    constructor(
+        @inject(SAAS_SERVICE_TYPES.Logger) protected readonly logger: LoggerService,
+        @inject(SAAS_SERVICE_TYPES.AppConfigService) protected readonly appConfigService: AppConfigurationService,
+        @inject(SAAS_SERVICE_TYPES.ApplicationStartupConfigValidatorService) protected readonly applicationStartupConfigValidator: ApplicationStartupConfigValidatorService,
+        @inject(SAAS_SERVICE_TYPES.ResourceRegistryService) protected readonly resourcesRegistryService: ResourcesRegistryBackendService,
+        @inject(SAAS_SERVICE_TYPES.RepositoriesRegistryHandlerService) protected readonly repositoriesRegistryService: RepositoriesRegistryHandlerBackendService,
+        @inject(SAAS_SERVICE_TYPES.ServicesRegistryHandlerService) protected readonly servicesRegistryService: ServicesRegistryHandlerBackendService,
+        @inject(SAAS_SERVICE_TYPES.ControllersRegistryHandlerService) protected readonly controllersRegistryService: ControllersRegistryHandlerBackendService,
+        @inject(SAAS_SERVICE_TYPES.HttpServerService) protected readonly httpServerService: HttpServerBackendService,
+        @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) protected readonly errorBuilder: ErrorBuilderBackendService,
+        @inject(SAAS_SERVICE_TYPES.ErrorHandlerService) protected readonly errorHandler: ErrorHandlerService,
+        @inject(SAAS_SERVICE_TYPES.AuthorizationsService) protected readonly authorizationsService: AuthorizationsBackendService,
+        @inject(SAAS_SERVICE_TYPES.BatchesCronjobsExecutorService) protected readonly batchesExecutor: BatchesCronjobsExecutor_BackendService,
+        @inject(SAAS_SERVICE_TYPES.ExecutionContextCreatorBackendService) protected readonly executionContextCreatorBackendService: ExecutionContextCreatorBackendService,
+        @inject(SAAS_SERVICE_TYPES.ResourceOperationCustomImplementationRegistryService) protected readonly customImplRegistry: ResourceOperationCustomImplementationRegistryBackendService,
+        @inject(SAAS_SERVICE_TYPES.MongoDBService) protected readonly mongoDBService: MongoDBService,
+        @inject(SAAS_SERVICE_TYPES.RedisService) protected readonly redisService: RedisService,
+        @inject(SAAS_SERVICE_TYPES.I18nService) protected readonly i18nService: I18nBackendService,
+        @inject(SAAS_SERVICE_TYPES.ExternalProvidersRegistryService) protected readonly externalProvidersRegistryService: ExternalProvidersRegistryBackendService,
+        @inject(SAAS_SERVICE_TYPES.LazyProviderRegistryService) protected readonly lazyProviderRegistryService: LazyProviderRegistryBackendService,
+        @inject(SAAS_SERVICE_TYPES.CapabilityBindingsService) protected readonly capabilityBindingsService: CapabilityBindingsBackendService,
+        @inject(SAAS_SERVICE_TYPES.FeatureDefinitionRegistryService) protected readonly featureDefinitionRegistryService: FeatureDefinitionRegistryBackendService,
+        @inject(SAAS_SERVICE_TYPES.MilestoneDefinitionRegistry) protected readonly milestoneDefinitionRegistry: MilestoneDefinitionRegistryBackendService,
+        @inject(SAAS_SERVICE_TYPES.MilestoneConditionRegistry) protected readonly milestoneConditionRegistry: MilestoneConditionRegistryBackendService,
+        @inject(SAAS_SERVICE_TYPES.LifecycleEvaluator) protected readonly lifecycleEvaluator: LifecycleEvaluatorBackendService,
+        @inject(SAAS_SERVICE_TYPES.FlowsActorsRegistryService) protected readonly flowsActorsRegistryService: FlowsActorsRegistryService,
+        @inject(SAAS_SERVICE_TYPES.QueueWorkerInitializerService) protected readonly queueWorkerInitializer: QueueWorkerInitializerBackendService,
+        @inject(SAAS_SERVICE_TYPES.CronJobSyncService) protected readonly cronJobSyncService: CronJobSyncBackendService,
+        @inject(SAAS_SERVICE_TYPES.ChartRegistryService) protected readonly chartRegistryService: ChartRegistryBackendService,
+        @inject(SAAS_SERVICE_TYPES.GuidanceTriggerEvaluator) protected readonly guidanceTriggerEvaluator: GuidanceTriggerEvaluatorBackendService,
+        @inject(SAAS_SERVICE_TYPES.EmailTemplateRegistry) protected readonly emailTemplateRegistryService: EmailTemplateRegistryBackendService,
+        @inject(SAAS_SERVICE_TYPES.FileStorageRouter) protected readonly fileStorageRouter: FileStorageRouterBackendService,
+    ) {
+        this.logger = logger;
+        this.appConfigService = appConfigService;
+        this.resourcesRegistryService = resourcesRegistryService;
+        this.repositoriesRegistryService = repositoriesRegistryService;
+        this.servicesRegistryService = servicesRegistryService;
+        this.controllersRegistryService = controllersRegistryService;
+        this.httpServerService = httpServerService;
+        this.authorizationsService = authorizationsService;
+
+        this.logDebug = this.logger.debugByType('StartApplicationBackendService');
+        this.logger.setDebugTypeLogging('StartApplicationBackendService', false);
+
+        this.logDebug('Start application service created');
+    }
+
+    /**
+     * Initialize the backend application with a structured configuration object.
+     */
+    public async initialize(config: ApplicationInitializationConfig): Promise<void> {
+
+        if (this.isInitialized) {
+            this.logDebug('Application already initialized, skipping');
+            return;
+        }
+
+        const {
+            sharedResourceConfigurations,
+            sharedResourceFieldIdentifiers,
+            sharedResourceRelationships,
+            backendResourceConfigurations,
+            backendResourceFieldIdentifiers,
+            backendResourceRelationships = [],
+            customServiceImplementations,
+            customRoles,
+            customControllers,
+            container,
+            controllerWhiteList,
+            isPlatformApplication = false,
+            customBatchesFactory,
+            flowsActorsRegistry,
+            customLabels,
+            providerCatalog,
+            customFeatureDefinitions,
+            customFeatureConfiguration,
+            chartDefinitions,
+            customMilestoneDefinitions,
+            customMilestoneConditions,
+            productDefinitions,
+            emailTemplateDefinitions,
+            backendConfig,
+            guidanceFlowDefinitions,
+        } = config;
+
+        try {
+            this.logDebug('🚀 Starting backend application initialization...');
+            // Step 1: Initialize application configuration
+            this.logDebug('📋 Initializing application configuration...');
+
+            // Persist platform mode for validation differences
+            this.isPlatformMode = !!isPlatformApplication;
+
+            if(!isPlatformApplication) {
+                await this.appConfigService.initialize();
+                this.appConfigService.applyBackendConfig(backendConfig ?? {});
+                if (backendConfig) {
+                    this.logger.info('Backend config applied', {
+                        sections: Object.keys(backendConfig),
+                    });
+                }
+                this.appConfigService.assertNoPreOverridePlaceholders();
+                this.logDebug('✅ Application configuration initialized successfully');
+                // Establish default MongoDB connection using loaded app secrets
+                try {
+                    await this.mongoDBService.connect();
+                    this.logDebug('✅ MongoDB default connection established');
+                } catch (e) {
+                    this.logger.error('❌ MongoDB default connection failed', e as any);
+                    throw e;
+                }
+                // Establish Redis connection for caching, sessions, and WebSocket sync
+                // Redis is optional - graceful fallback to in-memory if unavailable
+                try {
+                    await this.redisService.connect();
+                    this.logDebug('✅ Redis connection established');
+                } catch (e) {
+                    this.logger.warn('⚠️ Redis connection failed, using in-memory fallbacks', { error: e instanceof Error ? e.message : String(e) });
+                }
+
+                // Initialize file storage (MinIO/S3) — optional, skipped when not configured
+                if (this.fileStorageRouter.isConfigured()) {
+                    try {
+                        await this.fileStorageRouter.initialize();
+                        this.logDebug('✅ File storage initialized');
+                    } catch (e) {
+                        this.logger.warn('⚠️ File storage initialization failed, file operations will fail at runtime', { error: e instanceof Error ? e.message : String(e) });
+                    }
+                } else {
+                    this.logDebug('📦 File storage not configured, skipping initialization');
+                }
+            }
+
+            if (!isPlatformApplication) {
+                this.applicationStartupConfigValidator.validate(this.appConfigService.config);
+            }
+
+            // Step 1.5: Initialize roles configuration
+            this.logDebug('🔐 Initializing roles configuration...');
+            if (customRoles) {
+                this.authorizationsService.initializeRolesWithCustom(customRoles);
+                this.logDebug('✅ Roles configuration initialized with custom roles');
+            } else {
+                // Roles are already initialized with defaults in the constructor
+                this.logDebug('✅ Roles configuration using default roles only');
+            }
+
+            // Step 2: Initialize resources registry with all 4 sources
+            this.logDebug('🔧 Initializing resources registry...');
+
+            // Read lifecycle config early — needed for both resource exclusion and evaluator init
+            // Platform apps don't use lifecycle, billing, or feature gating
+            const lifecycleConfig: LifecycleConfig | undefined = isPlatformApplication ? undefined : this.appConfigService.config?.lifecycle;
+
+            // Compute excluded resource types based on app configuration.
+            // When billing/lifecycle is disabled, their resource types are excluded
+            // from the registry (no routes, no repositories, no frontend resources).
+            // When billing IS enabled, scope variants for scopes not in enabledScopes
+            // are also excluded (e.g., USER variants when only ORG billing is enabled).
+            const excludedResourceTypes: ReadonlySet<string> | undefined = (() => {
+                if (isPlatformApplication) return undefined;
+                const excluded = new Set<string>();
+                const billingConfig = this.appConfigService.config?.billing;
+                if (!billingConfig?.enabled) {
+                    BILLING_RESOURCE_TYPES.forEach(t => excluded.add(t));
+                } else {
+                    // Billing is enabled — exclude variants for scopes NOT in enabledScopes.
+                    // Non-polymorphic resources (Products, Prices, etc.) are always kept.
+                    const enabledScopesSet = new Set<string>(billingConfig.enabledScopes ?? []);
+                    for (const scope of BILLING_SCOPES) {
+                        if (!enabledScopesSet.has(scope)) {
+                            const scopeTypes = BILLING_SCOPE_RESOURCE_TYPES[scope];
+                            if (scopeTypes) {
+                                scopeTypes.forEach(t => excluded.add(t));
+                            }
+                        }
+                    }
+                }
+                if (!lifecycleConfig?.enabled) {
+                    LIFECYCLE_RESOURCE_TYPES.forEach(t => excluded.add(t));
+                }
+                return excluded.size > 0 ? excluded : undefined;
+            })();
+
+            if (excludedResourceTypes) {
+                this.logDebug(`Feature-gated resources excluded: ${excludedResourceTypes.size} types`, {
+                    billingDisabled: !this.appConfigService.config?.billing?.enabled,
+                    billingDisabledScopes: (() => {
+                        const billingConfig = this.appConfigService.config?.billing;
+                        if (!billingConfig?.enabled) return 'all';
+                        const enabledSet = new Set<string>(billingConfig.enabledScopes ?? []);
+                        return BILLING_SCOPES.filter(s => !enabledSet.has(s));
+                    })(),
+                    lifecycleDisabled: !lifecycleConfig?.enabled,
+                });
+            }
+
+            await this.resourcesRegistryService.initialize(
+                    sharedResourceConfigurations,
+                    sharedResourceFieldIdentifiers,
+                    sharedResourceRelationships,
+                    (backendResourceConfigurations ?? {}) as ResourceConfiguration_InitializationFactoryMap,
+                    backendResourceFieldIdentifiers,
+                    backendResourceRelationships,
+                    undefined, // customNotificationBadgeDefinitions
+                    undefined, // customAdditionalUserNotificationDefinitions
+                    excludedResourceTypes,
+            );
+            this.logDebug('✅ Resources registry initialized successfully');
+
+            // Step 2.0.1: Initialize feature definition registry
+            this.logDebug('🏷️ Initializing feature definition registry...');
+            this.featureDefinitionRegistryService.registerCoreFeatures();
+            if (customFeatureDefinitions && customFeatureDefinitions.length > 0) {
+                this.featureDefinitionRegistryService.registerCustomFeatures(customFeatureDefinitions);
+            }
+            this.featureDefinitionRegistryService.validateDefinitions();
+            this.featureDefinitionRegistryService.logStartupSummary();
+
+            // Build and set the merged FeatureConfiguration (profiles + policy)
+            if (customFeatureConfiguration) {
+                const allDefinitions = this.featureDefinitionRegistryService.getAllDefinitions();
+                this.featureDefinitionRegistryService.setConfiguration({
+                    definitions: allDefinitions,
+                    profiles: customFeatureConfiguration.profiles ?? {},
+                    defaultProfile: customFeatureConfiguration.defaultProfile,
+                    unavailabilityPolicy: {
+                        defaultBehavior: customFeatureConfiguration.unavailabilityPolicy?.defaultBehavior ?? FeatureUnavailabilityBehavior.UPGRADE_PROMPT,
+                        whenBillingDisabled: customFeatureConfiguration.unavailabilityPolicy?.whenBillingDisabled ?? FeatureUnavailabilityBehavior.HIDE,
+                        roleDefaults: customFeatureConfiguration.unavailabilityPolicy?.roleDefaults ?? {},
+                        reasonDefaults: customFeatureConfiguration.unavailabilityPolicy?.reasonDefaults ?? {
+                            [FeatureUnavailabilityReason.FEATURE_NOT_ENABLED]: FeatureUnavailabilityBehavior.UPGRADE_PROMPT,
+                            [FeatureUnavailabilityReason.LIMIT_EXCEEDED]: FeatureUnavailabilityBehavior.LIMIT_UPGRADE_PROMPT,
+                            [FeatureUnavailabilityReason.NOT_CONFIGURED]: FeatureUnavailabilityBehavior.HIDE,
+                        },
+                    },
+                });
+                this.logDebug('✅ Feature configuration set (profiles + unavailability policy)');
+            }
+            const analyticsValueMoments = this.appConfigService.isInitialized()
+                ? this.appConfigService.config.analytics?.valueMoments
+                : undefined;
+
+            this.featureDefinitionRegistryService.warnMisplacedLimitFeatures();
+            this.featureDefinitionRegistryService.warnInvalidFeatureReferences({
+                featureProfiles: customFeatureConfiguration?.profiles,
+                chartDefinitions,
+                guidanceFlowDefinitions,
+                productDefinitions,
+                analyticsValueMoments,
+            });
+            this.logDebug('✅ Feature definition registry initialized successfully');
+
+            // Step 2.0.2: Initialize milestone definition registry
+            this.logDebug('🏅 Initializing milestone definition registry...');
+            if (customMilestoneConditions && customMilestoneConditions.length > 0) {
+                for (const { ref, fn } of customMilestoneConditions) {
+                    this.milestoneConditionRegistry.registerCondition(ref, fn);
+                }
+                this.logDebug(`Registered ${customMilestoneConditions.length} custom milestone condition(s)`);
+            }
+            if (customMilestoneDefinitions && customMilestoneDefinitions.length > 0) {
+                this.milestoneDefinitionRegistry.registerCustomMilestones(customMilestoneDefinitions);
+                this.milestoneDefinitionRegistry.validateDefinitions();
+                this.milestoneDefinitionRegistry.logStartupSummary();
+            }
+            this.logDebug('✅ Milestone definition registry initialized successfully');
+
+            // Step 2.0.3: Initialize lifecycle evaluator configuration
+            if (!isPlatformApplication && lifecycleConfig?.enabled) {
+                this.logDebug('🔄 Initializing lifecycle evaluator...');
+                this.lifecycleEvaluator.setLifecycleConfig(lifecycleConfig);
+
+                // Late-binding initialization for lifecycle custom implementations
+                initializeLifecycleCustomImplementations(this.lifecycleEvaluator, lifecycleConfig, this.errorBuilder);
+
+                // Validate activation criteria refs against registries
+                if (lifecycleConfig.activationCriteria?.criteria) {
+                    for (const criterion of lifecycleConfig.activationCriteria.criteria) {
+                        if (criterion.criterionType === ActivationCriterionType.MILESTONE) {
+                            const exists = !!this.milestoneDefinitionRegistry.getDefinition(criterion.milestoneRef);
+                            if (!exists) {
+                                this.logger.warn(`Lifecycle activation criterion references unknown milestone: '${criterion.milestoneRef}'`);
+                            }
+                        } else if (criterion.criterionType === ActivationCriterionType.GUIDANCE_COMPLETED) {
+                            this.logDebug(`Lifecycle activation criterion references guidance flow: '${criterion.guidanceFlowRef}' (validated at runtime)`);
+                        }
+                    }
+                }
+
+                this.logDebug('✅ Lifecycle evaluator configured', {
+                    dormancyThresholdDays: lifecycleConfig.dormancyThresholdDays,
+                    activityDebounceMinutes: lifecycleConfig.activityDebounceMinutes,
+                    dormancyCronSchedule: lifecycleConfig.dormancyCronSchedule,
+                    activationCriteriaCount: lifecycleConfig.activationCriteria?.criteria?.length ?? 0,
+                });
+            } else if (!isPlatformApplication) {
+                this.logDebug('🔄 Lifecycle system disabled (lifecycle.enabled = false or not configured)');
+            }
+
+            // Step 2.1: Initialize lazy provider registry (on-demand provider definitions)
+            if (providerCatalog) {
+                this.logDebug('📦 Initializing lazy provider registry with catalog...');
+                await this.lazyProviderRegistryService.initialize(providerCatalog);
+                this.logDebug('✅ Lazy provider registry initialized successfully');
+            } else {
+                this.logDebug('📦 Skipping lazy provider registry (no catalog provided)');
+            }
+
+            // Step 2.2: Initialize capability bindings + external providers registry
+            // Order matters: bindings compute the registry from policy, then registry consumes it.
+            // Skip for platform applications - they initialize config later and will refresh the registry
+            if (!isPlatformApplication) {
+                this.logDebug('🎯 Initializing feature bindings service...');
+                await this.capabilityBindingsService.initialize();
+                this.logDebug('✅ Feature bindings service initialized successfully');
+
+                this.logDebug('🔌 Initializing external providers registry...');
+                await this.externalProvidersRegistryService.initialize();
+                this.logDebug('✅ External providers registry initialized successfully');
+            } else {
+                this.logDebug('🔌 Skipping external providers registry initialization (platform app - will initialize after config is ready)');
+            }
+
+            // Step 2.3: Initialize flows-actors registry
+            this.logDebug('🎭 Initializing flows-actors registry...');
+            const mergedFlowActorSystemsFactoryMap = {
+                ...(flowsActorsRegistry?.flowActorSystemsFactoryMap || {}),
+            };
+            const mergedAgents = [
+                ...(flowsActorsRegistry?.agents || []),
+            ];
+            await this.flowsActorsRegistryService.initialize(
+                mergedFlowActorSystemsFactoryMap,
+                mergedAgents
+            );
+            this.logDebug('✅ Flows-actors registry initialized successfully');
+
+            if (!isPlatformApplication) {
+                this.logDebug('🧭 Validating initialized runtime contracts...');
+                this.applicationStartupConfigValidator.validateInitializedRuntimeContracts();
+                this.logDebug('✅ Initialized runtime contracts validated successfully');
+            }
+
+            // Step 2.4: Initialize I18n service with custom labels
+            this.logDebug('🌐 Initializing I18n service...');
+            this.i18nService.initialize(customLabels || {}, {
+                suppressEmptyWarning: isPlatformApplication,
+            });
+            this.logDebug('✅ I18n service initialized successfully');
+
+            // Step 2.4b: Initialize email template registry
+            if (emailTemplateDefinitions && Object.keys(emailTemplateDefinitions).length > 0) {
+                this.emailTemplateRegistryService.initialize(emailTemplateDefinitions);
+            }
+
+            // Step 2.5: Register chart definitions
+            if (chartDefinitions && chartDefinitions.length > 0) {
+                this.logDebug('📊 Registering chart definitions...', { count: chartDefinitions.length });
+                for (const chartDef of chartDefinitions) {
+                    this.chartRegistryService.registerChart(chartDef);
+                }
+                this.logDebug('✅ Chart definitions registered successfully', { count: chartDefinitions.length });
+            } else {
+                this.logDebug('📊 No chart definitions provided, skipping chart registration');
+            }
+
+            // Step 2.5b: Register guidance flow definitions
+            if (guidanceFlowDefinitions && guidanceFlowDefinitions.length > 0) {
+                this.logDebug('🧭 Registering guidance flow definitions...', { count: guidanceFlowDefinitions.length });
+                this.guidanceTriggerEvaluator.initializeFlows(guidanceFlowDefinitions);
+                this.logDebug('✅ Guidance flow definitions registered successfully', { count: guidanceFlowDefinitions.length });
+            } else {
+                this.logDebug('🧭 No guidance flow definitions provided, skipping guidance registration');
+            }
+
+            // Step 2.6: Debug URL generation
+            this.logDebug('🌐 Displaying generated URLs for debugging...');
+            this.resourcesRegistryService.debugDisplayGeneratedUrls();
+
+            // Step 3: Initialize repositories registry
+            this.logDebug('🗄️ Initializing repositories registry...');
+            const resourcesRegistry = this.resourcesRegistryService.getResourcesRegistry();
+            const resourceConfigurations = new Map(
+                Object.entries(resourcesRegistry.resourceConfigurations) as [ResourceType, ResourceConfiguration<any, any, any>][]
+            );
+
+            // Initialize repositories registry on the active default connection
+            const activeConnection = this.mongoDBService.getConnection();
+            await this.repositoriesRegistryService.initializeRepositories(resourceConfigurations, activeConnection || undefined);
+            this.logDebug('✅ Repositories registry initialized successfully');
+
+            // Step 2.1: Initialize custom service implementations registry (backend defaults)
+            this.customImplRegistry.initialize([...CoreBackend_ServiceImplementationsFactories, ...customServiceImplementations]);
+
+            // Step 4: Initialize services registry (business logic layer)
+            this.logDebug('🏢 Initializing services registry...');
+            await this.servicesRegistryService.initializeServices();
+            this.logDebug('✅ Services registry initialized successfully');
+
+            // Step 4.5: Initialize billing services (if enabled)
+            if (!isPlatformApplication && this.appConfigService.config?.billing?.enabled && container) {
+                await this.initializeBillingServices(container, this.appConfigService.config.billing, productDefinitions);
+            }
+
+            // Step 4.6: Initialize webhook auto-controller (must happen before controllers registry)
+            if (!isPlatformApplication && container) {
+                await this.initializeWebhookAutoController(container);
+            }
+
+            // Step 5: Initialize controllers registry (HTTP endpoints layer)
+            this.logDebug('🌐 Initializing controllers registry...');
+
+
+            // Get manual controllers from provided container
+            let allCustomControllers: AbstractControllerBackendService[] = [];
+
+            if (container) {
+                // G-4: directoryProvisioningEnabled moved to organizationTypes[t].scimProvisioning — hardcode false until migration
+                const directoryProvisioningEnabled = false;
+                const analyticsEnabled = isPlatformApplication ? false : !!this.appConfigService.config?.analytics?.enabled;
+                const manualControllers = isPlatformApplication ? [] : getManualControllersBackend(container, { directoryProvisioningEnabled, analyticsEnabled });
+                allCustomControllers = [
+                    ...manualControllers,
+                    ...(customControllers || [])
+                ];
+
+
+
+                this.logDebug('📋 Controllers to register', {
+                    manualControllers: manualControllers.length,
+                    runtimeCustomControllers: customControllers?.length || 0,
+                    totalCustomControllers: allCustomControllers.length
+                });
+            } else {
+                allCustomControllers = customControllers || [];
+
+                this.logDebug('📋 Controllers to register', {
+                    manualControllers: 0,
+                    runtimeCustomControllers: customControllers?.length || 0,
+                    totalCustomControllers: allCustomControllers.length
+                });
+            }
+            if(!isPlatformApplication) {
+                await this.controllersRegistryService.initialize(
+                    allCustomControllers.length > 0 ? allCustomControllers : undefined,
+                    controllerWhiteList
+                );
+                this.logDebug('✅ Controllers registry initialized successfully');
+            } else {
+                this.logDebug('Skipping controllers registry initialization in platform mode (will be started by apps-manager)');
+            }
+
+            // Step 5.5: Initialize batches/cronjobs (core engine + custom + resource-based)
+            this.logDebug('🧵 Initializing batches & cronjobs...');
+            const customBatches = customBatchesFactory
+                ? customBatchesFactory({
+                    logger: this.logger,
+                    errorBuilder: this.errorBuilder,
+                    errorHandler: this.errorHandler,
+                    executionContextCreatorService: this.executionContextCreatorBackendService,
+                    resourcesRegistryService: this.resourcesRegistryService,
+                    repositoriesRegistryService: this.repositoriesRegistryService,
+                    servicesRegistryService: this.servicesRegistryService,
+                  })
+                : new Map<string, BatchesCronjobsCustomExecution_Service<any, any>>();
+
+            // Register core engine batches (always present, independent of custom app)
+            customBatches.set(FILES_CLEANUP_BATCH_REF, createFilesCleanupBatch());
+            customBatches.set(CONSUMABLE_TOKENS_CLEANUP_BATCH_REF, createConsumableTokensCleanupBatch());
+
+            if (this.appConfigService.anonymousSessionsEnabled) {
+                customBatches.set(ANONYMOUS_SESSION_CLEANUP_BATCH_REF, createAnonymousSessionCleanupBatch());
+                this.logDebug('✅ Anonymous session cleanup batch registered');
+            }
+
+            // Register lifecycle dormancy detection batch (only when lifecycle is enabled)
+            if (lifecycleConfig?.enabled) {
+                customBatches.set(DORMANCY_DETECTION_BATCH_REF, createDormancyDetectionBatch(lifecycleConfig.dormancyCronSchedule));
+                this.logDebug('✅ Dormancy detection batch registered', { cronSchedule: lifecycleConfig.dormancyCronSchedule });
+            }
+
+            await this.batchesExecutor.initialize(customBatches);
+            this.logDebug('✅ Batches & cronjobs initialized');
+
+            // Step 6: Initialize HTTP server (skip here in platform mode; apps-manager will start it later)
+            if (!this.isPlatformMode) {
+                this.logger.info('🌍 Initializing HTTP server...');
+                try {
+                    await this.httpServerService.initialize();
+                    this.logger.info('✅ HTTP server initialized successfully');
+                } catch (error) {
+                    this.logger.error('❌ HTTP server initialization failed:', error);
+                    throw error;
+                }
+            } else {
+                this.logDebug('Skipping HTTP server initialization in platform mode (will be started by apps-manager)');
+            }
+
+            // Step 7: Initialize queue workers (for background job processing)
+            if (!this.isPlatformMode) {
+                this.logger.info('🐰 Initializing queue workers...');
+                try {
+                    await this.queueWorkerInitializer.initialize();
+                    this.logger.info('✅ Queue workers initialized (if RabbitMQ configured)');
+                } catch (error) {
+                    // Queue workers failing shouldn't prevent app from starting
+                    this.logger.warn('⚠️ Queue worker initialization skipped or failed:', error);
+                }
+
+                // Step 7.5: Sync cron jobs to crontabs-batches-manager
+                this.logger.info('🕐 Syncing cron jobs to crontabs-manager...');
+                try {
+                    // Initialize the sync service
+                    this.cronJobSyncService.initialize();
+
+                    // Sync cron jobs (non-blocking - errors are logged but don't fail startup)
+                    await this.cronJobSyncService.syncCronJobsToManager();
+                    this.logger.info('✅ Cron job sync completed (if crontabs-manager configured)');
+                } catch (error) {
+                    // Cron sync failing shouldn't prevent app from starting
+                    this.logger.warn('⚠️ Cron job sync skipped or failed:', error);
+                }
+            } else {
+                this.logDebug('Skipping queue worker initialization in platform mode');
+            }
+
+            // Step 7.6: Run one-time SIEM DLQ migration (non-blocking)
+            try {
+                const siemService = container.get(SAAS_SERVICE_TYPES.SIEMWebhookDeliveryService) as { migrateRedisDLQToMongoDB(): Promise<void> } | undefined;
+                if (siemService?.migrateRedisDLQToMongoDB) {
+                    await siemService.migrateRedisDLQToMongoDB();
+                }
+            } catch (error) {
+                this.logger.warn('⚠️ SIEM DLQ migration skipped or failed:', error);
+            }
+
+            // Step 8: Validate initialization
+            await this.validateInitialization();
+
+            this.isInitialized = true;
+
+            // Step 8: Display debug information (after initialization is complete)
+            this.logDebug('📋 Displaying implemented Mongoose schemas...');
+            this.debugDisplayMongooseSchemas({
+                showSchemaStructure: true,
+                showIndexes: true,
+                maxFieldDepth: 2,
+            });
+
+            this.logDebug('🌐 Displaying registered routes...');
+            this.debugDisplayRegisteredRoutes();
+
+            this.logDebug('🎉 Backend application initialization completed successfully');
+
+        } catch (error) {
+            this.logger.error('❌ Backend application initialization failed:', error);
+            throw error;
+        }
+    }
+
+    /**
+     * Initialize the webhook auto-controller with its dependencies.
+     * Must be called before controllers registry so that setupRoutes() can discover providers.
+     * Async because it pre-loads protocols from the lazy registry (ProtocolCatalogEntry only has loaders).
+     */
+    private async initializeWebhookAutoController(container: any): Promise<void> {
+        try {
+            const webhookHandler = container.get(SAAS_SERVICE_TYPES.WebhookHandlerService) as WebhookHandlerBackendService;
+            const providerRegistry = container.get(SAAS_SERVICE_TYPES.LazyProviderRegistryService) as LazyProviderRegistryBackendService;
+            const webhookAutoController = container.get(SAAS_SERVICE_TYPES.WebhookAutoController) as WebhookAutoControllerBackendService;
+
+            await webhookAutoController.initialize(webhookHandler, providerRegistry);
+            this.logDebug('🔗 Webhook auto-controller initialized');
+        } catch (error) {
+            // Non-fatal — if no webhook providers are registered, this is expected
+            this.logger.warn('Webhook auto-controller initialization skipped', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+
+    /**
+     * Initialize billing services when billing is enabled.
+     *
+     * Resolves the billing provider from the external connectors system
+     * and initializes all billing services (product catalog sync,
+     * usage metering, promotions, custom implementations) and wires up webhooks.
+     */
+    private async initializeBillingServices(
+        container: any,
+        billingConfig: BillingConfiguration,
+        appProductDefinitions?: ProductDefinition[],
+    ): Promise<void> {
+        this.logDebug('💳 Initializing billing services...');
+
+        try {
+            // 1. Resolve the billing provider via external connectors
+            const billingProvider = await this.resolveBillingProvider(billingConfig);
+            if (!billingProvider) {
+                this.logger.warn('⚠️ Billing is enabled but no provider could be resolved — billing services will NOT be initialized');
+                return;
+            }
+
+            // 2. Get billing services from DI container
+            const catalogSync = container.get(SAAS_SERVICE_TYPES.ProductCatalogSyncService) as ProductCatalogSyncBackendService;
+            const usageMetering = container.get(SAAS_SERVICE_TYPES.UsageMeteringService) as UsageMeteringBackendService;
+
+            // 3. Product definitions from the custom app (like customRoles, customFeatureDefinitions)
+            const productDefinitions: ProductDefinition[] = appProductDefinitions ?? [];
+
+            // 4. Initialize services in dependency order
+            await catalogSync.initialize(productDefinitions, billingProvider);
+            await usageMetering.initialize(billingProvider);
+
+            // 4a. Sync product catalog to DB (ensures products/prices exist before billing state endpoint queries them)
+            try {
+                const syncResult = await catalogSync.syncProductCatalog();
+                this.logDebug('📦 Product catalog synced at startup', {
+                    synced: syncResult.synced,
+                    created: syncResult.created,
+                    updated: syncResult.updated,
+                    featuresDirty: syncResult.featuresDirty.length,
+                });
+            } catch (syncError) {
+                this.logger.warn('⚠️ Product catalog startup sync failed (non-fatal)', {
+                    error: syncError instanceof Error ? syncError.message : String(syncError),
+                });
+            }
+
+            // 4b. Initialize billing custom implementations (late-binding for resource-centric operations)
+            const featureSync = container.get(SAAS_SERVICE_TYPES.BillingFeatureSyncService) as BillingFeatureSyncBackendService;
+            const billingStateService = container.get(SAAS_SERVICE_TYPES.BillingStateService) as BillingStateBackendService;
+            initializeBillingCustomImplementations(billingProvider, featureSync, billingStateService, billingConfig, this.errorBuilder);
+
+            // 4c. Register post-operation hooks (feature sync fires automatically after subscription mutations)
+            registerBillingPostOperationHooks(this.servicesRegistryService);
+
+            // 5. Wire up billing webhooks
+            // The WebhookAutoControllerBackendService auto-registers routes from provider definitions,
+            // so we only need to register the adapter (verify+parse) and handler (dispatch).
+            const webhookHandler = container.get(SAAS_SERVICE_TYPES.WebhookHandlerService) as WebhookHandlerBackendService;
+            const webhookAutoController = container.get(SAAS_SERVICE_TYPES.WebhookAutoController) as WebhookAutoControllerBackendService;
+
+            const billingAdapter = new BillingWebhookAdapter(billingProvider, billingConfig.providerRef);
+            webhookHandler.registerAdapter(billingConfig.providerRef, 'billing', billingAdapter);
+
+            const webSocketService = container.get(SAAS_SERVICE_TYPES.WebSocketService) as WebSocketService;
+            setBillingWebSocketService(webSocketService);
+            const webhookEventRouter = new BillingWebhookEventRouterBackendService(this.servicesRegistryService, this.logger, webSocketService);
+            const billingCapabilityHandler = new BillingWebhookCapabilityHandler(webhookEventRouter);
+            webhookAutoController.registerCapabilityHandler(billingCapabilityHandler);
+
+            this.logDebug('✅ Billing services initialized successfully', {
+                providerRef: billingConfig.providerRef,
+                enabledScopes: billingConfig.enabledScopes,
+            });
+        } catch (error) {
+            // Billing initialization failure is non-fatal: the app can still run without billing
+            this.logger.error('❌ Billing services initialization failed (billing will be unavailable)', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+
+    /**
+     * Resolve the StandardBilling_Interface from the external providers system.
+     *
+     * Flow:
+     * 1. Get the billing providerRef from config (e.g., 'stripe')
+     * 2. Use the CapabilityBindingsService to check if billing capability is available
+     * 3. Load the billing protocol/transformer from the lazy provider registry
+     *
+     * Returns null if the provider cannot be resolved (e.g., no provider configured,
+     * connector not installed, credentials missing).
+     */
+    private async resolveBillingProvider(billingConfig: BillingConfiguration): Promise<StandardBilling_Interface | null> {
+        const providerRef = billingConfig.providerRef;
+        if (!providerRef) {
+            this.logDebug('No billing providerRef configured');
+            return null;
+        }
+
+        try {
+            // Check if the provider exists in the lazy registry
+            if (!this.lazyProviderRegistryService.hasProvider(providerRef)) {
+                this.logDebug('Billing provider not found in catalog', { providerRef });
+                return null;
+            }
+
+            // Check if required SDK packages are installed (fail-fast for optional dependencies).
+            // Provider SDK packages (e.g., 'stripe') are optional peer dependencies of
+            // @wildo-ai/external-connectors. The consuming app must add them explicitly.
+            const sdkCheck = this.lazyProviderRegistryService.checkRequiredPackages(providerRef);
+            if (sdkCheck.available === false) {
+                const { missing } = sdkCheck;
+                this.logger.error(
+                    `Billing provider '${providerRef}' requires SDK packages that are not installed: [${missing.join(', ')}]. ` +
+                    `Add them to your app's dependencies: pnpm add ${missing.join(' ')}`,
+                    { providerRef, missingPackages: missing },
+                );
+                return null;
+            }
+
+            // Load the billing protocol from the lazy provider registry.
+            // The billing protocol should implement StandardBilling_Interface.
+            // This is loaded from the provider's registered protocol catalog entry
+            // for the 'REST_API' kind (billing operations are REST-based).
+            const protocol = await this.lazyProviderRegistryService.getProtocol(
+                providerRef,
+                'REST_API' as any, // The protocol kind for billing providers
+            );
+
+            if (!protocol) {
+                this.logDebug('No billing protocol found for provider', { providerRef });
+                return null;
+            }
+
+            // The protocol should expose a billing transformer that implements StandardBilling_Interface.
+            // Cast it — the concrete provider connector (e.g., Stripe) registers this interface
+            // when it registers its protocol in the provider catalog.
+            const billingInterface = (protocol as any).billingInterface as StandardBilling_Interface | undefined;
+            if (billingInterface) {
+                this.logDebug('Billing provider resolved from protocol', { providerRef });
+                return billingInterface;
+            }
+
+            // Fallback: the protocol itself may implement the interface directly
+            if (typeof (protocol as any).createCustomer === 'function') {
+                this.logDebug('Billing provider resolved (protocol implements StandardBilling_Interface)', { providerRef });
+                return protocol as unknown as StandardBilling_Interface;
+            }
+
+            this.logDebug('Billing protocol found but does not implement StandardBilling_Interface', { providerRef });
+            return null;
+        } catch (error) {
+            this.logger.warn('Failed to resolve billing provider', {
+                providerRef,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }
+
+    async shutdown(): Promise<void> {
+        this.logDebug('Starting graceful shutdown');
+
+        // Shutdown queue workers first (wait for in-flight jobs)
+        try {
+            await this.queueWorkerInitializer.shutdown();
+        } catch (error) {
+            this.logger.error('Error during queue worker shutdown', error as any);
+        }
+    }
+    /**
+     * Check if the application is initialized
+     */
+    public isApplicationInitialized(): boolean {
+        return this.isInitialized;
+    }
+
+    /**
+     * Get application configuration
+     */
+    public async getAppConfig(): Promise<AppConfiguration> {
+        this.ensureInitialized();
+        return this.appConfigService.config;
+    }
+
+    /**
+     * Get resources registry
+     */
+    public getResourcesRegistry(): ResourcesRegistry {
+        this.ensureInitialized();
+        return this.resourcesRegistryService.getResourcesRegistry();
+    }
+
+    /**
+     * Get repositories registry handler
+     */
+    public getRepositoriesRegistry(): RepositoriesRegistryHandlerBackendService {
+        this.ensureInitialized();
+        return this.repositoriesRegistryService;
+    }
+
+    /**
+     * Debug function to display all implemented Mongoose schemas
+     * Convenient access to schema debugging from the main application service
+     */
+    public debugDisplayMongooseSchemas(options: {
+        showSchemaStructure?: boolean;
+        showIndexes?: boolean;
+        showVirtuals?: boolean;
+        resourceTypeFilter?: string[];
+        maxFieldDepth?: number;
+    } = {}): void {
+        this.logDebug('\n🚀 === WILDO.AI BACKEND - MONGOOSE SCHEMAS DEBUG ===\n');
+
+        if (!this.isInitialized) {
+            this.logDebug('⚠️  Application not initialized yet. Schemas may not be available.');
+            return;
+        }
+
+        this.repositoriesRegistryService.debugDisplayMongooseSchemas(options);
+    }
+
+    /**
+     * Quick debug summary of all schemas
+     */
+    public debugShowSchemasSummary(): void {
+        this.logDebug('\n🚀 === WILDO.AI BACKEND - SCHEMAS SUMMARY ===\n');
+
+        if (!this.isInitialized) {
+            this.logDebug('⚠️  Application not initialized yet. Schemas may not be available.');
+            return;
+        }
+
+        this.repositoriesRegistryService.debugShowSchemasSummary();
+    }
+
+    /**
+     * Debug function to display all registered routes
+     */
+    public debugDisplayRegisteredRoutes(): void {
+        this.logDebug('\n🌐 === WILDO.AI BACKEND - REGISTERED ROUTES ===\n');
+
+        if (!this.isInitialized) {
+            this.logDebug('⚠️  Application not initialized yet. Routes may not be available.');
+            return;
+        }
+
+        this.controllersRegistryService.displayAllRoutes();
+    }
+
+    /**
+     * Get the controllers registry for route registration
+     */
+    public getControllersRegistry(): ControllersRegistryHandlerBackendService {
+        this.ensureInitialized();
+        return this.controllersRegistryService;
+    }
+
+    /**
+     * Get the services registry for business logic access
+     */
+    public getServicesRegistry(): ServicesRegistryHandlerBackendService {
+        this.ensureInitialized();
+        return this.servicesRegistryService;
+    }
+
+    /**
+     * Get the HTTP server service instance
+     */
+    public getHttpServer(): HttpServerBackendService {
+        this.ensureInitialized();
+        return this.httpServerService;
+    }
+
+    /**
+     * Get the authorizations service instance
+     */
+    public getAuthorizationsService(): AuthorizationsBackendService {
+        this.ensureInitialized();
+        return this.authorizationsService;
+    }
+
+    /**
+     * Validate that all components are properly initialized
+     */
+    private async validateInitialization(): Promise<void> {
+        this.logDebug('Validating application initialization...');
+
+        try {
+            // Validate app config is accessible
+            if (!this.isPlatformMode) {
+                const config = this.appConfigService.config;
+                if (!config) {
+                    const error = this.errorBuilder.buildError(
+                        ErrorType.CONFIGURATION,
+                        undefined,
+                        {customMessageReference: ErrorCustomMessageReference.START_APPLICATION_CONFIGURATION_FAILED}
+                    );
+                    throw error;
+                }
+            }
+
+            // Validate resources registry is accessible
+            const registry = this.resourcesRegistryService.getResourcesRegistry();
+            if (!registry) {
+                const error = this.errorBuilder.buildError(
+                    ErrorType.INTERNAL,
+                    undefined,
+                    {customMessageReference: ErrorCustomMessageReference.START_APPLICATION_INITIALIZATION_FAILED}
+                );
+                throw error;
+            }
+
+            // Validate repositories registry is accessible
+            // const repositoriesDebugInfo = this.repositoriesRegistryService.getDebugInfo();
+            // if (!repositoriesDebugInfo.isInitialized) {
+            //     throw new Error('Repositories registry is not initialized');
+            // }
+
+            // Validate services registry is accessible
+            // const servicesDebugInfo = this.servicesRegistryService.getDebugInfo();
+            // if (!servicesDebugInfo.isInitialized) {
+            //     throw new Error('Services registry is not initialized');
+            // }
+
+            // Validate controllers registry is accessible
+            // const controllersDebugInfo = this.controllersRegistryService.getDebugInfo();
+            // if (!controllersDebugInfo.isInitialized) {
+            //     throw new Error('Controllers registry is not initialized');
+            // }
+
+            // // Validate HTTP server is running
+            // if (!this.httpServerService.isRunning()) {
+            //     throw new Error('HTTP server is not running');
+            // }
+
+            const serverInfo = this.httpServerService.getServerInfo();
+
+            // this.logDebug('Application initialization validation successful', {
+            //     appName: config.appIdentity.appName,
+            //     environment: process.env.APPLICATION_ENV,
+            //     resourcesCount: Object.keys(registry.resourceConfigurations).length,
+            //     repositoriesCount: repositoriesDebugInfo.repositoryCount,
+            //     repositoriesOperationPaths: repositoriesDebugInfo.operationPathsCount,
+            //     servicesCount: servicesDebugInfo.serviceCount,
+            //     servicesOperationPaths: servicesDebugInfo.operationPathsCount,
+            //     controllersCount: controllersDebugInfo.controllerCount,
+            //     controllersOperationPaths: controllersDebugInfo.operationPathsCount,
+            //     totalRoutes: controllersDebugInfo.totalRoutes,
+            //     httpServerRunning: this.httpServerService.isRunning(),
+            //     serverHost: serverInfo?.host,
+            //     serverPort: serverInfo?.port
+            // });
+
+        } catch (error) {
+            this.logger.error('Application initialization validation failed:', error);
+            throw error;
+        }
+    }
+
+    /**
+     * Ensure the application is initialized before operations
+     */
+    private ensureInitialized(): void {
+        if (!this.isInitialized) {
+            const error = this.errorBuilder.buildError(
+                ErrorType.INTERNAL,
+                undefined,
+                { customMessageReference: ErrorCustomMessageReference.START_APPLICATION_STARTUP_FAILED }
+            );
+            throw error;
+        }
+    }
+}