From 5b37333d31b60f17871f6872e16ddf60b374e9d7 Mon Sep 17 00:00:00 2001
From: Adhish-Krishna <adhishthesak@gmail.com>
Date: Thu, 5 Mar 2026 22:29:17 +0530
Subject: [PATCH 1/5] disabled the package selection in edit mode

---
 dashboard/app/templates/editor/page.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/dashboard/app/templates/editor/page.tsx b/dashboard/app/templates/editor/page.tsx
index 85aa488..772126f 100644
--- a/dashboard/app/templates/editor/page.tsx
+++ b/dashboard/app/templates/editor/page.tsx
@@ -718,6 +718,7 @@ function TemplateEditorContent() {
               <Label className="text-xs">Package</Label>
               <Select
                 value={form.package}
+                disabled={mode === "edit"}
                 onValueChange={(value) =>
                   setForm((prev) => ({
                     ...prev,

From bda658acbaaa55f2f017ec83a756f77ae657da7c Mon Sep 17 00:00:00 2001
From: Adhish-Krishna <adhishthesak@gmail.com>
Date: Fri, 6 Mar 2026 20:37:53 +0530
Subject: [PATCH 2/5] fix: enhance validation for notification schemas to
 require non-empty channel, template_id, or content

---
 src/api/utils/utils.ts           |  4 +-
 src/types/schemas.ts             | 61 +++++++++++++--------
 tests/unit/types/schemas.test.ts | 94 ++++++++++++++++++++++++++++++++
 3 files changed, 134 insertions(+), 25 deletions(-)

diff --git a/src/api/utils/utils.ts b/src/api/utils/utils.ts
index b8ea8da..ca20e57 100644
--- a/src/api/utils/utils.ts
+++ b/src/api/utils/utils.ts
@@ -525,14 +525,14 @@ export const validateContentSchema = (
   }
   if (!provider) {
     throw new ProviderNotFoundError(
-      `Provider not found with the given provider_id: ${provider_id}`,
+      `Provider not found with the given provider_id: ${provider_id ?? "Default Provider"}`,
     );
   }
   const providerContentSchema = provider.getContentSchema();
   const validationResult = providerContentSchema.safeParse(content);
   if (!validationResult.success) {
     throw new InvalidContentSchemaError(
-      `Content Validation failed for given provider_id: ${provider_id}`,
+      `Content Validation failed for given provider_id: ${provider_id ?? "Default Provider"}`,
       validationResult.error,
     );
   }
diff --git a/src/types/schemas.ts b/src/types/schemas.ts
index f9cd714..29ff24f 100644
--- a/src/types/schemas.ts
+++ b/src/types/schemas.ts
@@ -33,6 +33,13 @@ export const UUIDV4Schema = z.custom<UUID>(
 
 export const variablesSchema = z.record(z.string(), z.string());
 
+const hasNonEmptyTemplateIds = (templateIds?: string[]) =>
+  Array.isArray(templateIds) && templateIds.length > 0;
+
+const hasNonEmptyContent = (
+  content?: Record<string, Record<string, string>>,
+) => !!content && Object.keys(content).length > 0;
+
 // ============================================================================
 // BASE NOTIFICATION SCHEMA (Channel-Agnostic)
 // ============================================================================
@@ -271,7 +278,7 @@ export const baseNotificationRequestSchema = z
     client_id: UUIDV4Schema,
     client_name: z.string().optional(),
     template_id: z.array(z.string()).optional(),
-    channel: z.array(z.string()),
+    channel: z.array(z.string()).min(1, "At least one channel is required."),
     provider: z.array(z.string()).optional(),
     recipient: z.record(z.string(), z.unknown()),
     content: z.record(z.string(), z.record(z.string(), z.string())).optional(),
@@ -279,17 +286,21 @@ export const baseNotificationRequestSchema = z
     scheduled_at: z.coerce.date().optional(),
     webhook_url: z.url(),
   })
-  .refine(
-    (data) => {
-      if (data.template_id || data.content) {
-        return true;
+  .superRefine((data, ctx) => {
+    if (
+      !hasNonEmptyTemplateIds(data.template_id) &&
+      !hasNonEmptyContent(data.content)
+    ) {
+      for (const path of ["template_id", "content"] as const) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            "Either a non-empty template_id array or non-empty content must be present.",
+          path: [path],
+        });
       }
-    },
-    {
-      message: "Either template_id array or content must be present.",
-      path: ["template_id", "content"],
-    },
-  );
+    }
+  });
 
 /**
  * Batch notification request - channel-agnostic
@@ -298,7 +309,7 @@ export const baseBatchNotificationRequestSchema = z
   .object({
     client_id: UUIDV4Schema,
     client_name: z.string().optional(),
-    channel: z.array(z.string()),
+    channel: z.array(z.string()).min(1, "At least one channel is required."),
     template_id: z.array(z.string()).optional(),
     provider: z
       .union([z.string(), z.array(z.string().nullable().optional())])
@@ -310,7 +321,7 @@ export const baseBatchNotificationRequestSchema = z
         user_id: z.string(),
         variables: variablesSchema.optional(),
       }),
-    ),
+    ).min(1, "At least one recipient is required."),
     scheduled_at: z.coerce.date().optional(),
     webhook_url: z.url(),
   })
@@ -330,17 +341,21 @@ export const baseBatchNotificationRequestSchema = z
       path: ["recipients"],
     },
   )
-  .refine(
-    (data) => {
-      if (data.template_id || data.content) {
-        return true;
+  .superRefine((data, ctx) => {
+    if (
+      !hasNonEmptyTemplateIds(data.template_id) &&
+      !hasNonEmptyContent(data.content)
+    ) {
+      for (const path of ["template_id", "content"] as const) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            "Either a non-empty template_id array or non-empty content must be present.",
+          path: [path],
+        });
       }
-    },
-    {
-      message: "Either template_id array or content must be present.",
-      path: ["template_id", "content"],
-    },
-  );
+    }
+  });
 
 /*
 Notification Template Request Schema
diff --git a/tests/unit/types/schemas.test.ts b/tests/unit/types/schemas.test.ts
index eddf952..dfebc04 100644
--- a/tests/unit/types/schemas.test.ts
+++ b/tests/unit/types/schemas.test.ts
@@ -184,6 +184,46 @@ describe('Notification Request Schema', () => {
             const result = safeValidateNotificationRequest(validRequest);
             expect(result.success).toBe(true);
         });
+
+        it('should fail when channel is empty', () => {
+            const invalidRequest = {
+                request_id: randomUUID(),
+                client_id: randomUUID(),
+                channel: [],
+                recipient: {
+                    user_id: 'user-123',
+                    email: 'test@example.com',
+                },
+                content: {
+                    email: {
+                        subject: 'Test',
+                        message: 'Test',
+                    },
+                },
+                webhook_url: 'https://webhook.example.com/callback',
+            };
+
+            const result = safeValidateNotificationRequest(invalidRequest);
+            expect(result.success).toBe(false);
+        });
+
+        it('should fail when template_id and content are both empty', () => {
+            const invalidRequest = {
+                request_id: randomUUID(),
+                client_id: randomUUID(),
+                channel: ['email'],
+                template_id: [],
+                recipient: {
+                    user_id: 'user-123',
+                    email: 'test@example.com',
+                },
+                content: {},
+                webhook_url: 'https://webhook.example.com/callback',
+            };
+
+            const result = safeValidateNotificationRequest(invalidRequest);
+            expect(result.success).toBe(false);
+        });
     });
 });
 
@@ -212,6 +252,60 @@ describe('Batch Notification Request Schema', () => {
                 expect(result.data.recipients.length).toBe(2);
             }
         });
+
+        it('should fail when batch channel is empty', () => {
+            const invalidRequest = {
+                client_id: randomUUID(),
+                channel: [],
+                content: {
+                    email: {
+                        subject: 'Batch Test',
+                        message: 'Hello {{name}}',
+                    },
+                },
+                recipients: [
+                    { request_id: randomUUID(), user_id: 'user-1', email: 'user1@example.com' },
+                ],
+                webhook_url: 'https://webhook.example.com/callback',
+            };
+
+            const result = safeValidateBatchNotificationRequest(invalidRequest);
+            expect(result.success).toBe(false);
+        });
+
+        it('should fail when batch recipients are empty', () => {
+            const invalidRequest = {
+                client_id: randomUUID(),
+                channel: ['email'],
+                content: {
+                    email: {
+                        subject: 'Batch Test',
+                        message: 'Hello {{name}}',
+                    },
+                },
+                recipients: [],
+                webhook_url: 'https://webhook.example.com/callback',
+            };
+
+            const result = safeValidateBatchNotificationRequest(invalidRequest);
+            expect(result.success).toBe(false);
+        });
+
+        it('should fail when batch template_id and content are both empty', () => {
+            const invalidRequest = {
+                client_id: randomUUID(),
+                channel: ['email'],
+                template_id: [],
+                content: {},
+                recipients: [
+                    { request_id: randomUUID(), user_id: 'user-1', email: 'user1@example.com' },
+                ],
+                webhook_url: 'https://webhook.example.com/callback',
+            };
+
+            const result = safeValidateBatchNotificationRequest(invalidRequest);
+            expect(result.success).toBe(false);
+        });
     });
 });
 

From 2b66734a224ed62ed98e7c128235848eb1870c3b Mon Sep 17 00:00:00 2001
From: Adhish-Krishna <adhishthesak@gmail.com>
Date: Sat, 7 Mar 2026 14:11:42 +0530
Subject: [PATCH 3/5] feat: implement fallback provider handling when retry
 budget exceeds for current provider

---
 src/plugins/index.ts                          |   9 +-
 src/plugins/loader/registry.ts                |  13 +
 src/plugins/loader/router.ts                  |  43 +++
 src/processors/unified/unified.consumer.ts    | 139 +++++--
 tests/unit/plugins/router.test.ts             |  61 +++
 .../unit/processors/unified.consumer.test.ts  | 349 ++++++++++++++++++
 6 files changed, 583 insertions(+), 31 deletions(-)
 create mode 100644 tests/unit/processors/unified.consumer.test.ts

diff --git a/src/plugins/index.ts b/src/plugins/index.ts
index 8f0290d..da6e5e6 100644
--- a/src/plugins/index.ts
+++ b/src/plugins/index.ts
@@ -19,4 +19,11 @@ export {
 export { loadProviders, loadProvidersFromEnv, registerProvider, getConfiguredChannels } from './loader/loader.js';
 
 // Router
-export { sendWithFallback, sendToProvider, validateNotification, getRateLimitConfig } from './loader/router.js';
+export {
+    sendWithFallback,
+    sendToProvider,
+    validateNotification,
+    validateNotificationForProvider,
+    resolveFallbackProviderId,
+    getRateLimitConfig
+} from './loader/router.js';
diff --git a/src/plugins/loader/registry.ts b/src/plugins/loader/registry.ts
index 16ed41e..e056f71 100644
--- a/src/plugins/loader/registry.ts
+++ b/src/plugins/loader/registry.ts
@@ -230,6 +230,19 @@ class PluginRegistryClass {
         return providers[1];
     }
 
+    /**
+     * Get fallback provider ID for a channel
+     */
+    getFallbackProviderId(channel: string): string | undefined {
+        const config = this.channelConfig.get(channel);
+        if (config?.fallback) {
+            return config.fallback;
+        }
+        // Fall back to second registered provider ID for channel
+        const ids = this.channelProviders.get(channel);
+        return ids?.[1];
+    }
+
     /**
      * Get all registered provider IDs
      */
diff --git a/src/plugins/loader/router.ts b/src/plugins/loader/router.ts
index d0128fc..35ca700 100644
--- a/src/plugins/loader/router.ts
+++ b/src/plugins/loader/router.ts
@@ -86,6 +86,23 @@ async function tryFallback<T extends BaseNotification>(
     };
 }
 
+/**
+ * Resolve a fallback provider ID for retry exhaustion handoff.
+ * Returns undefined when no distinct fallback provider is available.
+ */
+export function resolveFallbackProviderId(
+    channel: string,
+    currentProviderId?: string
+): string | undefined {
+    const fallbackProviderId = PluginRegistry.getFallbackProviderId(channel);
+
+    if (!fallbackProviderId || fallbackProviderId === currentProviderId) {
+        return undefined;
+    }
+
+    return fallbackProviderId;
+}
+
 /**
  * Send notification with automatic fallback
  * 
@@ -165,6 +182,32 @@ export async function sendToProvider<T extends BaseNotification>(
     return provider.send(notification);
 }
 
+/**
+ * Validate notification against a specific provider schema
+ */
+export function validateNotificationForProvider<T extends BaseNotification>(
+    providerId: string,
+    notification: unknown
+): { success: true; data: T } | { success: false; error: string } {
+    const provider = PluginRegistry.get(providerId);
+
+    if (!provider) {
+        return { success: false, error: `Provider '${providerId}' not found` };
+    }
+
+    const schema = provider.getNotificationSchema();
+    const result = schema.safeParse(notification);
+
+    if (result.success) {
+        return { success: true, data: result.data as T };
+    }
+
+    return {
+        success: false,
+        error: result.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join(', '),
+    };
+}
+
 /**
  * Validate notification against provider schema
  */
diff --git a/src/processors/unified/unified.consumer.ts b/src/processors/unified/unified.consumer.ts
index b5b1f94..541f0f4 100644
--- a/src/processors/unified/unified.consumer.ts
+++ b/src/processors/unified/unified.consumer.ts
@@ -17,7 +17,12 @@ import { env } from '@src/config/env.config.js';
 import { unifiedProcessorLogger as logger } from './unified.logger.js';
 
 // Plugin system
-import { sendWithFallback, PluginRegistry } from '@src/plugins/index.js';
+import {
+    sendWithFallback,
+    PluginRegistry,
+    resolveFallbackProviderId,
+    validateNotificationForProvider
+} from '@src/plugins/index.js';
 import type { BaseNotification, DeliveryResult } from '@src/plugins/interfaces/provider.types.js';
 
 // Shared utilities
@@ -95,6 +100,67 @@ const publishFailureStatus = async (
     await publishStatus(status as any);
 };
 
+/**
+ * Hand off a retry-exhausted notification to the fallback provider via delayed queue.
+ * This gives the fallback provider its own retry budget while preserving normal backoff.
+ */
+export const scheduleFallbackProviderHandoff = async (
+    channel: string,
+    notification: BaseNotification,
+    currentProviderId: string | undefined,
+    errorMessage: string
+): Promise<boolean> => {
+    const fallbackProviderId = resolveFallbackProviderId(channel, currentProviderId);
+
+    if (!fallbackProviderId) {
+        return false;
+    }
+
+    const fallbackNotification: BaseNotification = {
+        ...notification,
+        provider: fallbackProviderId,
+    };
+
+    const validationResult = validateNotificationForProvider<BaseNotification>(
+        fallbackProviderId,
+        fallbackNotification
+    );
+
+    if (!validationResult.success) {
+        logger.error(
+            `[${channel}] Fallback handoff validation failed: ${notification.notification_id} - ${validationResult.error}`
+        );
+        return false;
+    }
+
+    await setFailed(notification.notification_id.toString(), notification.retry_count);
+    const delayedPayload = buildDelayedPayloadGeneric(
+        validationResult.data as unknown as Record<string, unknown>,
+        channel,
+        0
+    );
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    await publishDelayed(delayedPayload as any);
+
+    void AdminAlertService.sendAlert(
+        'service_health',
+        `INFO: RETRY BUDGET EXHAUSTED, SWITCHING TO FALLBACK\n` +
+        `Notification ID: ${notification.notification_id}\n` +
+        `Channel: ${channel}\n` +
+        `Primary provider: ${currentProviderId || 'default'}\n` +
+        `Fallback provider: ${fallbackProviderId}\n` +
+        `Error: ${errorMessage}\n` +
+        `Action: Investigate the primary provider if this handoff becomes frequent.`,
+        { severity: 'warning', notificationId: notification.notification_id, channel }
+    );
+
+    logger.warn(
+        `[${channel}] Retry budget exhausted for provider ${currentProviderId || 'default'}, ` +
+        `scheduled fallback handoff to ${fallbackProviderId}: ${notification.notification_id}`
+    );
+    return true;
+};
+
 /**
  * Process a single notification message
  * Returns true if processing completed (commit offset)
@@ -204,13 +270,25 @@ const processMessage = async (
 
             const newRetryCount = notification.retry_count + 1;
             if (newRetryCount > env.MAX_RETRY_COUNT) {
-                logger.error(`[${channel}] Max retries exceeded: ${notificationId}`);
+                const currentProviderId = notification.provider || PluginRegistry.getDefaultProviderId(channel);
+                const handoffScheduled = await scheduleFallbackProviderHandoff(
+                    channel,
+                    notification,
+                    currentProviderId,
+                    `Rate limited after ${env.MAX_RETRY_COUNT} retries`
+                );
+
+                if (handoffScheduled) {
+                    return true;
+                }
+
+                logger.error(`[${channel}] Max retries exceeded (rate limited): ${notificationId}`);
 
                 void AdminAlertService.sendAlert('failed_notification',
                     `❌ MAX RETRIES EXCEEDED (RATE LIMITED)\n` +
                     `Notification ID: ${notificationId}\n` +
                     `Channel: ${channel}\n` +
-                    `Provider: ${providerId}\n` +
+                    `Provider: ${currentProviderId || providerId || 'default'}\n` +
                     `Root cause: Provider rate limit exhausted after ${env.MAX_RETRY_COUNT} retries\n` +
                     `Action: Check provider rate limits in simplens.config.yaml. Consider increasing limits or adding fallback provider.`,
                     { severity: 'critical', notificationId, channel });
@@ -286,42 +364,43 @@ const processMessage = async (
             return true;
         }
         else if (result.success === false && result.error?.retryable === false) {
-            // Non-retryable failure from router (e.g., ALL_PROVIDERS_FAILED, SCHEMA_VALIDATION_ERROR)
-            // Schema validation failures are already handled by handleSchemaValidationFailure
-            // But ALL_PROVIDERS_FAILED and PROVIDER_NOT_FOUND need explicit handling here
-            if (result.error?.code === 'ALL_PROVIDERS_FAILED') {
-                logger.error(`[${channel}] All providers failed: ${notificationId} - ${result.error?.message}`);
+            const errorCode = result.error?.code || 'NON_RETRYABLE_FAILURE';
+            const errorMessage = result.error?.message || 'Non-retryable provider error';
 
-                void AdminAlertService.sendAlert('failed_notification',
-                    `🔴 ALL PROVIDERS FAILED\n` +
-                    `Notification ID: ${notificationId}\n` +
-                    `Channel: ${channel}\n` +
-                    `Error: ${result.error?.message}\n` +
-                    `Action: Check provider credentials and connectivity. Review simplens.config.yaml.`,
-                    { severity: 'critical', notificationId, channel });
+            logger.error(`[${channel}] Non-retryable failure: ${notificationId} (${errorCode}) - ${errorMessage}`);
 
-                await setFailed(notificationId, validationResult.data.retry_count);
-                await publishFailureStatus(notification, channel, result.error?.message || 'All providers failed');
-            } else if (result.error?.code === 'PROVIDER_NOT_FOUND') {
-                logger.error(`[${channel}] Provider not found: ${notificationId} - ${result.error?.message}`);
+            void AdminAlertService.sendAlert('failed_notification',
+                `❌ NON-RETRYABLE PROVIDER FAILURE\n` +
+                `Notification ID: ${notificationId}\n` +
+                `Channel: ${channel}\n` +
+                `Error code: ${errorCode}\n` +
+                `Error: ${errorMessage}\n` +
+                `Action: Check provider configuration and connectivity. Review simplens.config.yaml.`,
+                { severity: 'critical', notificationId, channel });
 
-                void AdminAlertService.sendAlert('failed_notification',
-                    `🔴 PROVIDER NOT FOUND\n` +
-                    `Notification ID: ${notificationId}\n` +
-                    `Channel: ${channel}\n` +
-                    `Error: ${result.error?.message}\n` +
-                    `Action: Check simplens.config.yaml. Verify provider is installed and configured.`,
-                    { severity: 'critical', notificationId, channel });
+            await setFailed(notificationId, validationResult.data.retry_count);
+            await publishFailureStatus(notification, channel, errorMessage);
 
-                await setFailed(notificationId, validationResult.data.retry_count);
-                await publishFailureStatus(notification, channel, result.error?.message || 'Provider not found');
-            }
-            // Commit kafka offset
+            // Commit kafka offset after persisting failed state + status
             return true;
         }
         else {
             // 6b. Failure - check if retryable
             const newRetryCount = notification.retry_count + 1;
+            const currentProviderId = notification.provider || PluginRegistry.getDefaultProviderId(channel);
+
+            if (result.error?.retryable && newRetryCount > env.MAX_RETRY_COUNT) {
+                const handoffScheduled = await scheduleFallbackProviderHandoff(
+                    channel,
+                    notification,
+                    currentProviderId,
+                    result.error?.message || 'Unknown retryable error'
+                );
+
+                if (handoffScheduled) {
+                    return true;
+                }
+            }
 
             if (!result.error?.retryable || newRetryCount > env.MAX_RETRY_COUNT) {
                 logger.error(`[${channel}] Final failure: ${notificationId} - ${result.error?.message}`);
diff --git a/tests/unit/plugins/router.test.ts b/tests/unit/plugins/router.test.ts
index 638f9f6..7fdd848 100644
--- a/tests/unit/plugins/router.test.ts
+++ b/tests/unit/plugins/router.test.ts
@@ -69,6 +69,8 @@ describe('Provider Router', () => {
     let sendWithFallback: typeof import('../../../src/plugins/loader/router.js').sendWithFallback;
     let sendToProvider: typeof import('../../../src/plugins/loader/router.js').sendToProvider;
     let validateNotification: typeof import('../../../src/plugins/loader/router.js').validateNotification;
+    let validateNotificationForProvider: typeof import('../../../src/plugins/loader/router.js').validateNotificationForProvider;
+    let resolveFallbackProviderId: typeof import('../../../src/plugins/loader/router.js').resolveFallbackProviderId;
     let getRateLimitConfig: typeof import('../../../src/plugins/loader/router.js').getRateLimitConfig;
 
     beforeEach(async () => {
@@ -80,6 +82,8 @@ describe('Provider Router', () => {
         sendWithFallback = routerModule.sendWithFallback;
         sendToProvider = routerModule.sendToProvider;
         validateNotification = routerModule.validateNotification;
+        validateNotificationForProvider = routerModule.validateNotificationForProvider;
+        resolveFallbackProviderId = routerModule.resolveFallbackProviderId;
         getRateLimitConfig = routerModule.getRateLimitConfig;
 
         PluginRegistry.clear();
@@ -316,6 +320,63 @@ describe('Provider Router', () => {
         });
     });
 
+    describe('validateNotificationForProvider', () => {
+        it('should validate notification against a specific provider schema', () => {
+            const gmail = createMockProvider({ name: 'gmail', channel: 'email' });
+            PluginRegistry.register(gmail as any, 'gmail', 1);
+
+            const notification = {
+                notification_id: 'notif-123',
+                request_id: 'req-123',
+                client_id: 'client-123',
+                channel: 'email',
+                provider: 'gmail',
+                recipient: { user_id: 'user-123' },
+                content: { message: 'Hello' },
+                webhook_url: 'https://webhook.example.com',
+                retry_count: 0,
+                created_at: new Date(),
+            };
+
+            const result = validateNotificationForProvider('gmail', notification);
+
+            expect(result.success).toBe(true);
+        });
+
+        it('should return an error if provider is not found', () => {
+            const result = validateNotificationForProvider('missing-provider', {});
+
+            expect(result.success).toBe(false);
+            if (!result.success) {
+                expect(result.error).toContain("Provider 'missing-provider' not found");
+            }
+        });
+    });
+
+    describe('resolveFallbackProviderId', () => {
+        it('should resolve fallback provider when it differs from the current provider', () => {
+            const primary = createMockProvider({ name: 'primary', channel: 'email' });
+            const fallback = createMockProvider({ name: 'fallback', channel: 'email' });
+
+            PluginRegistry.register(primary as any, 'primary', 2);
+            PluginRegistry.register(fallback as any, 'fallback', 1);
+            PluginRegistry.setChannelConfig('email', { default: 'primary', fallback: 'fallback' });
+
+            expect(resolveFallbackProviderId('email', 'primary')).toBe('fallback');
+        });
+
+        it('should return undefined when current provider is already the fallback provider', () => {
+            const primary = createMockProvider({ name: 'primary', channel: 'email' });
+            const fallback = createMockProvider({ name: 'fallback', channel: 'email' });
+
+            PluginRegistry.register(primary as any, 'primary', 2);
+            PluginRegistry.register(fallback as any, 'fallback', 1);
+            PluginRegistry.setChannelConfig('email', { default: 'primary', fallback: 'fallback' });
+
+            expect(resolveFallbackProviderId('email', 'fallback')).toBeUndefined();
+        });
+    });
+
     describe('getRateLimitConfig', () => {
         it('should return rate limit config for provider', () => {
             const gmail = createMockProvider({
diff --git a/tests/unit/processors/unified.consumer.test.ts b/tests/unit/processors/unified.consumer.test.ts
new file mode 100644
index 0000000..77d591b
--- /dev/null
+++ b/tests/unit/processors/unified.consumer.test.ts
@@ -0,0 +1,349 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const sendAlertMock = vi.fn().mockResolvedValue(undefined);
+const setFailedMock = vi.fn().mockResolvedValue(undefined);
+const setDeliveredMock = vi.fn().mockResolvedValue(undefined);
+const setRateLimitedMock = vi.fn().mockResolvedValue(undefined);
+const tryAcquireProcessingLockMock = vi.fn();
+const buildDelayedPayloadGenericMock = vi.fn();
+const publishDelayedMock = vi.fn().mockResolvedValue(undefined);
+const publishStatusMock = vi.fn().mockResolvedValue(undefined);
+const consumeTokenMock = vi.fn();
+const resolveFallbackProviderIdMock = vi.fn();
+const validateNotificationForProviderMock = vi.fn();
+const sendWithFallbackMock = vi.fn();
+
+const providerSafeParseMock = vi.fn();
+const providerGetNotificationSchemaMock = vi.fn(() => ({
+    safeParse: providerSafeParseMock,
+}));
+const pluginRegistryGetMock = vi.fn();
+const pluginRegistryGetDefaultProviderIdMock = vi.fn();
+
+let eachMessageHandler: ((payload: {
+    topic: string;
+    partition: number;
+    message: { value: Buffer | null; offset: string };
+}) => Promise<void>) | undefined;
+
+const commitOffsetsMock = vi.fn().mockResolvedValue(undefined);
+const kafkaConsumerMock = {
+    connect: vi.fn().mockResolvedValue(undefined),
+    subscribe: vi.fn().mockResolvedValue(undefined),
+    run: vi.fn().mockImplementation(async ({ eachMessage }) => {
+        eachMessageHandler = eachMessage;
+    }),
+    commitOffsets: commitOffsetsMock,
+    stop: vi.fn().mockResolvedValue(undefined),
+    disconnect: vi.fn().mockResolvedValue(undefined),
+};
+
+vi.mock('../../../src/config/kafka.config.js', () => ({
+    kafka: {
+        consumer: vi.fn(() => kafkaConsumerMock),
+    },
+}));
+
+vi.mock('../../../src/plugins/index.js', () => ({
+    PluginRegistry: {
+        get: pluginRegistryGetMock,
+        getDefaultProviderId: pluginRegistryGetDefaultProviderIdMock,
+    },
+    sendWithFallback: sendWithFallbackMock,
+    resolveFallbackProviderId: resolveFallbackProviderIdMock,
+    validateNotificationForProvider: validateNotificationForProviderMock,
+}));
+
+vi.mock('../../../src/admin-alerts/admin-alert.service.js', () => ({
+    AdminAlertService: {
+        sendAlert: sendAlertMock,
+    },
+}));
+
+vi.mock('../../../src/processors/shared/idempotency.js', () => ({
+    tryAcquireProcessingLock: tryAcquireProcessingLockMock,
+    setDelivered: setDeliveredMock,
+    setFailed: setFailedMock,
+    setRateLimited: setRateLimitedMock,
+}));
+
+vi.mock('../../../src/processors/shared/delayed.producer.js', () => ({
+    publishDelayed: publishDelayedMock,
+    buildDelayedPayloadGeneric: buildDelayedPayloadGenericMock,
+}));
+
+vi.mock('../../../src/processors/shared/status.producer.js', () => ({
+    publishStatus: publishStatusMock,
+}));
+
+vi.mock('../../../src/processors/shared/schema-failure-handler.js', () => ({
+    handleSchemaValidationFailure: vi.fn(),
+}));
+
+vi.mock('../../../src/processors/shared/rate-limiter.js', () => ({
+    consumeToken: consumeTokenMock,
+}));
+
+vi.mock('../../../src/workers/utils/logger.js', () => ({
+    apiLogger: {
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+        debug: vi.fn(),
+        success: vi.fn(),
+    },
+}));
+
+vi.mock('../../../src/processors/unified/unified.logger.js', () => ({
+    unifiedProcessorLogger: {
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+        debug: vi.fn(),
+        success: vi.fn(),
+    },
+}));
+
+vi.mock('../../../src/database/models/status-outbox.models.js', () => ({
+    default: {
+        create: vi.fn(),
+    },
+}));
+
+describe('scheduleFallbackProviderHandoff', () => {
+    beforeEach(() => {
+        vi.resetModules();
+        vi.clearAllMocks();
+        eachMessageHandler = undefined;
+
+        providerSafeParseMock.mockImplementation((notification) => ({
+            success: true,
+            data: notification,
+        }));
+        pluginRegistryGetDefaultProviderIdMock.mockReturnValue('primary');
+        pluginRegistryGetMock.mockReturnValue({
+            getNotificationSchema: providerGetNotificationSchemaMock,
+        });
+        tryAcquireProcessingLockMock.mockResolvedValue({ canProcess: true, isRetry: false });
+        consumeTokenMock.mockResolvedValue({ allowed: true });
+        sendWithFallbackMock.mockResolvedValue({ success: true, messageId: 'msg-1' });
+
+        buildDelayedPayloadGenericMock.mockReturnValue({
+            notification_id: 'notif-123',
+            request_id: 'req-123',
+            client_id: 'client-123',
+            scheduled_at: new Date(),
+            target_topic: 'email_notification',
+            payload: {},
+            created_at: new Date(),
+        });
+    });
+
+    it('should republish to delayed queue with fallback provider and reset retry count', async () => {
+        resolveFallbackProviderIdMock.mockReturnValue('fallback');
+        validateNotificationForProviderMock.mockImplementation((_providerId, notification) => ({
+            success: true,
+            data: notification,
+        }));
+
+        const { scheduleFallbackProviderHandoff } = await import('../../../src/processors/unified/unified.consumer.js');
+        const notification = {
+            notification_id: 'notif-123',
+            request_id: 'req-123',
+            client_id: 'client-123',
+            channel: 'email',
+            provider: 'primary',
+            recipient: { user_id: 'user-123' },
+            content: { message: 'Hello' },
+            webhook_url: 'https://webhook.example.com',
+            retry_count: 5,
+            created_at: new Date(),
+        };
+
+        const result = await scheduleFallbackProviderHandoff(
+            'email',
+            notification,
+            'primary',
+            'Rate limited'
+        );
+
+        expect(result).toBe(true);
+        expect(validateNotificationForProviderMock).toHaveBeenCalledWith(
+            'fallback',
+            expect.objectContaining({ provider: 'fallback' })
+        );
+        expect(setFailedMock).toHaveBeenCalledWith('notif-123', 5);
+        expect(buildDelayedPayloadGenericMock).toHaveBeenCalledWith(
+            expect.objectContaining({ provider: 'fallback' }),
+            'email',
+            0
+        );
+        expect(publishDelayedMock).toHaveBeenCalledTimes(1);
+        expect(sendAlertMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('should return false when no fallback provider is available', async () => {
+        resolveFallbackProviderIdMock.mockReturnValue(undefined);
+
+        const { scheduleFallbackProviderHandoff } = await import('../../../src/processors/unified/unified.consumer.js');
+        const notification = {
+            notification_id: 'notif-123',
+            request_id: 'req-123',
+            client_id: 'client-123',
+            channel: 'email',
+            provider: 'primary',
+            recipient: { user_id: 'user-123' },
+            content: { message: 'Hello' },
+            webhook_url: 'https://webhook.example.com',
+            retry_count: 5,
+            created_at: new Date(),
+        };
+
+        const result = await scheduleFallbackProviderHandoff(
+            'email',
+            notification,
+            'primary',
+            'Rate limited'
+        );
+
+        expect(result).toBe(false);
+        expect(validateNotificationForProviderMock).not.toHaveBeenCalled();
+        expect(publishDelayedMock).not.toHaveBeenCalled();
+    });
+
+    it('should return false when fallback validation fails', async () => {
+        resolveFallbackProviderIdMock.mockReturnValue('fallback');
+        validateNotificationForProviderMock.mockReturnValue({
+            success: false,
+            error: 'content.message: Required',
+        });
+
+        const { scheduleFallbackProviderHandoff } = await import('../../../src/processors/unified/unified.consumer.js');
+        const notification = {
+            notification_id: 'notif-123',
+            request_id: 'req-123',
+            client_id: 'client-123',
+            channel: 'email',
+            provider: 'primary',
+            recipient: { user_id: 'user-123' },
+            content: { message: 'Hello' },
+            webhook_url: 'https://webhook.example.com',
+            retry_count: 5,
+            created_at: new Date(),
+        };
+
+        const result = await scheduleFallbackProviderHandoff(
+            'email',
+            notification,
+            'primary',
+            'Rate limited'
+        );
+
+        expect(result).toBe(false);
+        expect(setFailedMock).not.toHaveBeenCalled();
+        expect(publishDelayedMock).not.toHaveBeenCalled();
+    });
+});
+
+describe('processMessage via consumer run loop', () => {
+    const createNotification = (overrides: Record<string, unknown> = {}) => ({
+        notification_id: 'notif-123',
+        request_id: 'req-123',
+        client_id: 'client-123',
+        channel: 'email',
+        provider: 'primary',
+        recipient: { user_id: 'user-123' },
+        content: { message: 'Hello' },
+        webhook_url: 'https://webhook.example.com',
+        retry_count: 0,
+        created_at: new Date().toISOString(),
+        ...overrides,
+    });
+
+    const startAndProcess = async (notification: Record<string, unknown>) => {
+        const { startUnifiedConsumer, stopUnifiedConsumer } = await import('../../../src/processors/unified/unified.consumer.js');
+
+        await startUnifiedConsumer('email');
+        expect(eachMessageHandler).toBeDefined();
+
+        await eachMessageHandler!({
+            topic: 'email_notification',
+            partition: 0,
+            message: {
+                value: Buffer.from(JSON.stringify(notification)),
+                offset: '0',
+            },
+        });
+
+        await stopUnifiedConsumer('email');
+    };
+
+    it('should set failed, publish failure status, and alert for non-retryable provider errors', async () => {
+        sendWithFallbackMock.mockResolvedValue({
+            success: false,
+            error: {
+                code: 'AUTH_FAILED',
+                message: 'Invalid credentials',
+                retryable: false,
+            },
+        });
+
+        await startAndProcess(createNotification());
+
+        expect(setFailedMock).toHaveBeenCalledWith('notif-123', 0);
+        expect(publishStatusMock).toHaveBeenCalledWith(expect.objectContaining({
+            notification_id: 'notif-123',
+            status: 'failed',
+            message: 'Invalid credentials',
+        }));
+        expect(sendAlertMock).toHaveBeenCalledWith(
+            'failed_notification',
+            expect.stringContaining('NON-RETRYABLE PROVIDER FAILURE'),
+            expect.objectContaining({ severity: 'critical', notificationId: 'notif-123', channel: 'email' })
+        );
+        expect(commitOffsetsMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('should hand off to fallback when rate-limit retry budget is exceeded', async () => {
+        consumeTokenMock.mockResolvedValue({ allowed: false, retryAfterMs: 1000 });
+        resolveFallbackProviderIdMock.mockReturnValue('fallback');
+        validateNotificationForProviderMock.mockImplementation((_providerId, notification) => ({
+            success: true,
+            data: notification,
+        }));
+
+        await startAndProcess(createNotification({ retry_count: Number.MAX_SAFE_INTEGER }));
+
+        expect(resolveFallbackProviderIdMock).toHaveBeenCalledWith('email', 'primary');
+        expect(buildDelayedPayloadGenericMock).toHaveBeenCalledWith(
+            expect.objectContaining({ provider: 'fallback' }),
+            'email',
+            0
+        );
+        expect(publishDelayedMock).toHaveBeenCalledTimes(1);
+        expect(publishStatusMock).not.toHaveBeenCalledWith(expect.objectContaining({ status: 'failed' }));
+        expect(commitOffsetsMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('should set failed when retry budget exceeded and current provider is fallback', async () => {
+        consumeTokenMock.mockResolvedValue({ allowed: false, retryAfterMs: 1000 });
+        resolveFallbackProviderIdMock.mockReturnValue(undefined);
+
+        await startAndProcess(createNotification({ provider: 'fallback', retry_count: Number.MAX_SAFE_INTEGER }));
+
+        expect(resolveFallbackProviderIdMock).toHaveBeenCalledWith('email', 'fallback');
+        expect(setFailedMock).toHaveBeenCalledWith('notif-123', Number.MAX_SAFE_INTEGER);
+        expect(publishStatusMock).toHaveBeenCalledWith(expect.objectContaining({
+            notification_id: 'notif-123',
+            status: 'failed',
+            message: 'Max retry count exceeded (rate limiting)',
+        }));
+        expect(sendAlertMock).toHaveBeenCalledWith(
+            'failed_notification',
+            expect.stringContaining('MAX RETRIES EXCEEDED (RATE LIMITED)'),
+            expect.objectContaining({ severity: 'critical', notificationId: 'notif-123', channel: 'email' })
+        );
+        expect(publishDelayedMock).not.toHaveBeenCalled();
+        expect(commitOffsetsMock).toHaveBeenCalledTimes(1);
+    });
+});

From 1482a293f4daef9829bb61d1067a3a5b476890e4 Mon Sep 17 00:00:00 2001
From: Adhish-Krishna <adhishthesak@gmail.com>
Date: Sat, 7 Mar 2026 14:27:10 +0530
Subject: [PATCH 4/5] feat: add logs-data volume to services for improved
 logging management

---
 docker-compose.dev.yaml           |  9 +++++++++
 docker-compose.yaml               | 10 +++++++++-
 packages/onboard/src/templates.ts | 13 +++++++++++++
 3 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/docker-compose.dev.yaml b/docker-compose.dev.yaml
index 39f16da..5cc6425 100644
--- a/docker-compose.dev.yaml
+++ b/docker-compose.dev.yaml
@@ -152,6 +152,7 @@ services:
     volumes:
       # Mount plugins directory for user-installed plugins (optional)
       - plugin-data:/app/.plugins
+      - logs-data:/app/logs
       - ./simplens.config.yaml:/app/simplens.config.yaml:ro
     command: [ "node", "dist/api/server.js" ]
     depends_on:
@@ -190,6 +191,8 @@ services:
       OUTBOX_CLAIM_TIMEOUT_MS: ${OUTBOX_CLAIM_TIMEOUT_MS:-30000}
       LOKI_URL: http://loki:3100
       LOG_LEVEL: ${LOG_LEVEL:-info}
+    volumes:
+      - logs-data:/app/logs
     command: [ "node", "dist/workers/worker.js" ]
     depends_on:
       mongo:
@@ -231,6 +234,7 @@ services:
     volumes:
       # Mount plugins directory for user-installed plugins (optional)
       - plugin-data:/app/.plugins
+      - logs-data:/app/logs
       - ./simplens.config.yaml:/app/simplens.config.yaml:ro
     depends_on:
       mongo:
@@ -264,6 +268,8 @@ services:
       # Logging
       LOKI_URL: http://loki:3100
       LOG_LEVEL: ${LOG_LEVEL:-info}
+    volumes:
+      - logs-data:/app/logs
     command: [ "node", "dist/processors/delayed/delayed.processor.js" ]
     depends_on:
       mongo:
@@ -301,6 +307,8 @@ services:
       # Logging
       LOKI_URL: http://loki:3100
       LOG_LEVEL: ${LOG_LEVEL:-info}
+    volumes:
+      - logs-data:/app/logs
     command: [ "node", "dist/workers/recovery/recovery.service.js" ]
     depends_on:
       mongo:
@@ -355,6 +363,7 @@ volumes:
   loki_data:
   grafana_data:
   plugin-data:
+  logs-data:
 
 
 networks:
diff --git a/docker-compose.yaml b/docker-compose.yaml
index 5f72611..60acdce 100644
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -8,6 +8,7 @@ services:
       - .env
     volumes:
       - plugin-data:/app/.plugins
+      - logs-data:/app/logs
       - ./simplens.config.yaml:/app/simplens.config.yaml:ro
     command: [ "node", "dist/api/server.js" ]
     networks:
@@ -24,6 +25,8 @@ services:
     image: ghcr.io/simplenotificationsystem/simplens-core:latest
     env_file:
       - .env
+    volumes:
+      - logs-data:/app/logs
     command: [ "node", "dist/workers/worker.js" ]
     networks:
       - simplens
@@ -35,6 +38,7 @@ services:
       - .env
     volumes:
       - plugin-data:/app/.plugins
+      - logs-data:/app/logs
       - ./simplens.config.yaml:/app/simplens.config.yaml:ro
     command: [ "node", "dist/processors/unified/unified.processor.js" ]
     depends_on:
@@ -48,6 +52,8 @@ services:
     image: ghcr.io/simplenotificationsystem/simplens-core:latest
     env_file:
       - .env
+    volumes:
+      - logs-data:/app/logs
     command: [ "node", "dist/processors/delayed/delayed.processor.js" ]
     networks:
       - simplens
@@ -57,6 +63,8 @@ services:
     image: ghcr.io/simplenotificationsystem/simplens-core:latest
     env_file:
       - .env
+    volumes:
+      - logs-data:/app/logs
     command: [ "node", "dist/workers/recovery/recovery.service.js" ]
     networks:
       - simplens
@@ -80,8 +88,8 @@ services:
 
 volumes:
   plugin-data:
+  logs-data:
 
 networks:
   simplens:
     driver: bridge
-
diff --git a/packages/onboard/src/templates.ts b/packages/onboard/src/templates.ts
index 2651a0e..d64bc69 100644
--- a/packages/onboard/src/templates.ts
+++ b/packages/onboard/src/templates.ts
@@ -127,8 +127,11 @@ export const APP_COMPOSE_TEMPLATE = `services:
       - 3000:3000
     env_file:
       - .env
+    environment:
+      SIMPLENS_CONFIG_PATH: \${SIMPLENS_CONFIG_PATH:-/app/simplens.config.yaml}
     volumes:
       - plugin-data:/app/.plugins
+      - logs-data:/app/logs
       - ./simplens.config.yaml:/app/simplens.config.yaml:ro
     command: [ "node", "dist/api/server.js" ]
     restart: unless-stopped
@@ -143,6 +146,8 @@ export const APP_COMPOSE_TEMPLATE = `services:
     image: ghcr.io/simplenotificationsystem/simplens-core:\${CORE_VERSION:-latest}
     env_file:
       - .env
+    volumes:
+      - logs-data:/app/logs
     command: [ "node", "dist/workers/worker.js" ]
     restart: unless-stopped
 
@@ -150,8 +155,11 @@ export const APP_COMPOSE_TEMPLATE = `services:
     image: ghcr.io/simplenotificationsystem/simplens-core:\${CORE_VERSION:-latest}
     env_file:
       - .env
+    environment:
+      SIMPLENS_CONFIG_PATH: \${SIMPLENS_CONFIG_PATH:-/app/simplens.config.yaml}
     volumes:
       - plugin-data:/app/.plugins
+      - logs-data:/app/logs
       - ./simplens.config.yaml:/app/simplens.config.yaml:ro
     command: [ "node", "dist/processors/unified/unified.processor.js" ]
     depends_on:
@@ -163,6 +171,8 @@ export const APP_COMPOSE_TEMPLATE = `services:
     image: ghcr.io/simplenotificationsystem/simplens-core:\${CORE_VERSION:-latest}
     env_file:
       - .env
+    volumes:
+      - logs-data:/app/logs
     command: [ "node", "dist/processors/delayed/delayed.processor.js" ]
     restart: unless-stopped
 
@@ -170,6 +180,8 @@ export const APP_COMPOSE_TEMPLATE = `services:
     image: ghcr.io/simplenotificationsystem/simplens-core:\${CORE_VERSION:-latest}
     env_file:
       - .env
+    volumes:
+      - logs-data:/app/logs
     command: [ "node", "dist/workers/recovery/recovery.service.js" ]
     restart: unless-stopped
 
@@ -189,6 +201,7 @@ export const APP_COMPOSE_TEMPLATE = `services:
 
 volumes:
   plugin-data:
+  logs-data:
 
 networks:
   default:

From d16306cf5c7f6f8cd2062e7abc95aa083c99c56d Mon Sep 17 00:00:00 2001
From: Adhish-Krishna <adhishthesak@gmail.com>
Date: Sat, 7 Mar 2026 18:53:46 +0530
Subject: [PATCH 5/5] feat: implement SSL automation with Certbot for enhanced
 security setup

---
 packages/onboard/README.md                    |  28 +++-
 packages/onboard/package-lock.json            |   4 +-
 packages/onboard/package.json                 |   2 +-
 .../src/__tests__/infra-prompts.test.ts       |   4 +-
 packages/onboard/src/__tests__/infra.test.ts  |  15 ++
 .../onboard/src/__tests__/validators.test.ts  |  28 +++-
 packages/onboard/src/index.ts                 | 152 ++++++++++++++++--
 packages/onboard/src/infra.ts                 | 142 +++++++++++++---
 packages/onboard/src/services.ts              |  72 +++++++++
 packages/onboard/src/templates.ts             |  57 +++++++
 packages/onboard/src/types/domain.ts          |   6 +
 packages/onboard/src/validators.ts            |  51 ++++++
 12 files changed, 515 insertions(+), 46 deletions(-)

diff --git a/packages/onboard/README.md b/packages/onboard/README.md
index 60762e0..6e6c820 100644
--- a/packages/onboard/README.md
+++ b/packages/onboard/README.md
@@ -13,6 +13,7 @@
 - 🐧 **OS-Aware Configuration** - Automatically detects and configures for Windows, Linux, or macOS
 - ⚙️ **Smart Environment Config** - Default or interactive mode for environment variables
 - 🔌 **Plugin Management** - Browse and install official SimpleNS plugins
+- 🔐 **Optional SSL Setup** - Automatic Let's Encrypt setup with Dockerized Certbot (Windows/macOS/Linux)
 - 🚀 **Service Orchestration** - Automatic health checks and sequential service startup
 - 📊 **Service Dashboard** - View all running services and their access URLs
 
@@ -110,6 +111,9 @@ The CLI will display a security notice with all credentials that need to be upda
 | `--core-version <version>` | Override `CORE_VERSION` in generated `.env` (primarily for `--full`) | `latest` |
 | `--dashboard-version <version>` | Override `DASHBOARD_VERSION` in generated `.env` (primarily for `--full`) | `latest` |
 | `--plugin [plugins...]` | Plugins to install (e.g., `@simplens/mock @simplens/nodemailer-gmail`) | Prompted |
+| `--ssl` | Enable optional SSL automation with Certbot | `false` |
+| `--ssl-domain <domain>` | Public domain for SSL cert (required with `--ssl` in `--full`) | Prompted |
+| `--ssl-email <email>` | Email for Let's Encrypt registration (required with `--ssl` in `--full`) | Prompted |
 | `--no-output` | Suppress all console output (silent mode) | `false` |
 
 ### Valid Infrastructure Services
@@ -118,7 +122,7 @@ The CLI will display a security notice with all credentials that need to be upda
 - `kafka` - Apache Kafka message queue
 - `kafka-ui` - Kafka UI dashboard (optional)
 - `redis` - Redis cache
-- `nginx` - Nginx reverse proxy (optional, Required only is BASE_PATH is configured)
+- `nginx` - Nginx reverse proxy (optional, Required only is BASE_PATH or SSL is configured)
 - `loki` - Loki log aggregation (optional)
 - `grafana` - Grafana observability dashboard (optional)
 
@@ -156,12 +160,18 @@ The CLI will display a security notice with all credentials that need to be upda
    - Start application services
    - Display service URLs and status
 
+6. **Optional SSL Automation** (if enabled)
+   - Auto-enables Nginx if required
+   - Issues cert via Dockerized Certbot (`http-01` webroot challenge)
+   - Configures auto-renew service and Nginx reload
+
 ## Generated Files
 
 - `docker-compose.infra.yaml` - Infrastructure services (if `--infra` used)
 - `docker-compose.yaml` - Application services
 - `.env` - Environment variables and credentials
 - `simplens.config.yaml` - Plugin configuration
+- `nginx.conf` - Generated reverse proxy config (HTTP/HTTPS based on options)
 
 ## Service URLs
 
@@ -243,6 +253,22 @@ cd /app/simplens
 docker-compose up -d
 ```
 
+### Full Setup With SSL Automation
+
+```bash
+npx @simplens/onboard \
+  --full \
+  --infra mongo kafka redis \
+  --env default \
+  --ssl \
+  --ssl-domain app.example.com \
+  --ssl-email ops@example.com
+```
+
+Notes:
+- Your domain DNS must point to the host running onboarding.
+- Ports 80 and 443 must be publicly reachable for Let's Encrypt validation.
+
 ### Silent Mode (No Console Output)
 
 ```bash
diff --git a/packages/onboard/package-lock.json b/packages/onboard/package-lock.json
index ef188fc..2f769c0 100644
--- a/packages/onboard/package-lock.json
+++ b/packages/onboard/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@simplens/onboard",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@simplens/onboard",
-      "version": "1.0.5",
+      "version": "1.0.6",
       "license": "ISC",
       "dependencies": {
         "@clack/prompts": "^1.0.0",
diff --git a/packages/onboard/package.json b/packages/onboard/package.json
index 701dc73..a86b862 100644
--- a/packages/onboard/package.json
+++ b/packages/onboard/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@simplens/onboard",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
diff --git a/packages/onboard/src/__tests__/infra-prompts.test.ts b/packages/onboard/src/__tests__/infra-prompts.test.ts
index 8a7c7ae..e8858d6 100644
--- a/packages/onboard/src/__tests__/infra-prompts.test.ts
+++ b/packages/onboard/src/__tests__/infra-prompts.test.ts
@@ -28,12 +28,14 @@ describe('promptInfraServicesWithBasePath', () => {
         const mockMultiselect = vi.mocked(multiselect);
         mockMultiselect.mockResolvedValue(['mongo', 'redis', 'nginx']);
 
-        const result = await promptInfraServicesWithBasePath({ allowNginx: true });
+        const result = await promptInfraServicesWithBasePath({ allowNginx: true, defaultNginx: true });
 
         // Should include nginx in options
         const callArgs = mockMultiselect.mock.calls[0][0] as any;
         const values = callArgs.options.map((o: any) => o.value);
         expect(values).toContain('nginx');
+        expect(callArgs.initialValues).toContain('nginx');
+        expect(callArgs.initialValues).not.toContain('kafka-ui');
 
         expect(result).toContain('nginx');
     });
diff --git a/packages/onboard/src/__tests__/infra.test.ts b/packages/onboard/src/__tests__/infra.test.ts
index cc19971..74015f7 100644
--- a/packages/onboard/src/__tests__/infra.test.ts
+++ b/packages/onboard/src/__tests__/infra.test.ts
@@ -12,4 +12,19 @@ describe('infra app compose generation', () => {
         expect(compose).toContain('  nginx:');
         expect(compose).toContain('./nginx.conf:/etc/nginx/conf.d/default.conf:ro');
     });
+
+    it('does not include certbot services when ssl is disabled', () => {
+        const compose = buildAppComposeContent(true, { includeSsl: false });
+        expect(compose).not.toContain('  certbot:');
+        expect(compose).not.toContain('  certbot-renew:');
+    });
+
+    it('includes certbot services and volumes when ssl is enabled', () => {
+        const compose = buildAppComposeContent(false, { includeSsl: true });
+        expect(compose).toContain('  nginx:');
+        expect(compose).toContain('  certbot:');
+        expect(compose).toContain('  certbot-renew:');
+        expect(compose).toContain('certbot-etc:');
+        expect(compose).toContain('certbot-www:');
+    });
 });
diff --git a/packages/onboard/src/__tests__/validators.test.ts b/packages/onboard/src/__tests__/validators.test.ts
index f9939b2..ec8a603 100644
--- a/packages/onboard/src/__tests__/validators.test.ts
+++ b/packages/onboard/src/__tests__/validators.test.ts
@@ -4,7 +4,9 @@ import {
     checkDockerRunning,
     detectOS,
     validatePrerequisites,
-    validateEnvValue
+    validateEnvValue,
+    validatePublicDomain,
+    validateEmailAddress
 } from '../validators.js';
 import {
     DockerNotInstalledError,
@@ -192,4 +194,28 @@ describe('validators', () => {
             });
         });
     });
+
+    describe('validatePublicDomain', () => {
+        it('accepts valid public domains', () => {
+            expect(validatePublicDomain('example.com')).toBe(true);
+            expect(validatePublicDomain('app.example.com')).toBe(true);
+        });
+
+        it('rejects urls or malformed values', () => {
+            expect(validatePublicDomain('https://example.com')).not.toBe(true);
+            expect(validatePublicDomain('example')).not.toBe(true);
+            expect(validatePublicDomain('example.com/path')).not.toBe(true);
+        });
+    });
+
+    describe('validateEmailAddress', () => {
+        it('accepts valid email addresses', () => {
+            expect(validateEmailAddress('admin@example.com')).toBe(true);
+        });
+
+        it('rejects invalid email values', () => {
+            expect(validateEmailAddress('admin@')).not.toBe(true);
+            expect(validateEmailAddress('not-an-email')).not.toBe(true);
+        });
+    });
 });
diff --git a/packages/onboard/src/index.ts b/packages/onboard/src/index.ts
index 5aa3464..005ec85 100644
--- a/packages/onboard/src/index.ts
+++ b/packages/onboard/src/index.ts
@@ -15,7 +15,11 @@ import {
 } from './utils.js';
 import { text, confirm, select } from '@clack/prompts';
 import { intro, outro, handleCancel, log, note } from './ui.js';
-import { validatePrerequisites } from './validators.js';
+import {
+    validatePrerequisites,
+    validatePublicDomain,
+    validateEmailAddress,
+} from './validators.js';
 import {
     promptInfraServicesWithBasePath,
     generateInfraCompose,
@@ -45,6 +49,8 @@ import {
     waitForInfraHealth,
     startAppServices,
     displayServiceStatus,
+    setupSslCertificates,
+    getSslManualCommands,
 } from './services.js';
 
 const program = new Command();
@@ -61,6 +67,9 @@ program
     .option('--core-version <version>', 'Override CORE_VERSION in generated .env (primarily for --full mode)')
     .option('--dashboard-version <version>', 'Override DASHBOARD_VERSION in generated .env (primarily for --full mode)')
     .option('--plugin [plugins...]', 'Plugins to install (e.g., @simplens/mock @simplens/nodemailer-gmail)')
+    .option('--ssl', 'Enable optional SSL certificate setup using Dockerized Certbot')
+    .option('--ssl-domain <domain>', 'Public domain for SSL certificate (required with --ssl in --full mode)')
+    .option('--ssl-email <email>', 'Email for Let\'s Encrypt registration (required with --ssl in --full mode)')
     .option('--no-output', 'Suppress all console output (silent mode)');
 
 interface OnboardSetupOptions {
@@ -70,6 +79,9 @@ interface OnboardSetupOptions {
     targetDir: string;
     basePath: string;
     plugins: string[];
+    enableSsl: boolean;
+    sslDomain?: string;
+    sslEmail?: string;
 }
 
 function printStep(step: number, total: number, title: string): void {
@@ -112,6 +124,9 @@ function showSetupSummary(setupOptions: OnboardSetupOptions, targetDir: string,
     const pluginsLabel = setupOptions.plugins.length > 0 
         ? setupOptions.plugins.join(', ') 
         : 'none';
+    const sslLabel = setupOptions.enableSsl
+        ? `enabled (${setupOptions.sslDomain})`
+        : 'disabled';
 
     const summaryLines = [
         `Target directory   : ${targetDir}`,
@@ -119,6 +134,7 @@ function showSetupSummary(setupOptions: OnboardSetupOptions, targetDir: string,
         `Environment mode   : ${setupOptions.envMode}`,
         `BASE_PATH          : ${basePathLabel}`,
         `Plugins            : ${pluginsLabel}`,
+        `SSL (Certbot)      : ${sslLabel}`,
         `Nginx auto-include : ${autoNginx ? 'enabled (BASE_PATH is non-default)' : 'disabled'}`,
     ].join('\n');
 
@@ -170,6 +186,26 @@ async function promptSetupOptions(options: any): Promise<OnboardSetupOptions> {
             }
         }
 
+        if (options.ssl === true) {
+            if (!options.sslDomain) {
+                errors.push('--ssl-domain <domain> is required in --full mode when --ssl is enabled');
+            } else {
+                const domainValidation = validatePublicDomain(options.sslDomain);
+                if (domainValidation !== true) {
+                    errors.push(`Invalid --ssl-domain: ${domainValidation}`);
+                }
+            }
+
+            if (!options.sslEmail) {
+                errors.push('--ssl-email <email> is required in --full mode when --ssl is enabled');
+            } else {
+                const emailValidation = validateEmailAddress(options.sslEmail);
+                if (emailValidation !== true) {
+                    errors.push(`Invalid --ssl-email: ${emailValidation}`);
+                }
+            }
+        }
+
         if (errors.length > 0) {
             console.error('\\n❌ Validation errors in --full mode:\\n');
             errors.forEach(err => console.error(`  • ${err}`));
@@ -274,6 +310,55 @@ async function promptSetupOptions(options: any): Promise<OnboardSetupOptions> {
     }
     // If not provided and not in full mode, will prompt later in the main workflow
 
+    // --- SSL ---
+    let enableSslValue = false;
+    let sslDomainValue: string | undefined;
+    let sslEmailValue: string | undefined;
+
+    if (options.ssl === true) {
+        enableSslValue = true;
+    } else if (!isFullMode) {
+        const sslConfirm = await confirm({
+            message: 'Do you want to automatically setup SSL certificate using Certbot?',
+            initialValue: false,
+            withGuide: true,
+        });
+        handleCancel(sslConfirm);
+        enableSslValue = sslConfirm as boolean;
+    }
+
+    if (enableSslValue) {
+        if (typeof options.sslDomain === 'string') {
+            sslDomainValue = options.sslDomain.trim().toLowerCase();
+        } else if (!isFullMode) {
+            const domainAnswer = await text({
+                message: 'Public domain to secure (example: app.example.com):',
+                validate: (value: string | undefined) => {
+                    const validation = validatePublicDomain(value ?? '');
+                    return validation === true ? undefined : validation;
+                },
+                withGuide: true,
+            });
+            handleCancel(domainAnswer);
+            sslDomainValue = (domainAnswer as string).trim().toLowerCase();
+        }
+
+        if (typeof options.sslEmail === 'string') {
+            sslEmailValue = options.sslEmail.trim();
+        } else if (!isFullMode) {
+            const emailAnswer = await text({
+                message: 'Email for Let\'s Encrypt registration:',
+                validate: (value: string | undefined) => {
+                    const validation = validateEmailAddress(value ?? '');
+                    return validation === true ? undefined : validation;
+                },
+                withGuide: true,
+            });
+            handleCancel(emailAnswer);
+            sslEmailValue = (emailAnswer as string).trim();
+        }
+    }
+
     return {
         infra: infraValue,
         infraServices: infraServices,
@@ -281,6 +366,9 @@ async function promptSetupOptions(options: any): Promise<OnboardSetupOptions> {
         targetDir: targetDirValue || process.cwd(),
         basePath: basePathValue,
         plugins: pluginsValue,
+        enableSsl: enableSslValue,
+        sslDomain: sslDomainValue,
+        sslEmail: sslEmailValue,
     };
 }
 
@@ -318,6 +406,7 @@ async function main() {
         // Get target directory
         const targetDir = path.resolve(setupOptions.targetDir);
         const autoEnableNginx = shouldAutoEnableNginx(setupOptions.basePath);
+        const nginxRequired = autoEnableNginx || setupOptions.enableSsl;
 
         logDebug(`Resolved target directory: ${targetDir}`);
         showSetupSummary(setupOptions, targetDir, autoEnableNginx);
@@ -329,39 +418,50 @@ async function main() {
         // Step 2: Infrastructure setup (if --infra flag is provided)
         log.step('Step 2/6 — Infrastructure Setup');
         let selectedInfraServices: string[] = [];
+        const shouldSetupInfra = setupOptions.infra || nginxRequired;
 
-        if (setupOptions.infra) {
+        if (shouldSetupInfra) {
             // Use pre-provided services from CLI, or prompt for them
-            if (setupOptions.infraServices.length > 0) {
+            if (setupOptions.infra && setupOptions.infraServices.length > 0) {
                 selectedInfraServices = setupOptions.infraServices;
                 log.info(`Using infrastructure services: ${selectedInfraServices.join(', ')}`);
+            } else if (!setupOptions.infra && nginxRequired) {
+                selectedInfraServices = ['nginx'];
+                log.info('Nginx is required (BASE_PATH/SSL), so infrastructure compose will be generated with nginx.');
             } else {
                 // Prompt for services (interactive mode)
                 if (!autoEnableNginx) {
                     log.info('BASE_PATH is empty, nginx reverse proxy is disabled.');
-                    selectedInfraServices = await promptInfraServicesWithBasePath({ allowNginx: false });
+                    selectedInfraServices = await promptInfraServicesWithBasePath({
+                        allowNginx: false,
+                    });
                 } else {
-                    selectedInfraServices = await promptInfraServicesWithBasePath({ allowNginx: true });
+                    selectedInfraServices = await promptInfraServicesWithBasePath({
+                        allowNginx: true,
+                        defaultNginx: true,
+                    });
                 }
             }
 
-            if (autoEnableNginx && !selectedInfraServices.includes('nginx')) {
+            if (setupOptions.enableSsl && !selectedInfraServices.includes('nginx')) {
                 selectedInfraServices.push('nginx');
-                log.info('BASE_PATH is non-default, so nginx was added automatically.');
+                log.info('SSL is enabled, so nginx was added automatically.');
             }
 
-            await generateInfraCompose(targetDir, selectedInfraServices);
+            const infraHasNginx = selectedInfraServices.includes('nginx');
+            await generateInfraCompose(targetDir, selectedInfraServices, {
+                includeSsl: setupOptions.enableSsl && infraHasNginx,
+            });
         } else {
             log.info('Skipping infrastructure setup (use --infra to enable).');
         }
 
         // Step 3: Always write app docker-compose
         log.step('Step 3/6 — Application Compose Setup');
-        const includeNginxInAppCompose = autoEnableNginx && !selectedInfraServices.includes('nginx');
-        if (includeNginxInAppCompose) {
-            log.info('Including nginx in docker-compose.yaml because BASE_PATH is non-default.');
-        }
-        await writeAppCompose(targetDir, { includeNginx: includeNginxInAppCompose });
+        await writeAppCompose(targetDir, {
+            includeNginx: false,
+            includeSsl: false,
+        });
 
         // Step 4: Environment configuration
         log.step('Step 4/6 — Environment Configuration');
@@ -390,9 +490,12 @@ async function main() {
         }
 
         // Generate nginx.conf whenever nginx is active in either compose file
-        const nginxEnabled = selectedInfraServices.includes('nginx') || includeNginxInAppCompose;
+        const nginxEnabled = selectedInfraServices.includes('nginx');
         if (nginxEnabled) {
-            await generateNginxConfig(targetDir, setupOptions.basePath);
+            await generateNginxConfig(targetDir, setupOptions.basePath, {
+                enableSsl: setupOptions.enableSsl,
+                domain: setupOptions.sslDomain,
+            });
         }
 
         // Step 5: Plugin installation
@@ -447,7 +550,7 @@ async function main() {
 
         if (shouldStart) {
             // Start infra services first (if --infra was used)
-            if (setupOptions.infra && selectedInfraServices.length > 0) {
+            if (selectedInfraServices.length > 0) {
                 await startInfraServices(targetDir);
                 await waitForInfraHealth(targetDir);
             }
@@ -455,15 +558,30 @@ async function main() {
             // Start app services
             await startAppServices(targetDir);
 
+            if (setupOptions.enableSsl && setupOptions.sslDomain && setupOptions.sslEmail) {
+                await setupSslCertificates(targetDir, {
+                    composeFile: 'docker-compose.infra.yaml',
+                    domain: setupOptions.sslDomain,
+                    email: setupOptions.sslEmail,
+                });
+            }
+
             // Display service status
             await displayServiceStatus();
         } else {
             log.info('Services not started. You can start them later with:');
             const commands: string[] = [];
-            if (setupOptions.infra) {
+            if (selectedInfraServices.length > 0) {
                 commands.push('docker-compose -f docker-compose.infra.yaml up -d');
             }
             commands.push('docker-compose up -d');
+            if (setupOptions.enableSsl && setupOptions.sslDomain && setupOptions.sslEmail) {
+                commands.push(...getSslManualCommands({
+                    composeFile: 'docker-compose.infra.yaml',
+                    domain: setupOptions.sslDomain,
+                    email: setupOptions.sslEmail,
+                }));
+            }
             printCommandHints('Manual startup commands', commands);
         }
 
diff --git a/packages/onboard/src/infra.ts b/packages/onboard/src/infra.ts
index b761a40..3be27db 100644
--- a/packages/onboard/src/infra.ts
+++ b/packages/onboard/src/infra.ts
@@ -1,4 +1,11 @@
-import { APP_COMPOSE_TEMPLATE, APP_NGINX_SERVICE_TEMPLATE } from './templates.js';
+import {
+    APP_COMPOSE_TEMPLATE,
+    APP_NGINX_SERVICE_TEMPLATE,
+    APP_NGINX_SSL_SERVICE_TEMPLATE,
+    APP_CERTBOT_SERVICES_TEMPLATE,
+    INFRA_CERTBOT_SERVICES_TEMPLATE,
+    INFRA_CERTBOT_VOLUMES,
+} from './templates.js';
 import { writeFile, logInfo, logSuccess } from './utils.js';
 import { multiselect } from '@clack/prompts';
 import { handleCancel, spinner } from './ui.js';
@@ -8,7 +15,7 @@ import type { InfraService } from './types/domain.js';
 const INFRA_SERVICES: InfraService[] = [
     { name: 'MongoDB (Database)', value: 'mongo', checked: true },
     { name: 'Kafka (Message Queue)', value: 'kafka', checked: true },
-    { name: 'Kafka UI (Dashboard)', value: 'kafka-ui', checked: true },
+    { name: 'Kafka UI (Dashboard)', value: 'kafka-ui', checked: false },
     { name: 'Redis (Cache)', value: 'redis', checked: true },
     { name: 'Nginx (Reverse Proxy)', value: 'nginx', checked: false },
     { name: 'Loki (Log Aggregation)', value: 'loki', checked: false },
@@ -31,9 +38,15 @@ export async function promptInfraServices(): Promise<string[]> {
  */
 export async function promptInfraServicesWithBasePath(options: {
     allowNginx: boolean;
+    defaultNginx?: boolean;
 }): Promise<string[]> {
     const choices = options.allowNginx
-        ? INFRA_SERVICES
+        ? INFRA_SERVICES.map(service => {
+            if (service.value === 'nginx') {
+                return { ...service, checked: options.defaultNginx === true };
+            }
+            return service;
+        })
         : INFRA_SERVICES.filter(service => service.value !== 'nginx');
 
     const message = options.allowNginx
@@ -179,6 +192,18 @@ const SERVICE_CHUNKS: Record<string, string> = {
     restart: unless-stopped`,
 };
 
+const NGINX_INFRA_SSL_SERVICE_CHUNK = `  nginx:
+    image: nginx:alpine
+    container_name: nginx
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - "./nginx.conf:/etc/nginx/conf.d/default.conf:ro"
+      - certbot-etc:/etc/letsencrypt
+      - certbot-www:/var/www/certbot
+    restart: unless-stopped`;
+
 /**
  * Service-to-volumes mapping
  */
@@ -195,7 +220,10 @@ const SERVICE_VOLUMES: Record<string, string[]> = {
 /**
  * Build docker-compose content from selected services
  */
-function buildInfraCompose(selectedServices: string[]): string {
+function buildInfraCompose(
+    selectedServices: string[],
+    options: { includeSsl?: boolean } = {}
+): string {
     // Header
     const header = `# ============================================
 # SimpleNS Infrastructure Services
@@ -212,9 +240,17 @@ services:
     const serviceBlocks: string[] = [];
     for (const service of selectedServices) {
         if (SERVICE_CHUNKS[service]) {
-            serviceBlocks.push(SERVICE_CHUNKS[service]);
+            if (service === 'nginx' && options.includeSsl === true) {
+                serviceBlocks.push(NGINX_INFRA_SSL_SERVICE_CHUNK);
+            } else {
+                serviceBlocks.push(SERVICE_CHUNKS[service]);
+            }
         }
     }
+
+    if (options.includeSsl === true) {
+        serviceBlocks.push(INFRA_CERTBOT_SERVICES_TEMPLATE);
+    }
     
     // Collect volumes for selected services
     const volumeSet = new Set<string>();
@@ -222,6 +258,12 @@ services:
         const volumes = SERVICE_VOLUMES[service] || [];
         volumes.forEach(v => volumeSet.add(v));
     }
+
+    if (options.includeSsl === true) {
+        for (const volumeName of INFRA_CERTBOT_VOLUMES) {
+            volumeSet.add(volumeName);
+        }
+    }
     
     // Build volumes section
     const volumeLines: string[] = ['', 'volumes:'];
@@ -248,13 +290,14 @@ services:
  */
 export async function generateInfraCompose(
     targetDir: string,
-    selectedServices: string[]
+    selectedServices: string[],
+    options: { includeSsl?: boolean } = {}
 ): Promise<void> {
     const s = spinner();
     s.start('Generating docker-compose.infra.yaml...');
 
     // Build compose content from service chunks
-    const infraContent = buildInfraCompose(selectedServices);
+    const infraContent = buildInfraCompose(selectedServices, options);
 
     // Write infrastructure compose file
     const infraPath = path.join(targetDir, 'docker-compose.infra.yaml');
@@ -266,17 +309,35 @@ export async function generateInfraCompose(
  * Build app docker-compose content.
  * Optionally inject nginx reverse-proxy service before the volumes section.
  */
-export function buildAppComposeContent(includeNginx: boolean): string {
-    if (!includeNginx) {
-        return APP_COMPOSE_TEMPLATE;
+export function buildAppComposeContent(
+    includeNginx: boolean,
+    options: { includeSsl?: boolean } = {}
+): string {
+    let content = APP_COMPOSE_TEMPLATE;
+    const includeSsl = options.includeSsl === true;
+    const shouldIncludeNginx = includeNginx || includeSsl;
+    const marker = '\nvolumes:';
+
+    if (!content.includes(marker)) {
+        return content;
     }
 
-    const marker = '\nvolumes:';
-    if (!APP_COMPOSE_TEMPLATE.includes(marker)) {
-        return APP_COMPOSE_TEMPLATE;
+    if (shouldIncludeNginx) {
+        const nginxBlock = includeSsl
+            ? APP_NGINX_SSL_SERVICE_TEMPLATE
+            : APP_NGINX_SERVICE_TEMPLATE;
+        content = content.replace(marker, `\n${nginxBlock}\n${marker}`);
+    }
+
+    if (includeSsl) {
+        content = content.replace(marker, `\n${APP_CERTBOT_SERVICES_TEMPLATE}\n${marker}`);
+        content = content.replace(
+            '\nvolumes:\n  plugin-data:',
+            '\nvolumes:\n  certbot-etc:\n  certbot-www:\n  plugin-data:'
+        );
     }
 
-    return APP_COMPOSE_TEMPLATE.replace(marker, `\n${APP_NGINX_SERVICE_TEMPLATE}\n${marker}`);
+    return content;
 }
 
 /**
@@ -284,12 +345,14 @@ export function buildAppComposeContent(includeNginx: boolean): string {
  */
 export async function writeAppCompose(
     targetDir: string,
-    options: { includeNginx?: boolean } = {}
+    options: { includeNginx?: boolean; includeSsl?: boolean } = {}
 ): Promise<void> {
     const s = spinner();
     s.start('Generating docker-compose.yaml...');
     const appPath = path.join(targetDir, 'docker-compose.yaml');
-    const appContent = buildAppComposeContent(options.includeNginx === true);
+    const appContent = buildAppComposeContent(options.includeNginx === true, {
+        includeSsl: options.includeSsl === true,
+    });
     await writeFile(appPath, appContent);
     s.stop('Generated docker-compose.yaml');
 }
@@ -299,7 +362,8 @@ export async function writeAppCompose(
  */
 export async function generateNginxConfig(
     targetDir: string,
-    basePath: string
+    basePath: string,
+    options: { enableSsl?: boolean; domain?: string } = {}
 ): Promise<void> {
     const s = spinner();
     s.start('Generating nginx.conf...');
@@ -307,12 +371,10 @@ export async function generateNginxConfig(
     // Normalize basePath (remove leading/trailing slashes for template)
     const normalizedPath = basePath.trim().replace(/^\/|\/$/g, '');
     const hasBasePath = normalizedPath.length > 0;
+    const enableSsl = options.enableSsl === true;
+    const domain = options.domain?.trim() || 'localhost';
 
-    // Template for nginx.conf
-    const nginxTemplate = `server {
-    listen 80;
-    server_name localhost;
-
+    const proxyRoutes = `
     location /api {
         proxy_pass http://api:3000;
         proxy_http_version 1.1;
@@ -395,10 +457,44 @@ ${hasBasePath ? `
         proxy_set_header X-Forwarded-Proto $scheme;
     }
 `}
+`;
+
+    const nginxTemplate = enableSsl
+        ? `server {
+    listen 80;
+    server_name ${domain};
+
+    location /.well-known/acme-challenge/ {
+        root /var/www/certbot;
+    }
+
+    location / {
+        return 301 https://$host$request_uri;
+    }
+}
+
+server {
+    listen 443 ssl;
+    server_name ${domain};
+
+    ssl_certificate /etc/letsencrypt/live/${domain}/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/${domain}/privkey.pem;
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_prefer_server_ciphers on;
+    location = / {
+        return 302 /dashboard;
+    }
+    ${proxyRoutes}
+}
+`
+        : `server {
+    listen 80;
+    server_name localhost;${proxyRoutes}
 }
 `;
 
     const nginxPath = path.join(targetDir, 'nginx.conf');
     await writeFile(nginxPath, nginxTemplate);
-    s.stop(`Generated nginx.conf${hasBasePath ? ` with base path: /${normalizedPath}` : ' (root path)'}`);
+    const sslLabel = enableSsl ? `, SSL domain: ${domain}` : '';
+    s.stop(`Generated nginx.conf${hasBasePath ? ` with base path: /${normalizedPath}` : ' (root path)'}${sslLabel}`);
 }
diff --git a/packages/onboard/src/services.ts b/packages/onboard/src/services.ts
index f7a1874..2223d6c 100644
--- a/packages/onboard/src/services.ts
+++ b/packages/onboard/src/services.ts
@@ -19,6 +19,15 @@ async function execDockerCompose(args: string[], cwd: string): Promise<void> {
     }
 }
 
+type ComposeFile = 'docker-compose.yaml' | 'docker-compose.infra.yaml';
+
+function withComposeFile(args: string[], composeFile?: ComposeFile): string[] {
+    if (!composeFile) {
+        return args;
+    }
+    return ['-f', composeFile, ...args];
+}
+
 /**
  * Prompts user whether to start the services immediately after setup.
  *
@@ -125,6 +134,69 @@ export async function startAppServices(targetDir: string): Promise<void> {
     }
 }
 
+export function getSslManualCommands(options: {
+    composeFile: ComposeFile;
+    domain: string;
+    email: string;
+}): string[] {
+    const composeFlag = options.composeFile === 'docker-compose.infra.yaml'
+        ? '-f docker-compose.infra.yaml '
+        : '';
+
+    return [
+        `docker compose ${composeFlag}up -d nginx certbot certbot-renew`,
+        `docker compose ${composeFlag}exec -T certbot certbot certonly --webroot -w /var/www/certbot --email ${options.email} --agree-tos --no-eff-email -d ${options.domain} --non-interactive`,
+        `docker compose ${composeFlag}exec -T nginx nginx -s reload`,
+        `docker compose ${composeFlag}up -d certbot-renew`,
+    ];
+}
+
+export async function setupSslCertificates(targetDir: string, options: {
+    composeFile: ComposeFile;
+    domain: string;
+    email: string;
+}): Promise<void> {
+    logInfo(`Setting up SSL certificate for ${options.domain}...`);
+
+    const s = spinner();
+    const composeArgs = (args: string[]) => withComposeFile(args, options.composeFile);
+
+    s.start('Ensuring nginx/certbot services are running...');
+    await execDockerCompose(composeArgs(['up', '-d', 'nginx', 'certbot']), targetDir);
+    s.stop('Nginx and certbot services are running');
+
+    s.start('Requesting initial certificate from Let\'s Encrypt...');
+    await execDockerCompose(
+        composeArgs([
+            'exec',
+            '-T',
+            'certbot',
+            'certbot',
+            'certonly',
+            '--webroot',
+            '-w',
+            '/var/www/certbot',
+            '--email',
+            options.email,
+            '--agree-tos',
+            '--no-eff-email',
+            '-d',
+            options.domain,
+            '--non-interactive',
+        ]),
+        targetDir
+    );
+    s.stop('Initial certificate issued');
+
+    s.start('Reloading nginx to apply certificates...');
+    await execDockerCompose(composeArgs(['exec', '-T', 'nginx', 'nginx', '-s', 'reload']), targetDir);
+    s.stop('Nginx reloaded');
+
+    s.start('Starting automatic certificate renewal service...');
+    await execDockerCompose(composeArgs(['up', '-d', 'certbot-renew']), targetDir);
+    s.stop('Certificate auto-renewal service started');
+}
+
 /**
  * Display service status and URLs
  */
diff --git a/packages/onboard/src/templates.ts b/packages/onboard/src/templates.ts
index d64bc69..f844077 100644
--- a/packages/onboard/src/templates.ts
+++ b/packages/onboard/src/templates.ts
@@ -219,3 +219,60 @@ export const APP_NGINX_SERVICE_TEMPLATE = `  nginx:
       - api
       - dashboard
     restart: unless-stopped`;
+
+export const APP_NGINX_SSL_SERVICE_TEMPLATE = `  nginx:
+    image: nginx:alpine
+    container_name: nginx
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - "./nginx.conf:/etc/nginx/conf.d/default.conf:ro"
+      - certbot-etc:/etc/letsencrypt
+      - certbot-www:/var/www/certbot
+    depends_on:
+      - api
+      - dashboard
+    restart: unless-stopped`;
+
+export const APP_CERTBOT_SERVICES_TEMPLATE = `  certbot:
+    image: certbot/certbot:latest
+    container_name: certbot
+    volumes:
+      - certbot-etc:/etc/letsencrypt
+      - certbot-www:/var/www/certbot
+    command: sh -c "trap exit TERM; while :; do sleep 86400; done"
+    restart: unless-stopped
+
+  certbot-renew:
+    image: docker:cli
+    container_name: certbot-renew
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+    depends_on:
+      - certbot
+      - nginx
+    command: sh -c "while :; do sleep 12h; docker exec certbot certbot renew --webroot -w /var/www/certbot --quiet && docker exec nginx nginx -s reload || true; done"
+    restart: unless-stopped`;
+
+export const INFRA_CERTBOT_SERVICES_TEMPLATE = `  certbot:
+    image: certbot/certbot:latest
+    container_name: certbot
+    volumes:
+      - certbot-etc:/etc/letsencrypt
+      - certbot-www:/var/www/certbot
+    command: sh -c "trap exit TERM; while :; do sleep 86400; done"
+    restart: unless-stopped
+
+  certbot-renew:
+    image: docker:cli
+    container_name: certbot-renew
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+    depends_on:
+      - certbot
+      - nginx
+    command: sh -c "while :; do sleep 12h; docker exec certbot certbot renew --webroot -w /var/www/certbot --quiet && docker exec nginx nginx -s reload || true; done"
+    restart: unless-stopped`;
+
+export const INFRA_CERTBOT_VOLUMES = ['certbot-etc', 'certbot-www'] as const;
diff --git a/packages/onboard/src/types/domain.ts b/packages/onboard/src/types/domain.ts
index eb3bd95..3d45411 100644
--- a/packages/onboard/src/types/domain.ts
+++ b/packages/onboard/src/types/domain.ts
@@ -52,6 +52,12 @@ export interface SetupOptions {
     targetDir: string;
     /** Dashboard base path (empty string means root) */
     basePath: string;
+    /** Whether SSL automation with Certbot is enabled */
+    enableSsl?: boolean;
+    /** Public domain for SSL certificate */
+    sslDomain?: string;
+    /** Registration email for Let's Encrypt */
+    sslEmail?: string;
 }
 
 /**
diff --git a/packages/onboard/src/validators.ts b/packages/onboard/src/validators.ts
index 0ae05ac..5ce225f 100644
--- a/packages/onboard/src/validators.ts
+++ b/packages/onboard/src/validators.ts
@@ -10,6 +10,57 @@ import { VALIDATION } from './config/constants.js';
 
 export type OSType = 'windows' | 'linux' | 'darwin';
 
+/**
+ * Validate a public domain used for ACME/Certbot.
+ * Accepts FQDN only (no protocol, path, query, port, or wildcard).
+ */
+export function validatePublicDomain(input: string): true | string {
+    const value = input.trim().toLowerCase();
+
+    if (!value) {
+        return 'Domain is required';
+    }
+
+    if (
+        value.includes('://') ||
+        value.includes('/') ||
+        value.includes('?') ||
+        value.includes('#') ||
+        value.includes(':') ||
+        value.includes('*')
+    ) {
+        return 'Enter only a domain name (example: app.example.com)';
+    }
+
+    // RFC-ish practical FQDN validation
+    const domainRegex =
+        /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+
+    if (!domainRegex.test(value)) {
+        return 'Invalid domain format (example: app.example.com)';
+    }
+
+    return true;
+}
+
+/**
+ * Validate email format for Let's Encrypt registration.
+ */
+export function validateEmailAddress(input: string): true | string {
+    const value = input.trim();
+
+    if (!value) {
+        return 'Email is required';
+    }
+
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    if (!emailRegex.test(value)) {
+        return 'Invalid email format (example: admin@example.com)';
+    }
+
+    return true;
+}
+
 /**
  * Checks if Docker is installed on the system by running `docker --version`.
  *