BACKLOG: mark DC-006 done, document DC-005 latent path bug

DC-006 marked done with 25-test result summary + 904/904 test note.
DC-005 annotated with two critical notes:
  - Latent require-path bug in depth-2 routes (mechanical 3->2 fix needed in ~22 files)
  - Branch state vs origin/main divergence (need coordinated merge, not silent FF)

BACKLOG.md

@@ -0,0 +1,90 @@
+# DashCaddy Improvement Backlog
+
+> **Shared coordination file for Hermes & Krystie.**
+> Both bots read this, claim tasks, and update status. Git is the source of truth.
+> When claiming: change `status: todo` to `status: in-progress` and set `owner`.
+> When done: change to `status: done` and add brief result.
+
+---
+
+## P0 — Must Fix (blocks public release)
+
+### DC-001: Fix 4 failing tests in services.routes.test.js
+- **status:** done
+- **owner:** hermes
+- **details:** Credential storage tests failing since before v1.13.4. Run `cd dashcaddy-api && npx jest __tests__/routes/services.routes.test.js` to see failures. Fix the root cause, not the test.
+- **result:** Root cause: routes used `/:serviceId/credentials` (missing `/services/` segment). All 3 credential routes (POST/DELETE/GET) in `routes/services.js` had the wrong path. Fixed to `/services/:serviceId/credentials` — matches the URL pattern used by the live frontend and all 759 tests pass.
+
+### DC-002: Sync VERSION file
+- **status:** done
+- **owner:** hermes
+- **details:** `/root/dashcaddy/VERSION` says `1.13.0` but `package.json` says `1.13.4`. VERSION file should always match package.json. Add a pre-commit or post-version bump hook to keep them in sync.
+- **result:** Fixed root VERSION to 1.13.4. Updated `scripts/release.sh` to write both `dashcaddy-api/package.json` AND root `VERSION` on every release — also stages VERSION in the release commit. No more drift.
+
+### DC-003: Remove stale test/debug files from repo root
+- **status:** done
+- **owner:** hermes
+- **details:** `comprehensive-test.js` and `test-security-fixes.js` are ad-hoc test scripts, not Jest tests. They clutter the repo root. Remove them or convert to proper Jest tests under `__tests__/`.
+- **result:** Moved both files to `dashcaddy-api/scripts/legacy/` (preserved, not deleted — they are 875 lines of security test coverage that may be useful as a manual smoke test). Zero references to them in code/docs — safe to move. All 759 Jest tests still pass.
+
+---
+
+## P1 — Code Quality
+
+### DC-004: Fix 19 ESLint warnings
+- **status:** in-progress
+- **owner:** hermes
+- **details:** Run `cd dashcaddy-api && npx eslint src/ --format compact`. Most are unused vars and nested ternaries in `src/utils/logging.js`. Fix all, target zero warnings.
+
+### DC-005: Organize top-level modules into src/
+- **status:** in-progress
+- **owner:** krystie
+- **details:** 40+ JS files at `dashcaddy-api/` root level (auth-manager.js, credential-manager.js, etc.). Move into organized subdirs under `src/` (e.g., `src/managers/`, `src/security/`, `src/docker/`). Update all require() paths. This is a big refactor — run tests after.
+- **latent bug (discovered during DC-006, NOT yet fixed):** The DC-005 refactor's path-rewrite script left depth-2 route files (`routes/auth/*.js`, `routes/recipes/*.js`, `routes/apps/*.js`, `routes/arr/*.js`, `routes/config/*.js`) with `'../../../src/...'` — **3 levels up instead of 2**, which goes above `dashcaddy-api/` entirely. Required path should be `'../../src/...'` for depth-2 routes. Tests didn't catch this because no test previously imported any depth-2 route (only depth-1 routes like `routes/services.js` were tested). Confirmed-broken imports (with file → offending line): `routes/auth/totp.js:2` (FIXED in DC-006 commit), `routes/auth/keys.js:2`, `routes/auth/sso-gate.js:2-3`, `routes/auth/session-handlers.js:2-3`, `routes/recipes/manage.js:2-3`, `routes/recipes/deploy.js:2-3`, `routes/recipes/index.js:2-3`, `routes/config/assets.js:2-4`, `routes/config/settings.js:2-4`, `routes/config/backup.js:2-4`, `routes/apps/restore.js:2`, `routes/apps/compose.js:2-3`, `routes/apps/deploy.js:2-5`, `routes/apps/helpers.js:2-3`, `routes/apps/templates.js:2-3`, `routes/apps/removal.js:2-3`, `routes/arr/detect.js:2`, `routes/arr/smart-connect.js:2`, `routes/arr/credentials.js:2-3`, `routes/arr/helpers.js:2`, `routes/arr/config.js:2-5`, `routes/arr/plex.js:2`. The fix is mechanical (3 → 2 levels) but touches ~22 files — should be its own PR/commit for clean review.
+- **branch state:** Work is complete on `krystie-improvements` (HEAD `7bc2a20`) with 879/879 tests passing on the branch. **NOT YET ON MAIN** — `origin/main` has since moved past the refactor with ~28 newer commits (DC-008/009/010/011, TOTP 4-part recovery, monitoring widget, unified logger, response-shape standardization). `git diff origin/main..HEAD` is 187 files / 10823 insertions / 3187 deletions — large enough to need careful coordination, not silent fast-forward. See Discord/Sami for proposed merge plan.
+
+### DC-006: Add integration test for TOTP auth flow
+- **status:** done
+- **owner:** krystie
+- **details:** End-to-end test: no token → 401, wrong token → 403, valid TOTP → session token → authenticated request succeeds. Cover the full `/api/auth/check` → session → endpoint flow.
+- **result:** Added `dashcaddy-api/__tests__/routes/auth.totp.routes.test.js` — 25 tests, all passing. Covers: GET `/api/totp/config`, POST `/api/totp/setup` (generate + normalize + reject invalid Base32), POST `/api/totp/verify-setup` (missing/bad/no-pending/valid-code paths), POST `/api/totp/verify` (login — 400/400/401/200), GET `/api/totp/check-session` (passthrough when disabled + 401 no-session + 200 valid-session — the BACKLOG "no token → 401 / authenticated request succeeds" pair), POST `/api/totp/disable` (400/401/200), POST `/api/totp/config` (valid/invalid/never-disables), plus the full end-to-end flow setup→login→check-session→disable and an otplib-not-stubbed sanity check. Uses real `otplib` for code generation (real TOTP math), mocks `credentialManager`/`session`/`totpConfig`/`saveTotpConfig` only. Full suite: 904/904 pass (879 baseline + 25 new). ESLint clean for the new file.
+- **side-effect (DC-005 latent bug fix):** While writing the test I discovered `routes/auth/totp.js` had broken require paths from the DC-005 refactor (`'../../../src/utilities/errors'` was 3 levels up from `routes/auth/` — wrong by 1). The test couldn't even load the route without this fix. Fixed in this commit (`'../../src/utilities/errors'` and `'../../src/utils/responses'`). **Same depth bug exists in other depth-2 route files — see DC-005 note below.**
+
+### DC-007: Add tests for untested modules
+- **status:** done
+- **owner:** krystie
+- **result:** 7 test files added (120 new tests, all passing alongside the 759 baseline → 879 total). Files: `__tests__/dns-propagation.test.js` (9), `__tests__/notification-manager.test.js` (18), `__tests__/ssl-monitor.test.js` (13), `__tests__/log-digest.test.js` (11), `__tests__/metrics.test.js` (21), `__tests__/config-drift-detector.test.js` (19), `__tests__/auto-restart-manager.test.js` (29).
+- **details:** These modules have NO test coverage: `dns-propagation.js`, `notification-manager.js`, `ssl-monitor.js`, `log-digest.js`, `metrics.js`, `config-drift-detector.js`, `auto-restart-manager.js`. Add at least basic smoke tests for each.
+
+---
+
+## P2 — Polish & DX
+
+### DC-008: Update CLAUDE.md for cross-platform accuracy
+- **status:** todo
+- **owner:** 
+- **details:** CLAUDE.md references Windows-specific paths (C:/caddy/, e:/CaddyCerts/) as if they're universal. DashCaddy runs on Linux (Docker on DNS2) and Windows (SAMI-PC). Document both deployment targets clearly.
+
+### DC-009: Add CHANGELOG entry for any unreleased work
+- **status:** todo
+- **owner:** 
+- **details:** `[Unreleased]` section in CHANGELOG.md is empty. Any fixes done should be documented there before tagging a release.
+
+### DC-010: Standardize error response shapes
+- **status:** todo
+- **owner:** 
+- **details:** v1.13.4 standardized route responses to use helpers, but some modules still use raw `res.json()`. Grep for remaining `res.json(` in route handlers and convert to response helpers.
+
+---
+
+## Coordination Rules
+
+1. **Always `git pull` before starting work.**
+2. **Claim a task by editing BACKLOG.md:** set `status: in-progress` and `owner: hermes` or `owner: krystie`.
+3. **Commit BACKLOG.md claim first**, then start coding.
+4. **Run tests before pushing:** `cd dashcaddy-api && npx jest --passWithNoTests`
+5. **Push to `main`** — use `http://sami7777:<token>@100.98.123.59:3000/sami7777/dashcaddy.git`
+6. **Update BACKLOG.md** when done: set `status: done`, add brief result under the task.
+7. **Never work on a task another bot has claimed** (status: in-progress).
+8. **Quality bar:** this is a public-release product. No hacks, no env-var workarounds, no per-machine patches. Fixes go in the shared codebase.
+9. **VERSION bump:** when a batch of tasks is done, bump patch version in package.json + VERSION file, update CHANGELOG, tag.

CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.13.4] - 2026-06-12
+
+### Changed
+- Standardized all route handler responses to use helpers from `src/utils/responses.js`
+  (`ok`, `errorResponse`, `successMessage`, `notFound`, `validationError`, `forbidden`,
+  `unauthorized`, `conflict`). ~160 raw `res.json()` calls converted across 32+ files.
+  No behavior changes — response shapes are identical. This ensures future schema
+  changes (e.g., adding a `requestId` envelope) only need to update one module.
+- Fixed `error` vs `errorResponse` signature mismatch in `routes/health.js` CA cert
+  endpoint. The `error` helper takes `(res, message, statusCode)` while `errorResponse`
+  takes `(res, statusCode, message, extras)` — the wrong alias was being used for
+  calls that needed the 4-argument form.
+- Updated `middleware.js`, `csrf-protection.js`, `error-handler.js`, and
+  `license-manager.js` to use response helpers for rejection/error responses
+  instead of inline `res.status().json()`.
+
+### Note
+- 4 pre-existing test failures in `services.routes.test.js` (credential storage)
+  remain from before this release. They are unrelated to the standardization pass.
+
 ## [1.5.0] - 2026-05-17
 
 ### Changed (BREAKING)

VERSION

@@ -1 +1 @@
-1.13.0
+1.13.4

dashcaddy-api/VERSION

@@ -1 +1 @@
-1.13.0
+1.13.4

dashcaddy-api/__tests__/app-templates.test.js

@@ -1,4 +1,4 @@
-const { APP_TEMPLATES, TEMPLATE_CATEGORIES, DIFFICULTY_LEVELS } = require('../app-templates');
+const { APP_TEMPLATES, TEMPLATE_CATEGORIES, DIFFICULTY_LEVELS } = require('../src/docker/app-templates');
 
 describe('App Templates', () => {
   const templates = Object.values(APP_TEMPLATES);

dashcaddy-api/__tests__/auth-manager.test.js

@@ -1,11 +1,11 @@
 // Must mock crypto-utils BEFORE auth-manager is required,
 // because auth-manager.js line 13: const JWT_SECRET = cryptoUtils.loadOrCreateKey()
 const mockFixedKey = Buffer.alloc(32, 'jwt-test-key-pad');
-jest.mock('../crypto-utils', () => ({
+jest.mock('../src/security/crypto-utils', () => ({
   loadOrCreateKey: jest.fn(() => mockFixedKey),
 }));
 
-jest.mock('../credential-manager', () => ({
+jest.mock('../src/managers/credential-manager', () => ({
   store: jest.fn().mockResolvedValue(true),
   retrieve: jest.fn().mockResolvedValue(null),
   delete: jest.fn().mockResolvedValue(true),
@@ -13,8 +13,8 @@ jest.mock('../credential-manager', () => ({
 }));
 
 const crypto = require('crypto');
-const authManager = require('../auth-manager');
-const credentialManager = require('../credential-manager');
+const authManager = require('../src/managers/auth-manager');
+const credentialManager = require('../src/managers/credential-manager');
 
 describe('AuthManager', () => {
   beforeEach(() => {

dashcaddy-api/__tests__/auto-restart-manager.test.js

@@ -0,0 +1,367 @@
+/**
+ * Smoke tests for auto-restart-manager.js
+ * Verifies the AutoRestartManager class:
+ *   - Policy CRUD (set/get/list/remove)
+ *   - handleContainerDown: cooldown, max-retries, restart attempt, failure
+ *   - handleContainerUp: retry counter reset
+ *   - _handleStatusCheck: healthy→unhealthy and unhealthy→healthy transitions
+ *   - _resolveContainerId: lookup precedence
+ */
+
+const EventEmitter = require('events');
+const { AutoRestartManager, DEFAULT_POLICY } = require('../src/managers/auto-restart-manager');
+
+jest.mock('../src/utilities/fs-helpers', () => ({
+  readJsonFile: jest.fn().mockResolvedValue({}),
+  writeJsonFile: jest.fn().mockResolvedValue(undefined),
+}));
+
+const fsHelpers = require('../src/utilities/fs-helpers');
+
+function makeManager(overrides = {}) {
+  const servicesStateManager = {
+    read: jest.fn().mockResolvedValue([]),
+    ...(overrides.servicesStateManager || {}),
+  };
+
+  const docker = {
+    client: {
+      getContainer: jest.fn(),
+      ...(overrides.dockerClient || {}),
+    },
+  };
+
+  const healthChecker = new EventEmitter();
+  if (overrides.healthChecker) {
+    Object.assign(healthChecker, overrides.healthChecker);
+  }
+
+  const notification = {
+    send: jest.fn().mockResolvedValue({ success: true }),
+    ...(overrides.notification || {}),
+  };
+
+  const ctx = {
+    docker,
+    healthChecker,
+    notification,
+    servicesStateManager,
+    SERVICES_FILE: '/tmp/dc-test/services.json',
+    log: { info: jest.fn(), error: jest.fn(), warn: jest.fn(), debug: jest.fn() },
+    logError: jest.fn(),
+  };
+
+  const manager = new AutoRestartManager(ctx);
+  return { manager, ctx, docker, healthChecker, notification, servicesStateManager };
+}
+
+describe('AutoRestartManager', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    fsHelpers.readJsonFile.mockResolvedValue({});
+    fsHelpers.writeJsonFile.mockResolvedValue(undefined);
+  });
+
+  describe('constants & construction', () => {
+    test('DEFAULT_POLICY has the documented fields and sensible defaults', () => {
+      expect(DEFAULT_POLICY).toEqual({
+        enabled: true,
+        maxRetries: 3,
+        retryIntervalMs: 5000,
+        windowMinutes: 10,
+        currentRetries: 0,
+        lastRestartAt: null,
+        cooldownUntil: null,
+      });
+    });
+
+    test('manager extends EventEmitter and stores ctx deps', () => {
+      const { manager, ctx } = makeManager();
+      expect(manager).toBeInstanceOf(EventEmitter);
+      expect(manager.docker).toBe(ctx.docker);
+      expect(manager.healthChecker).toBe(ctx.healthChecker);
+      expect(manager.notification).toBe(ctx.notification);
+      expect(manager.policies).toBeInstanceOf(Map);
+    });
+  });
+
+  describe('lifecycle', () => {
+    test('start() loads persisted policies from fs-helpers', async () => {
+      fsHelpers.readJsonFile.mockResolvedValue({
+        'svc-1': { enabled: false, maxRetries: 7 },
+      });
+      const { manager } = makeManager();
+      await manager.start();
+      expect(manager.policies.has('svc-1')).toBe(true);
+      const policy = manager.getPolicy('svc-1');
+      expect(policy.maxRetries).toBe(7);
+      expect(policy.enabled).toBe(false);
+    });
+
+    test('start() is idempotent (second call does nothing new)', async () => {
+      const { manager, healthChecker } = makeManager();
+      await manager.start();
+      const listenerCount = healthChecker.listenerCount('status-check');
+      await manager.start();
+      expect(healthChecker.listenerCount('status-check')).toBe(listenerCount);
+    });
+
+    test('stop() removes the status-check listener', async () => {
+      const { manager, healthChecker } = makeManager();
+      await manager.start();
+      expect(healthChecker.listenerCount('status-check')).toBe(1);
+      manager.stop();
+      expect(healthChecker.listenerCount('status-check')).toBe(0);
+    });
+  });
+
+  describe('policy CRUD', () => {
+    test('setPolicy throws on missing serviceId', async () => {
+      const { manager } = makeManager();
+      await expect(manager.setPolicy('', { enabled: true })).rejects.toThrow(/serviceId/);
+      await expect(manager.setPolicy(null, {})).rejects.toThrow(/serviceId/);
+    });
+
+    test('setPolicy merges fields with existing policy', async () => {
+      const { manager } = makeManager();
+      await manager.setPolicy('svc-1', { maxRetries: 5 });
+      await manager.setPolicy('svc-1', { enabled: false });
+      const policy = manager.getPolicy('svc-1');
+      expect(policy.maxRetries).toBe(5); // preserved from earlier
+      expect(policy.enabled).toBe(false); // updated by second call
+    });
+
+    test('setPolicy persists via fs-helpers.writeJsonFile', async () => {
+      const { manager } = makeManager();
+      await manager.setPolicy('svc-1', { maxRetries: 4 });
+      expect(fsHelpers.writeJsonFile).toHaveBeenCalled();
+      const [filePath, payload] = fsHelpers.writeJsonFile.mock.calls[0];
+      expect(filePath).toMatch(/auto-restart-policies\.json$/);
+      expect(payload['svc-1'].maxRetries).toBe(4);
+    });
+
+    test('getPolicy returns a copy, not the internal reference', async () => {
+      const { manager } = makeManager();
+      await manager.setPolicy('svc-1', { maxRetries: 2 });
+      const a = manager.getPolicy('svc-1');
+      a.maxRetries = 999;
+      const b = manager.getPolicy('svc-1');
+      expect(b.maxRetries).toBe(2);
+    });
+
+    test('getPolicy returns null for unknown service', () => {
+      const { manager } = makeManager();
+      expect(manager.getPolicy('does-not-exist')).toBeNull();
+    });
+
+    test('listPolicies returns array of all policies', async () => {
+      const { manager } = makeManager();
+      await manager.setPolicy('svc-1', { maxRetries: 1 });
+      await manager.setPolicy('svc-2', { maxRetries: 2 });
+      const list = manager.listPolicies();
+      expect(Array.isArray(list)).toBe(true);
+      expect(list).toHaveLength(2);
+      const ids = list.map(p => p.serviceId);
+      expect(ids).toEqual(expect.arrayContaining(['svc-1', 'svc-2']));
+    });
+
+    test('removePolicy returns true and deletes the policy', async () => {
+      const { manager } = makeManager();
+      await manager.setPolicy('svc-1', { maxRetries: 1 });
+      expect(await manager.removePolicy('svc-1')).toBe(true);
+      expect(manager.getPolicy('svc-1')).toBeNull();
+    });
+
+    test('removePolicy returns false for unknown service', async () => {
+      const { manager } = makeManager();
+      expect(await manager.removePolicy('does-not-exist')).toBe(false);
+    });
+  });
+
+  describe('handleContainerDown', () => {
+    test('returns ignored/no-policy when no policy exists', async () => {
+      const { manager } = makeManager();
+      const result = await manager.handleContainerDown('unknown', 'cid');
+      expect(result.action).toBe('ignored');
+      expect(result.reason).toBe('no-policy');
+    });
+
+    test('returns ignored/disabled when policy.enabled is false', async () => {
+      const { manager } = makeManager();
+      await manager.setPolicy('svc-1', { enabled: false });
+      const result = await manager.handleContainerDown('svc-1', 'cid');
+      expect(result.action).toBe('ignored');
+      expect(result.reason).toBe('disabled');
+    });
+
+    test('returns skipped/cooldown when cooldownUntil is in the future', async () => {
+      const { manager } = makeManager();
+      // setPolicy() intentionally guards runtime fields; we have to set
+      // cooldownUntil via the internal map to simulate an in-progress cooldown
+      await manager.setPolicy('svc-1', { maxRetries: 3 });
+      manager.policies.get('svc-1').cooldownUntil = Date.now() + 60_000;
+      const result = await manager.handleContainerDown('svc-1', 'cid');
+      expect(result.action).toBe('skipped');
+      expect(result.reason).toBe('cooldown');
+    });
+
+    test('increments currentRetries and calls docker.start on a successful restart', async () => {
+      const { manager, docker } = makeManager();
+      docker.client.getContainer.mockReturnValue({
+        start: jest.fn().mockResolvedValue(undefined),
+      });
+      await manager.setPolicy('svc-1', { maxRetries: 3, retryIntervalMs: 0 });
+
+      const onAttempt = jest.fn();
+      const onSuccess = jest.fn();
+      manager.on('auto-restart-attempt', onAttempt);
+      manager.on('auto-restart-success', onSuccess);
+
+      const result = await manager.handleContainerDown('svc-1', 'cid-abc');
+      expect(result.action).toBe('restarted');
+      expect(result.attempt).toBe(1);
+      expect(result.serviceId).toBe('svc-1');
+      expect(docker.client.getContainer).toHaveBeenCalledWith('cid-abc');
+      expect(onAttempt).toHaveBeenCalledTimes(1);
+      expect(onSuccess).toHaveBeenCalledTimes(1);
+      expect(manager.getPolicy('svc-1').currentRetries).toBe(1);
+    });
+
+    test('emits auto-restart-failed and increments currentRetries when docker.start throws', async () => {
+      const { manager, docker } = makeManager();
+      docker.client.getContainer.mockReturnValue({
+        start: jest.fn().mockRejectedValue(new Error('docker daemon down')),
+      });
+      await manager.setPolicy('svc-1', { maxRetries: 3, retryIntervalMs: 0 });
+
+      const onFailed = jest.fn();
+      manager.on('auto-restart-failed', onFailed);
+
+      const result = await manager.handleContainerDown('svc-1', 'cid-abc');
+      expect(result.action).toBe('failed');
+      expect(result.error).toMatch(/docker daemon down/);
+      expect(onFailed).toHaveBeenCalledTimes(1);
+      expect(manager.getPolicy('svc-1').currentRetries).toBe(1);
+    });
+
+    test('emits auto-restart-max-reached and sets cooldown when maxRetries exceeded', async () => {
+      const { manager, docker } = makeManager();
+      docker.client.getContainer.mockReturnValue({
+        start: jest.fn().mockResolvedValue(undefined),
+      });
+      await manager.setPolicy('svc-1', { maxRetries: 2, retryIntervalMs: 0 });
+
+      const onMax = jest.fn();
+      manager.on('auto-restart-max-reached', onMax);
+
+      // First attempt: currentRetries=0 -> succeeds, increments to 1
+      await manager.handleContainerDown('svc-1', 'cid');
+      // Second: 1 -> succeeds, increments to 2
+      await manager.handleContainerDown('svc-1', 'cid');
+      // Third: 2 >= maxRetries(2) -> max-reached, currentRetries reset to 0
+      const result = await manager.handleContainerDown('svc-1', 'cid');
+
+      expect(result.action).toBe('max-reached');
+      expect(onMax).toHaveBeenCalledTimes(1);
+      const policy = manager.getPolicy('svc-1');
+      expect(policy.currentRetries).toBe(0);
+      expect(policy.cooldownUntil).toBeGreaterThan(Date.now());
+    });
+  });
+
+  describe('handleContainerUp', () => {
+    test('resets currentRetries and cooldownUntil when service is tracked', async () => {
+      const { manager } = makeManager();
+      await manager.setPolicy('svc-1', { currentRetries: 2, cooldownUntil: Date.now() + 10000 });
+      // Mutate via internal map (bypassing the setter guard)
+      manager.policies.get('svc-1').currentRetries = 2;
+      manager.policies.get('svc-1').cooldownUntil = Date.now() + 10000;
+
+      await manager.handleContainerUp('svc-1');
+      const policy = manager.getPolicy('svc-1');
+      expect(policy.currentRetries).toBe(0);
+      expect(policy.cooldownUntil).toBeNull();
+    });
+
+    test('is a no-op when service is not tracked', async () => {
+      const { manager } = makeManager();
+      await expect(manager.handleContainerUp('unknown')).resolves.toBeUndefined();
+    });
+  });
+
+  describe('_handleStatusCheck', () => {
+    test('triggers handleContainerDown on healthy→unhealthy transition', async () => {
+      const { manager, docker } = makeManager();
+      docker.client.getContainer.mockReturnValue({
+        start: jest.fn().mockResolvedValue(undefined),
+      });
+      await manager.setPolicy('svc-1', { maxRetries: 3, retryIntervalMs: 0 });
+      // Pre-set previous health
+      manager._previousHealth.set('svc-1', 'up');
+
+      const handleDownSpy = jest.spyOn(manager, 'handleContainerDown');
+      await manager._handleStatusCheck({
+        serviceId: 'svc-1',
+        status: 'down',
+        details: { containerId: 'cid-1' },
+      });
+      expect(handleDownSpy).toHaveBeenCalledWith('svc-1', 'cid-1');
+    });
+
+    test('triggers handleContainerUp on unhealthy→healthy transition', async () => {
+      const { manager } = makeManager();
+      await manager.setPolicy('svc-1', { maxRetries: 3, retryIntervalMs: 0 });
+      manager._previousHealth.set('svc-1', 'down');
+
+      const handleUpSpy = jest.spyOn(manager, 'handleContainerUp');
+      await manager._handleStatusCheck({ serviceId: 'svc-1', status: 'up' });
+      expect(handleUpSpy).toHaveBeenCalledWith('svc-1');
+    });
+
+    test('does nothing for services without a policy', async () => {
+      const { manager } = makeManager();
+      const handleDownSpy = jest.spyOn(manager, 'handleContainerDown');
+      const handleUpSpy = jest.spyOn(manager, 'handleContainerUp');
+      await manager._handleStatusCheck({ serviceId: 'untracked', status: 'down' });
+      expect(handleDownSpy).not.toHaveBeenCalled();
+      expect(handleUpSpy).not.toHaveBeenCalled();
+    });
+
+    test('ignores status with no serviceId', async () => {
+      const { manager } = makeManager();
+      const handleDownSpy = jest.spyOn(manager, 'handleContainerDown');
+      await manager._handleStatusCheck({ status: 'down' });
+      expect(handleDownSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('_resolveContainerId', () => {
+    test('returns containerId from status.details when present', () => {
+      const { manager } = makeManager();
+      const cid = manager._resolveContainerId('svc-1', { details: { containerId: 'cid-details' } });
+      expect(cid).toBe('cid-details');
+    });
+
+    test('falls back to healthChecker.config.services[serviceId].containerId', () => {
+      const { manager, healthChecker } = makeManager();
+      healthChecker.config = { services: { 'svc-1': { containerId: 'cid-hc' } } };
+      const cid = manager._resolveContainerId('svc-1', { details: {} });
+      expect(cid).toBe('cid-hc');
+    });
+
+    test('falls back to servicesStateManager.read when sync list is returned', () => {
+      const { manager, servicesStateManager } = makeManager();
+      servicesStateManager.read.mockReturnValue([
+        { id: 'svc-1', containerId: 'cid-state' },
+      ]);
+      const cid = manager._resolveContainerId('svc-1', { details: {} });
+      expect(cid).toBe('cid-state');
+    });
+
+    test('returns null when no source has a containerId', () => {
+      const { manager } = makeManager();
+      const cid = manager._resolveContainerId('svc-unknown', { details: {} });
+      expect(cid).toBeNull();
+    });
+  });
+});

dashcaddy-api/__tests__/backup-manager.test.js

@@ -3,19 +3,19 @@
 
 jest.mock('fs');
 jest.mock('child_process');
-jest.mock('../credential-manager', () => ({
+jest.mock('../src/managers/credential-manager', () => ({
   exportBackup: jest.fn().mockReturnValue({ encrypted: 'cred-data' }),
   importBackup: jest.fn()
 }));
-jest.mock('../resource-monitor', () => ({
+jest.mock('../src/managers/resource-monitor', () => ({
   exportStats: jest.fn().mockReturnValue({ stats: [{ cpu: 10 }] }),
   importStats: jest.fn()
 }));
 
 const fs = require('fs');
 const crypto = require('crypto');
-const credentialManager = require('../credential-manager');
-const resourceMonitor = require('../resource-monitor');
+const credentialManager = require('../src/managers/credential-manager');
+const resourceMonitor = require('../src/managers/resource-monitor');
 
 // Setup defaults BEFORE requiring singleton (constructor calls loadConfig/loadHistory)
 fs.existsSync.mockReturnValue(false);
@@ -24,7 +24,7 @@ fs.writeFileSync.mockReturnValue(undefined);
 fs.mkdirSync.mockReturnValue(undefined);
 fs.unlinkSync.mockReturnValue(undefined);
 
-const backupManager = require('../backup-manager');
+const backupManager = require('../src/utilities/backup-manager');
 
 beforeEach(() => {
   jest.clearAllMocks();

dashcaddy-api/__tests__/config-drift-detector.test.js

@@ -0,0 +1,335 @@
+/**
+ * Smoke tests for config-drift-detector.js
+ * Verifies the ConfigDriftDetector class detects drift across all categories,
+ * exposes polling control, extracts container ports, and dispatches
+ * drift notifications.
+ */
+
+const EventEmitter = require('events');
+const { ConfigDriftDetector } = require('../src/managers/config-drift-detector');
+
+function makeContainer(overrides = {}) {
+  return {
+    Id: 'abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789',
+    Names: ['/dashcaddy-test'],
+    Image: 'nginx:latest',
+    State: 'running',
+    Status: 'Up 5 minutes',
+    Ports: [],
+    Labels: {},
+    ...overrides,
+  };
+}
+
+function makeDetector(overrides = {}) {
+  const servicesStateManager = {
+    read: jest.fn().mockResolvedValue([]),
+    update: jest.fn().mockImplementation(async (updater) => {
+      const data = await servicesStateManager.read();
+      const list = Array.isArray(data) ? data : (data?.services || []);
+      const next = updater(list);
+      return next;
+    }),
+    ...(overrides.servicesStateManager || {}),
+  };
+
+  const docker = {
+    client: {
+      listContainers: jest.fn().mockResolvedValue([]),
+      ...(overrides.dockerClient || {}),
+    },
+  };
+
+  const notification = {
+    send: jest.fn().mockResolvedValue({ success: true }),
+    ...(overrides.notification || {}),
+  };
+
+  const ctx = {
+    docker,
+    servicesStateManager,
+    notification,
+    log: {
+      info: jest.fn(),
+      error: jest.fn(),
+      warn: jest.fn(),
+      debug: jest.fn(),
+    },
+    logError: jest.fn(),
+  };
+
+  const detector = new ConfigDriftDetector(ctx);
+  return { detector, ctx, docker, servicesStateManager, notification };
+}
+
+describe('ConfigDriftDetector', () => {
+  describe('constructor', () => {
+    test('extends EventEmitter and stores ctx dependencies', () => {
+      const { detector, ctx } = makeDetector();
+      expect(detector).toBeInstanceOf(EventEmitter);
+      expect(detector.ctx).toBe(ctx);
+      expect(detector.docker).toBe(ctx.docker);
+      expect(detector.servicesStateManager).toBe(ctx.servicesStateManager);
+      expect(detector.notification).toBe(ctx.notification);
+      expect(detector.lastReport).toBeNull();
+      expect(detector.isPolling()).toBe(false);
+    });
+  });
+
+  describe('detect()', () => {
+    test('returns a clean report when services and containers are empty', async () => {
+      const { detector } = makeDetector();
+      const report = await detector.detect();
+      expect(report).toHaveProperty('checkedAt');
+      expect(report.missingContainers).toEqual([]);
+      expect(report.unknownContainers).toEqual([]);
+      expect(report.portMismatch).toEqual([]);
+      expect(report.stateMismatch).toEqual([]);
+      expect(report.staleRecords).toEqual([]);
+      expect(report.hasDrift).toBe(false);
+    });
+
+    test('flags missing containers when service containerId is not in Docker', async () => {
+      const services = [{
+        id: 'svc-1',
+        name: 'svc-1',
+        containerId: 'deadbeef00000000deadbeef0000000000000000deadbeef0000000000000000',
+      }];
+      const { detector, servicesStateManager, docker } = makeDetector();
+      servicesStateManager.read.mockResolvedValue(services);
+      docker.client.listContainers.mockResolvedValue([]);
+
+      const report = await detector.detect();
+      expect(report.staleRecords).toHaveLength(1);
+      expect(report.staleRecords[0].serviceId).toBe('svc-1');
+      expect(report.hasDrift).toBe(true);
+    });
+
+    test('flags port mismatches between service config and container', async () => {
+      const services = [{
+        id: 'svc-1',
+        name: 'svc-1',
+        port: 8080,
+        containerId: 'abcdef012345',
+      }];
+      const containers = [makeContainer({
+        Id: 'abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789',
+        Ports: [{ PublicPort: 9090, PrivatePort: 80, Type: 'tcp' }],
+      })];
+
+      const { detector, servicesStateManager, docker } = makeDetector();
+      servicesStateManager.read.mockResolvedValue(services);
+      docker.client.listContainers.mockResolvedValue(containers);
+
+      const report = await detector.detect();
+      expect(report.portMismatch).toHaveLength(1);
+      expect(report.portMismatch[0].configuredPort).toBe(8080);
+      expect(report.portMismatch[0].actualPorts).toEqual([9090]);
+    });
+
+    test('flags state mismatch when service is not running', async () => {
+      const services = [{
+        id: 'svc-1',
+        name: 'svc-1',
+        containerId: 'abcdef012345',
+      }];
+      const containers = [makeContainer({ State: 'exited', Status: 'Exited (1) 5 minutes ago' })];
+
+      const { detector, servicesStateManager, docker } = makeDetector();
+      servicesStateManager.read.mockResolvedValue(services);
+      docker.client.listContainers.mockResolvedValue(containers);
+
+      const report = await detector.detect();
+      expect(report.missingContainers).toHaveLength(1);
+      expect(report.stateMismatch).toHaveLength(1);
+      expect(report.stateMismatch[0].actualState).toBe('exited');
+    });
+
+    test('flags unknown managed containers not in services.json', async () => {
+      const containers = [makeContainer({
+        Labels: { 'sami.managed': 'true', 'sami.app': 'whoami' },
+      })];
+
+      const { detector, docker, servicesStateManager } = makeDetector();
+      docker.client.listContainers.mockResolvedValue(containers);
+      servicesStateManager.read.mockResolvedValue([]);
+
+      const report = await detector.detect();
+      expect(report.unknownContainers).toHaveLength(1);
+      expect(report.unknownContainers[0].name).toBe('dashcaddy-test');
+      expect(report.unknownContainers[0].app).toBe('whoami');
+    });
+
+    test('emits drift-detected and sends notification when drift exists', async () => {
+      const services = [{
+        id: 'svc-1',
+        name: 'svc-1',
+        containerId: 'missingcontainer00',
+      }];
+      const { detector, servicesStateManager, docker, notification } = makeDetector();
+      servicesStateManager.read.mockResolvedValue(services);
+      docker.client.listContainers.mockResolvedValue([]);
+
+      const onDrift = jest.fn();
+      detector.on('drift-detected', onDrift);
+      await detector.detect();
+
+      expect(onDrift).toHaveBeenCalledTimes(1);
+      expect(notification.send).toHaveBeenCalledTimes(1);
+      expect(notification.send.mock.calls[0][0]).toBe('drift-detected');
+      const payload = notification.send.mock.calls[0][1];
+      expect(payload.text).toMatch(/drift/i);
+      expect(payload.report).toBeDefined();
+    });
+
+    test('caches the report on the instance', async () => {
+      const { detector } = makeDetector();
+      const report = await detector.detect();
+      expect(detector.lastReport).toBe(report);
+    });
+
+    test('handles services as a wrapper object with .services field', async () => {
+      const { detector, servicesStateManager } = makeDetector();
+      servicesStateManager.read.mockResolvedValue({ services: [] });
+      const report = await detector.detect();
+      expect(report).toBeDefined();
+      expect(report.hasDrift).toBe(false);
+    });
+
+    test('tolerates Docker listContainers failure (logs and continues)', async () => {
+      const { detector, docker, ctx } = makeDetector();
+      docker.client.listContainers.mockRejectedValue(new Error('docker daemon down'));
+      const report = await detector.detect();
+      expect(report).toBeDefined();
+      expect(report.hasDrift).toBe(false);
+      expect(ctx.log.error).toHaveBeenCalled();
+    });
+  });
+
+  describe('autoFix()', () => {
+    test('removes stale records via servicesStateManager.update', async () => {
+      const services = [
+        { id: 'svc-good', name: 'svc-good', containerId: 'liveid0000000000000000000000000000' },
+        { id: 'svc-stale', name: 'svc-stale', containerId: 'deadbeef00000000deadbeef0000000000000000deadbeef00000000' },
+      ];
+      const containers = [makeContainer({
+        Id: 'liveid0000000000000000000000000000000000000000000000000000000000',
+      })];
+
+      const { detector, servicesStateManager, docker } = makeDetector();
+      servicesStateManager.read.mockResolvedValue(services);
+      servicesStateManager.update.mockImplementation(async (updater) => {
+        const next = updater(services);
+        return next;
+      });
+      docker.client.listContainers.mockResolvedValue(containers);
+
+      const result = await detector.autoFix();
+      expect(result.staleRemoved).toBe(1);
+      expect(result.unknownFlagged).toBe(0);
+      expect(servicesStateManager.update).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('polling', () => {
+    afterEach(() => {
+      jest.useRealTimers();
+    });
+
+    test('startPolling/stopPolling toggles isPolling', () => {
+      const { detector } = makeDetector();
+      expect(detector.isPolling()).toBe(false);
+      detector.startPolling(60000);
+      expect(detector.isPolling()).toBe(true);
+      detector.stopPolling();
+      expect(detector.isPolling()).toBe(false);
+    });
+
+    test('startPolling clears any existing timer before starting a new one', () => {
+      const { detector } = makeDetector();
+      detector.startPolling(60000);
+      const firstTimer = detector._pollTimer;
+      detector.startPolling(120000);
+      expect(detector._pollTimer).not.toBe(firstTimer);
+      detector.stopPolling();
+    });
+
+    test('stopPolling is a safe no-op when not started', () => {
+      const { detector } = makeDetector();
+      expect(() => detector.stopPolling()).not.toThrow();
+      expect(detector.isPolling()).toBe(false);
+    });
+
+    test('runs detect on the polling interval', async () => {
+      jest.useFakeTimers();
+      const { detector } = makeDetector();
+      const detectSpy = jest.spyOn(detector, 'detect').mockResolvedValue({
+        checkedAt: new Date().toISOString(),
+        missingContainers: [],
+        unknownContainers: [],
+        portMismatch: [],
+        stateMismatch: [],
+        staleRecords: [],
+        hasDrift: false,
+      });
+
+      detector.startPolling(1000);
+      jest.advanceTimersByTime(3500);
+      // 3 intervals should have fired (1000, 2000, 3000)
+      expect(detectSpy.mock.calls.length).toBeGreaterThanOrEqual(3);
+      detector.stopPolling();
+      detectSpy.mockRestore();
+    });
+  });
+
+  describe('_extractContainerPorts', () => {
+    test('returns mapped public ports', () => {
+      const { detector } = makeDetector();
+      const ports = detector._extractContainerPorts({
+        Ports: [
+          { PublicPort: 8080, PrivatePort: 80, Type: 'tcp' },
+          { PublicPort: 8443, PrivatePort: 443, Type: 'tcp' },
+          { PrivatePort: 53, Type: 'udp' }, // No PublicPort → not exposed
+        ],
+      });
+      expect(ports).toEqual([8080, 8443]);
+    });
+
+    test('returns [] when container has no Ports field', () => {
+      const { detector } = makeDetector();
+      expect(detector._extractContainerPorts({})).toEqual([]);
+      expect(detector._extractContainerPorts({ Ports: null })).toEqual([]);
+    });
+  });
+
+  describe('_sendDriftNotification', () => {
+    test('returns early when no notification manager is present', async () => {
+      const { detector } = makeDetector({ notification: null });
+      // Replace the field with null/undefined to simulate missing
+      detector.notification = null;
+      const result = await detector._sendDriftNotification({ hasDrift: true });
+      expect(result.success).toBe(false);
+      expect(result.reason).toMatch(/no-notification-manager/i);
+    });
+
+    test('formats message with one line per drift category', async () => {
+      const { detector, notification } = makeDetector();
+      const report = {
+        missingContainers: [{ name: 'app-a' }],
+        unknownContainers: [{ name: 'app-b' }],
+        portMismatch: [{ name: 'app-c' }],
+        stateMismatch: [],
+        staleRecords: [{ name: 'app-d' }],
+        hasDrift: true,
+      };
+      await detector._sendDriftNotification(report);
+      expect(notification.send).toHaveBeenCalledTimes(1);
+      const payload = notification.send.mock.calls[0][1];
+      expect(payload.text).toMatch(/Missing containers: app-a/);
+      expect(payload.text).toMatch(/Unknown managed containers: app-b/);
+      expect(payload.text).toMatch(/Port mismatches: app-c/);
+      expect(payload.text).toMatch(/Stale records: app-d/);
+      expect(payload.report).toBe(report);
+    });
+  });
+});

dashcaddy-api/__tests__/credential-manager.test.js

@@ -1,12 +1,12 @@
 // Mock dependencies before requiring the module
-jest.mock('../keychain-manager', () => ({
+jest.mock('../src/security/keychain-manager', () => ({
   available: false,
   store: jest.fn().mockResolvedValue(false),
   retrieve: jest.fn().mockResolvedValue(null),
   delete: jest.fn().mockResolvedValue(true),
 }));
 
-jest.mock('../crypto-utils', () => ({
+jest.mock('../src/security/crypto-utils', () => ({
   encrypt: jest.fn(data => `enc:tag:${Buffer.from(String(data)).toString('base64')}`),
   decrypt: jest.fn(data => {
     const parts = data.split(':');
@@ -40,8 +40,8 @@ describe('CredentialManager', () => {
     // Re-get mocked modules
     fs = require('fs');
     lockfile = require('proper-lockfile');
-    keychainManager = require('../keychain-manager');
-    cryptoUtils = require('../crypto-utils');
+    keychainManager = require('../src/security/keychain-manager');
+    cryptoUtils = require('../src/security/crypto-utils');
 
     // Reset mock implementations
     fs.existsSync.mockReturnValue(true);
@@ -50,7 +50,7 @@ describe('CredentialManager', () => {
     lockfile.lock.mockResolvedValue(jest.fn().mockResolvedValue());
     keychainManager.available = false;
 
-    credentialManager = require('../credential-manager');
+    credentialManager = require('../src/managers/credential-manager');
     credentialManager.cache.clear();
   });
 
@@ -72,10 +72,10 @@ describe('CredentialManager', () => {
       fs.writeFileSync.mockImplementation(() => {});
       lockfile = require('proper-lockfile');
       lockfile.lock.mockResolvedValue(jest.fn().mockResolvedValue());
-      keychainManager = require('../keychain-manager');
+      keychainManager = require('../src/security/keychain-manager');
       keychainManager.available = true;
       keychainManager.store.mockResolvedValue(true);
-      credentialManager = require('../credential-manager');
+      credentialManager = require('../src/managers/credential-manager');
 
       const result = await credentialManager.store('test.key', 'value');
       expect(result).toBe(true);
@@ -91,11 +91,11 @@ describe('CredentialManager', () => {
       fs.writeFileSync.mockImplementation(() => {});
       lockfile = require('proper-lockfile');
       lockfile.lock.mockResolvedValue(jest.fn().mockResolvedValue());
-      keychainManager = require('../keychain-manager');
+      keychainManager = require('../src/security/keychain-manager');
       keychainManager.available = true;
       keychainManager.store.mockResolvedValue(false);
-      cryptoUtils = require('../crypto-utils');
-      credentialManager = require('../credential-manager');
+      cryptoUtils = require('../src/security/crypto-utils');
+      credentialManager = require('../src/managers/credential-manager');
 
       const result = await credentialManager.store('test.key', 'value');
       expect(result).toBe(true);

dashcaddy-api/__tests__/crypto-utils.test.js

@@ -11,7 +11,7 @@ const TEST_KEY_HEX = TEST_KEY.toString('hex');
 // Load the module once — no jest.resetModules() needed
 // We control key state via clearCachedKey() + env vars
 process.env.DASHCADDY_ENCRYPTION_KEY = TEST_KEY_HEX;
-const cryptoUtils = require('../crypto-utils');
+const cryptoUtils = require('../src/security/crypto-utils');
 
 describe('Crypto Utils', () => {
   beforeEach(() => {

dashcaddy-api/__tests__/csrf-protection.test.js

@@ -2,7 +2,7 @@ const crypto = require('crypto');
 
 // Mock crypto-utils to provide a predictable signing key
 const mockFixedKey = Buffer.alloc(32, 'test-key-material');
-jest.mock('../crypto-utils', () => ({
+jest.mock('../src/security/crypto-utils', () => ({
   loadOrCreateKey: jest.fn(() => mockFixedKey),
 }));
 
@@ -16,7 +16,7 @@ const {
   csrfCookieMiddleware,
   csrfValidationMiddleware,
   renewCSRFToken
-} = require('../csrf-protection');
+} = require('../src/security/csrf-protection');
 const { createMockReqRes } = require('./helpers/test-utils');
 
 describe('CSRF Protection', () => {

dashcaddy-api/__tests__/dns-propagation.test.js

@@ -0,0 +1,106 @@
+/**
+ * Smoke tests for dns-propagation.js
+ * Verifies DNS propagation checker module loads, exposes the expected
+ * interface, and basic methods (verifyRecord, startVerification,
+ * getVerificationStatus, getAllVerifications, cleanup) work without throwing.
+ */
+
+// The module does `const dns = require('dns').promises;` then `new dns.Resolver()`.
+// We mock the dns module so that .promises exposes our Resolver class.
+jest.mock('dns', () => {
+  class MockResolver {
+    setServers() { return this; }
+    setTimeout() { return this; }
+    resolve4(domain) {
+      if (domain === 'propagated.sami') {
+        return Promise.resolve(['1.2.3.4']);
+      }
+      return Promise.resolve(['9.9.9.9']);
+    }
+  }
+  return {
+    promises: { Resolver: MockResolver },
+    Resolver: MockResolver,
+  };
+});
+
+const DNSPropagationChecker = require('../src/dns/dns-propagation');
+
+describe('DNSPropagationChecker', () => {
+  let checker;
+
+  beforeEach(() => {
+    const ctx = {
+      log: { error: jest.fn(), info: jest.fn(), warn: jest.fn() },
+      notification: { send: jest.fn().mockResolvedValue({ success: true }) },
+    };
+    checker = new DNSPropagationChecker(ctx);
+  });
+
+  test('is an EventEmitter', () => {
+    expect(typeof checker.on).toBe('function');
+    expect(typeof checker.emit).toBe('function');
+  });
+
+  test('starts with an empty verifications map', () => {
+    expect(checker.verifications).toBeInstanceOf(Map);
+    expect(checker.verifications.size).toBe(0);
+  });
+
+  test('verifyRecord returns expected shape and detects propagated domain', async () => {
+    const result = await checker.verifyRecord('propagated.sami', '1.2.3.4', {
+      timeout: 5000,
+      interval: 100,
+      resolvers: ['1.1.1.1'],
+    });
+    expect(result).toHaveProperty('domain', 'propagated.sami');
+    expect(result).toHaveProperty('expectedIp', '1.2.3.4');
+    expect(result).toHaveProperty('propagated', true);
+    expect(Array.isArray(result.results)).toBe(true);
+    expect(result.results.length).toBeGreaterThan(0);
+    expect(typeof result.totalTime).toBe('number');
+    expect(typeof result.checkedAt).toBe('string');
+  });
+
+  test('verifyRecord reports not-propagated when IP does not match', async () => {
+    const result = await checker.verifyRecord('notpropagated.sami', '5.6.7.8', {
+      timeout: 200,
+      interval: 50,
+      resolvers: ['1.1.1.1'],
+    });
+    expect(result.propagated).toBe(false);
+  });
+
+  test('startVerification returns a job object with running status', () => {
+    const job = checker.startVerification('job.sami', '1.1.1.1', {
+      timeout: 100,
+      interval: 50,
+      resolvers: ['1.1.1.1'],
+    });
+    expect(job).toMatchObject({
+      domain: 'job.sami',
+      expectedIp: '1.1.1.1',
+      status: 'running',
+    });
+    expect(job.startedAt).toBeDefined();
+  });
+
+  test('startVerification returns the same job when called twice for one domain', () => {
+    const a = checker.startVerification('dup.sami', '1.1.1.1', { timeout: 5000, interval: 1000 });
+    const b = checker.startVerification('dup.sami', '1.1.1.1', { timeout: 5000, interval: 1000 });
+    expect(a).toBe(b);
+  });
+
+  test('getVerificationStatus returns null for unknown domain', () => {
+    expect(checker.getVerificationStatus('nope.sami')).toBeNull();
+  });
+
+  test('getAllVerifications returns an array', () => {
+    expect(Array.isArray(checker.getAllVerifications())).toBe(true);
+  });
+
+  test('cleanup is a no-op on empty verifications', () => {
+    expect(() => checker.cleanup()).not.toThrow();
+    expect(checker.verifications.size).toBe(0);
+  });
+});

dashcaddy-api/__tests__/docker-security.test.js

@@ -27,7 +27,7 @@ describe('DockerSecurity Module', () => {
 
     // Reset modules to get fresh instance
     jest.resetModules();
-    dockerSecurity = require('../docker-security');
+    dockerSecurity = require('../src/security/docker-security');
   });
 
   afterEach(() => {
@@ -58,7 +58,7 @@ describe('DockerSecurity Module', () => {
 
       // Force module reload
       jest.resetModules();
-      const freshInstance = require('../docker-security');
+      const freshInstance = require('../src/security/docker-security');
       const status = freshInstance.getStatus();
 
       expect(status.trustedImagesCount).toBe(1);
@@ -77,7 +77,7 @@ describe('DockerSecurity Module', () => {
       fs.writeFileSync(TEST_CONFIG_FILE, 'INVALID JSON{{{');
 
       jest.resetModules();
-      const freshInstance = require('../docker-security');
+      const freshInstance = require('../src/security/docker-security');
       const status = freshInstance.getStatus();
 
       // Should fall back to default config
@@ -89,7 +89,7 @@ describe('DockerSecurity Module', () => {
       process.env.DOCKER_SECURITY_CONFIG = '/nonexistent/path/config.json';
 
       jest.resetModules();
-      const freshInstance = require('../docker-security');
+      const freshInstance = require('../src/security/docker-security');
       const status = freshInstance.getStatus();
 
       // Should fall back to default config

dashcaddy-api/__tests__/error-handler.test.js

@@ -12,7 +12,7 @@ jest.mock('../src/utils/logging', () => ({
   LOG_LEVELS: { debug: 0, info: 1, warn: 2, error: 3 }
 }));
 
-const { errorMiddleware, notFoundHandler } = require('../error-handler');
+const { errorMiddleware, notFoundHandler } = require('../src/utilities/error-handler');
 const {
   AppError,
   ValidationError,
@@ -20,7 +20,7 @@ const {
   NotFoundError,
   RateLimitError,
   DockerError,
-} = require('../errors');
+} = require('../src/utilities/errors');
 
 describe('Error Handler', () => {
   let req, res, next;

dashcaddy-api/__tests__/errors.test.js

@@ -10,7 +10,7 @@ const {
   CaddyError,
   DNSError,
   ServiceUnavailableError
-} = require('../errors');
+} = require('../src/utilities/errors');
 
 describe('Error Classes', () => {
   describe('AppError', () => {

dashcaddy-api/__tests__/health-checker.test.js

@@ -17,7 +17,7 @@ describe('HealthChecker', () => {
     fs.writeFileSync.mockImplementation(() => {});
 
     // Fresh instance each test
-    HealthChecker = require('../health-checker').constructor;
+    HealthChecker = require('../src/monitoring/health-checker').constructor;
     healthChecker = new HealthChecker();
   });
 
@@ -41,7 +41,7 @@ describe('HealthChecker', () => {
         services: { svc1: { url: 'http://test.local', enabled: true } }
       }));
 
-      HealthChecker = require('../health-checker').constructor;
+      HealthChecker = require('../src/monitoring/health-checker').constructor;
       const hc = new HealthChecker();
       expect(hc.config.services.svc1).toBeDefined();
     });
@@ -52,7 +52,7 @@ describe('HealthChecker', () => {
       fs.existsSync.mockReturnValue(true);
       fs.readFileSync.mockReturnValue('invalid json');
 
-      HealthChecker = require('../health-checker').constructor;
+      HealthChecker = require('../src/monitoring/health-checker').constructor;
       const hc = new HealthChecker();
       expect(hc.config).toEqual({ services: {} });
     });

dashcaddy-api/__tests__/helpers/test-utils.js

@@ -90,7 +90,7 @@ function buildTestApp(routeFactory, deps, prefix = '/api') {
   const router = routeFactory(deps);
   app.use(prefix, router);
   // Error handler
-  const { errorMiddleware } = require('../../error-handler');
+  const { errorMiddleware } = require('../../../src/utilities/error-handler');
   app.use(errorMiddleware);
   return app;
 }

dashcaddy-api/__tests__/input-validator.test.js

@@ -11,7 +11,7 @@ const {
   isValidPort,
   isPrivateIP,
   validateSecurePath
-} = require('../input-validator');
+} = require('../src/security/input-validator');
 
 describe('Input Validator', () => {
   function fail(message) {
@@ -480,7 +480,7 @@ describe('Input Validator', () => {
 
     // Re-require after mocking fs
     function getValidateSecurePath() {
-      return require('../input-validator').validateSecurePath;
+      return require('../src/security/input-validator').validateSecurePath;
     }
 
     it('resolves valid path within allowed roots', async () => {

dashcaddy-api/__tests__/log-digest.test.js

@@ -0,0 +1,187 @@
+/**
+ * Smoke tests for log-digest.js
+ * Verifies the singleton LogDigest exposes the expected interface, parses
+ * Docker multiplexed log streams, formats digests, and supports on-demand
+ * daily digest generation with mocked Docker.
+ */
+
+const fsReal = require('fs');
+const os = require('os');
+const path = require('path');
+
+jest.mock('dockerode', () => {
+  const listContainers = jest.fn().mockResolvedValue([]);
+  const getContainer = jest.fn(() => ({
+    logs: jest.fn().mockResolvedValue(Buffer.from([])),
+  }));
+  function Docker() {}
+  Docker.prototype.listContainers = listContainers;
+  Docker.prototype.getContainer = getContainer;
+  return Docker;
+});
+
+jest.mock('fs', () => {
+  const actual = jest.requireActual('fs');
+  return {
+    ...actual,
+    existsSync: jest.fn().mockReturnValue(true),
+    mkdirSync: jest.fn(),
+  };
+});
+
+jest.mock('../src/docker/docker-maintenance', () => ({
+  getDiskUsage: jest.fn().mockResolvedValue(null),
+}));
+
+const Docker = require('dockerode');
+const fs = require('fs');
+const logDigest = require('../src/security/log-digest');
+
+describe('LogDigest (singleton)', () => {
+  let dockerInstance;
+  let tempDir;
+
+  beforeEach(() => {
+    // Each test gets a fresh Docker() mock instance
+    jest.clearAllMocks();
+    fs.existsSync.mockReturnValue(true);
+    // Use a real, writable temp directory so writeFile inside generateDailyDigest
+    // does not blow up. Each test gets a fresh dir to avoid cross-test pollution.
+    tempDir = fsReal.mkdtempSync(path.join(os.tmpdir(), 'dc-digest-test-'));
+    logDigest.hourlySummaries = [];
+    logDigest.lastCollect = null;
+    logDigest.running = false;
+    logDigest.digestDir = null;
+    if (logDigest.collectInterval) {
+      clearInterval(logDigest.collectInterval);
+      logDigest.collectInterval = null;
+    }
+    if (logDigest.digestTimeout) {
+      clearTimeout(logDigest.digestTimeout);
+      logDigest.digestTimeout = null;
+    }
+    dockerInstance = new Docker();
+  });
+
+  afterEach(() => {
+    logDigest.stop();
+    if (tempDir && fsReal.existsSync(tempDir)) {
+      fsReal.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  test('is an EventEmitter and exposes the documented API', () => {
+    expect(typeof logDigest.on).toBe('function');
+    expect(typeof logDigest.emit).toBe('function');
+    expect(typeof logDigest.start).toBe('function');
+    expect(typeof logDigest.stop).toBe('function');
+    expect(typeof logDigest.generateDailyDigest).toBe('function');
+    expect(typeof logDigest.getLatestDigest).toBe('function');
+    expect(typeof logDigest.getDigestByDate).toBe('function');
+    expect(typeof logDigest.getDigestText).toBe('function');
+    expect(typeof logDigest.listDigests).toBe('function');
+    expect(typeof logDigest.getLiveData).toBe('function');
+    expect(typeof logDigest.getStatus).toBe('function');
+  });
+
+  test('getStatus returns current state', () => {
+    const status = logDigest.getStatus();
+    expect(status).toEqual({
+      running: false,
+      lastCollect: null,
+      hourlySummaries: 0,
+      digestDir: null,
+    });
+  });
+
+  test('start sets running and digestDir', () => {
+    logDigest.start(tempDir);
+    expect(logDigest.running).toBe(true);
+    expect(logDigest.digestDir).toBe(tempDir);
+  });
+
+  test('start is idempotent — second call does nothing new', () => {
+    logDigest.start(tempDir);
+    const firstInterval = logDigest.collectInterval;
+    logDigest.start(tempDir);
+    expect(logDigest.collectInterval).toBe(firstInterval);
+  });
+
+  test('_parseDockerLogs decodes multiplexed log frames into lines', () => {
+    // Stream type byte: 0=stdin, 1=stdout, 2=stderr
+    // Header: [type, 0, 0, 0, size-BE-uint32]
+    function frame(streamType, text) {
+      const buf = Buffer.from(text, 'utf8');
+      const header = Buffer.alloc(8);
+      header[0] = streamType;
+      header.writeUInt32BE(buf.length, 4);
+      return Buffer.concat([header, buf]);
+    }
+
+    const multiplexed = Buffer.concat([
+      frame(1, 'hello world\n'),
+      frame(2, '2026-03-13T12:00:00.000Z an error happened\n'),
+    ]);
+
+    const lines = logDigest._parseDockerLogs(multiplexed);
+    expect(lines).toHaveLength(2);
+    expect(lines[0]).toEqual({
+      stream: 'stdout',
+      text: 'hello world',
+      timestamp: null,
+    });
+    expect(lines[1].stream).toBe('stderr');
+    expect(lines[1].text).toBe('an error happened');
+    expect(lines[1].timestamp).toBe('2026-03-13T12:00:00');
+  });
+
+  test('generateDailyDigest with empty summaries produces minimal digest', async () => {
+    logDigest.start(tempDir);
+    const digest = await logDigest.generateDailyDigest('2099-01-01');
+    expect(digest.date).toBe('2099-01-01');
+    expect(digest.services).toEqual({});
+    expect(digest.summary.totalServices).toBe(0);
+    expect(digest.summary.totalErrors).toBe(0);
+    expect(Array.isArray(digest.notableEvents)).toBe(true);
+
+    // Confirm the file was actually written
+    const writtenPath = path.join(tempDir, 'digest-2099-01-01.log');
+    expect(fsReal.existsSync(writtenPath)).toBe(true);
+    const jsonPath = path.join(tempDir, 'digest-2099-01-01.json');
+    expect(fsReal.existsSync(jsonPath)).toBe(true);
+  });
+
+  test('getLiveData returns shape with date, hoursCollected, services', () => {
+    const data = logDigest.getLiveData();
+    expect(data).toHaveProperty('date');
+    expect(data).toHaveProperty('hoursCollected');
+    expect(data).toHaveProperty('services');
+    expect(data).toHaveProperty('lastCollect');
+  });
+
+  test('getLatestDigest returns null when digestDir is null', async () => {
+    logDigest.digestDir = null;
+    const result = await logDigest.getLatestDigest();
+    expect(result).toBeNull();
+  });
+
+  test('getDigestByDate returns null when no file exists', async () => {
+    logDigest.digestDir = '/nonexistent/path';
+    const result = await logDigest.getDigestByDate('2020-01-01');
+    expect(result).toBeNull();
+  });
+
+  test('listDigests returns empty array when digestDir is null', async () => {
+    logDigest.digestDir = null;
+    const result = await logDigest.listDigests();
+    expect(result).toEqual([]);
+  });
+
+  test('stop clears intervals and timeouts', () => {
+    logDigest.start(tempDir);
+    logDigest.stop();
+    expect(logDigest.running).toBe(false);
+    expect(logDigest.collectInterval).toBeNull();
+    expect(logDigest.digestTimeout).toBeNull();
+  });
+});

dashcaddy-api/__tests__/metrics.test.js

@@ -0,0 +1,207 @@
+/**
+ * Smoke tests for metrics.js
+ * Verifies the Metrics singleton exposes the expected interface, accumulates
+ * request/error/business counters, normalizes paths, formats uptime, and resets.
+ *
+ * The module exports a singleton instance, so we import it once and mutate its
+ * state in beforeEach.
+ */
+
+const metrics = require('../src/monitoring/metrics');
+
+describe('Metrics (singleton)', () => {
+  beforeEach(() => {
+    metrics.reset();
+  });
+
+  test('exposes the documented public API', () => {
+    expect(typeof metrics.recordRequest).toBe('function');
+    expect(typeof metrics.recordError).toBe('function');
+    expect(typeof metrics.recordBusinessEvent).toBe('function');
+    expect(typeof metrics.normalizePath).toBe('function');
+    expect(typeof metrics.getSummary).toBe('function');
+    expect(typeof metrics.formatUptime).toBe('function');
+    expect(typeof metrics.reset).toBe('function');
+  });
+
+  describe('recordRequest', () => {
+    test('increments total request count', () => {
+      metrics.recordRequest('GET', '/api/services', 200, 12);
+      metrics.recordRequest('GET', '/api/services', 200, 8);
+      expect(metrics.requests.total).toBe(2);
+    });
+
+    test('aggregates by status code', () => {
+      metrics.recordRequest('GET', '/a', 200, 5);
+      metrics.recordRequest('GET', '/b', 200, 5);
+      metrics.recordRequest('POST', '/c', 500, 5);
+      expect(metrics.requests.byStatus[200]).toBe(2);
+      expect(metrics.requests.byStatus[500]).toBe(1);
+    });
+
+    test('aggregates by HTTP method', () => {
+      metrics.recordRequest('GET', '/a', 200, 1);
+      metrics.recordRequest('GET', '/b', 200, 1);
+      metrics.recordRequest('DELETE', '/c', 200, 1);
+      expect(metrics.requests.byMethod.GET).toBe(2);
+      expect(metrics.requests.byMethod.DELETE).toBe(1);
+    });
+
+    test('aggregates by normalized path with totalDuration', () => {
+      // Real-looking UUID and long hex hash; both should normalize to /:id
+      const id1 = '550e8400-e29b-41d4-a716-446655440000';
+      const id2 = 'abcdef0123456789abcdef0123456789';
+      metrics.recordRequest('GET', `/api/services/${id1}`, 200, 10);
+      metrics.recordRequest('GET', `/api/services/${id2}`, 200, 20);
+      const entry = metrics.requests.byPath['/api/services/:id'];
+      expect(entry).toBeDefined();
+      expect(entry.count).toBe(2);
+      expect(entry.totalDuration).toBe(30);
+    });
+  });
+
+  describe('recordError', () => {
+    test('increments total error count and per-type counts', () => {
+      metrics.recordError('ValidationError');
+      metrics.recordError('ValidationError');
+      metrics.recordError('DockerError');
+      expect(metrics.errors.total).toBe(3);
+      expect(metrics.errors.byType.ValidationError).toBe(2);
+      expect(metrics.errors.byType.DockerError).toBe(1);
+    });
+  });
+
+  describe('recordBusinessEvent', () => {
+    test('increments known business counters', () => {
+      metrics.recordBusinessEvent('containersDeployed');
+      metrics.recordBusinessEvent('containersDeployed');
+      metrics.recordBusinessEvent('dnsRecordsCreated');
+      expect(metrics.business.containersDeployed).toBe(2);
+      expect(metrics.business.dnsRecordsCreated).toBe(1);
+    });
+
+    test('ignores unknown event types without throwing', () => {
+      expect(() => metrics.recordBusinessEvent('not-a-real-event')).not.toThrow();
+      expect(metrics.business.notARealEvent).toBeUndefined();
+    });
+  });
+
+  describe('normalizePath', () => {
+    test('replaces UUIDs with /:id', () => {
+      const normalized = metrics.normalizePath('/api/services/550e8400-e29b-41d4-a716-446655440000');
+      expect(normalized).toBe('/api/services/:id');
+    });
+
+    test('replaces long hex segments with /:id', () => {
+      expect(metrics.normalizePath('/api/containers/abc123def4567890'))
+        .toBe('/api/containers/:id');
+    });
+
+    test('replaces numeric path segments with /:n', () => {
+      expect(metrics.normalizePath('/api/services/42/edit'))
+        .toBe('/api/services/:n/edit');
+    });
+
+    test('leaves static paths unchanged', () => {
+      expect(metrics.normalizePath('/api/health')).toBe('/api/health');
+      expect(metrics.normalizePath('/')).toBe('/');
+    });
+  });
+
+  describe('getSummary', () => {
+    test('returns an object with the documented top-level shape', () => {
+      const summary = metrics.getSummary();
+      expect(summary).toHaveProperty('uptime');
+      expect(summary.uptime).toHaveProperty('ms');
+      expect(summary.uptime).toHaveProperty('human');
+      expect(summary).toHaveProperty('requests');
+      expect(summary.requests).toHaveProperty('total');
+      expect(summary.requests).toHaveProperty('perSecond');
+      expect(summary.requests).toHaveProperty('byStatus');
+      expect(summary.requests).toHaveProperty('byMethod');
+      expect(summary.requests).toHaveProperty('topEndpoints');
+      expect(Array.isArray(summary.requests.topEndpoints)).toBe(true);
+      expect(summary).toHaveProperty('errors');
+      expect(summary.errors).toHaveProperty('total');
+      expect(summary.errors).toHaveProperty('rate');
+      expect(summary.errors).toHaveProperty('byType');
+      expect(summary).toHaveProperty('business');
+      expect(summary).toHaveProperty('process');
+      expect(summary.process).toHaveProperty('pid');
+    });
+
+    test('reflects recorded activity', () => {
+      metrics.recordRequest('GET', '/api/foo', 200, 10);
+      metrics.recordError('BoomError');
+      const summary = metrics.getSummary();
+      expect(summary.requests.total).toBe(1);
+      expect(summary.requests.byStatus[200]).toBe(1);
+      expect(summary.errors.total).toBe(1);
+      expect(summary.errors.byType.BoomError).toBe(1);
+      // 1 error / 1 request = 100% error rate
+      expect(summary.errors.rate).toBe(100);
+    });
+
+    test('topEndpoints is sorted by count descending and capped at 15', () => {
+      // /a gets 3 hits, /b gets 1, /c gets 2
+      metrics.recordRequest('GET', '/a', 200, 1);
+      metrics.recordRequest('GET', '/a', 200, 2);
+      metrics.recordRequest('GET', '/a', 200, 3);
+      metrics.recordRequest('GET', '/b', 200, 1);
+      metrics.recordRequest('GET', '/c', 200, 1);
+      metrics.recordRequest('GET', '/c', 200, 2);
+      const top = metrics.getSummary().requests.topEndpoints;
+      expect(top[0].path).toBe('/a');
+      expect(top[0].count).toBe(3);
+      expect(top[0].avgMs).toBe(2);
+    });
+  });
+
+  describe('formatUptime', () => {
+    test('formats seconds-only when under a minute', () => {
+      expect(metrics.formatUptime(0)).toBe('0s');
+      expect(metrics.formatUptime(45)).toBe('45s');
+    });
+
+    test('formats minutes and seconds when under an hour', () => {
+      expect(metrics.formatUptime(60)).toBe('1m 0s');
+      expect(metrics.formatUptime(125)).toBe('2m 5s');
+    });
+
+    test('formats hours/minutes/seconds when under a day', () => {
+      expect(metrics.formatUptime(3600)).toBe('1h 0m 0s');
+      expect(metrics.formatUptime(3725)).toBe('1h 2m 5s');
+    });
+
+    test('formats days/hours/minutes when over a day', () => {
+      expect(metrics.formatUptime(86400)).toBe('1d 0h 0m');
+      // 1 day, 2 hours, 5 minutes, 0 seconds
+      expect(metrics.formatUptime(86400 + 2 * 3600 + 5 * 60)).toBe('1d 2h 5m');
+    });
+  });
+
+  describe('reset', () => {
+    test('clears request counters and error counters', () => {
+      metrics.recordRequest('GET', '/x', 200, 1);
+      metrics.recordError('E');
+      metrics.reset();
+      expect(metrics.requests.total).toBe(0);
+      expect(metrics.errors.total).toBe(0);
+      expect(metrics.requests.byStatus).toEqual({});
+      expect(metrics.requests.byMethod).toEqual({});
+      expect(metrics.requests.byPath).toEqual({});
+      expect(metrics.errors.byType).toEqual({});
+    });
+
+    test('resets startTime so uptime is small after reset', () => {
+      const before = metrics.startTime;
+      // Sleep a tick so Date.now() moves forward
+      const start = Date.now();
+      while (Date.now() - start < 5) {} // ~5ms busy-wait
+      metrics.reset();
+      expect(metrics.startTime).toBeGreaterThanOrEqual(before);
+      const summary = metrics.getSummary();
+      expect(summary.uptime.ms).toBeLessThan(5000);
+    });
+  });
+});

dashcaddy-api/__tests__/notification-manager.test.js

@@ -0,0 +1,217 @@
+/**
+ * Smoke tests for notification-manager.js
+ * Verifies the NotificationManager loads, exposes the expected interface,
+ * handles config loading/saving, sends notifications via providers, and
+ * correctly tracks history.
+ */
+
+jest.mock('fs', () => ({
+  existsSync: jest.fn().mockReturnValue(false),
+  readFileSync: jest.fn().mockReturnValue('{}'),
+  writeFileSync: jest.fn(),
+  mkdirSync: jest.fn(),
+}));
+
+jest.mock('nodemailer', () => ({
+  createTransport: jest.fn(() => ({
+    sendMail: jest.fn().mockResolvedValue({ messageId: 'mock' }),
+  })),
+}));
+
+const fs = require('fs');
+const nodemailer = require('nodemailer');
+const NotificationManager = require('../src/managers/notification-manager');
+
+describe('NotificationManager', () => {
+  let nm;
+  const NOTIF_FILE = '/tmp/dc-notif-test.json';
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    fs.existsSync.mockReturnValue(false);
+    fs.readFileSync.mockReturnValue('{}');
+    fs.writeFileSync.mockReturnValue(undefined);
+    fs.mkdirSync.mockReturnValue(undefined);
+
+    nm = new NotificationManager({
+      NOTIFICATIONS_FILE: NOTIF_FILE,
+      log: { error: jest.fn(), info: jest.fn(), warn: jest.fn() },
+      fetchT: jest.fn(),
+      docker: null,
+    });
+  });
+
+  afterEach(() => {
+    nm.stopHealthDaemon();
+  });
+
+  test('initializes with default config', () => {
+    const cfg = nm.getConfig();
+    expect(cfg.enabled).toBe(true);
+    expect(cfg.providers).toHaveProperty('discord');
+    expect(cfg.providers).toHaveProperty('telegram');
+    expect(cfg.providers).toHaveProperty('ntfy');
+    expect(cfg.providers).toHaveProperty('email');
+  });
+
+  test('starts with empty history and null lastSent', () => {
+    expect(nm.getHistory()).toEqual([]);
+    expect(nm.lastSent).toBeNull();
+  });
+
+  test('saveConfig writes the config to disk and creates parent dir', async () => {
+    fs.existsSync.mockReturnValue(false);
+    await nm.saveConfig();
+    expect(fs.mkdirSync).toHaveBeenCalled();
+    expect(fs.writeFileSync).toHaveBeenCalled();
+    const callArgs = fs.writeFileSync.mock.calls[0];
+    expect(callArgs[0]).toBe(NOTIF_FILE);
+    expect(callArgs[1]).toContain('enabled');
+  });
+
+  test('loadConfig merges file content with defaults', () => {
+    fs.existsSync.mockReturnValue(true);
+    fs.readFileSync.mockReturnValue(JSON.stringify({ enabled: false }));
+    const loaded = new NotificationManager({
+      NOTIFICATIONS_FILE: NOTIF_FILE,
+      log: { error: jest.fn(), info: jest.fn(), warn: jest.fn() },
+    });
+    expect(loaded.getConfig().enabled).toBe(false);
+  });
+
+  test('clearHistory empties the history array', () => {
+    nm.history.push({ event: 'test', timestamp: new Date().toISOString() });
+    expect(nm.getHistory().length).toBe(1);
+    nm.clearHistory();
+    expect(nm.getHistory().length).toBe(0);
+  });
+
+  test('send returns disabled when notifications are off', async () => {
+    nm.config.enabled = false;
+    const result = await nm.send('alert', { text: 'hi' });
+    expect(result.success).toBe(false);
+    expect(result.error).toMatch(/disabled/i);
+  });
+
+  test('send returns event-not-enabled for unknown events', async () => {
+    nm.config.events['some-disabled-event'] = false;
+    const result = await nm.send('some-disabled-event', { text: 'hi' });
+    expect(result.success).toBe(false);
+    expect(result.error).toMatch(/not enabled/i);
+  });
+
+  test('send with no providers enabled records history and returns success:false', async () => {
+    const result = await nm.send('alert', { text: 'hello' });
+    expect(result).toHaveProperty('results');
+    expect(Array.isArray(result.results)).toBe(true);
+    expect(nm.getHistory().length).toBe(1);
+    expect(nm.getHistory()[0].event).toBe('alert');
+  });
+
+  test('sendDiscord calls ctx.fetchT and returns success on 2xx', async () => {
+    nm.config.providers.discord = { enabled: true, webhookUrl: 'https://hook.test/x' };
+    nm.ctx.fetchT = jest.fn().mockResolvedValue({ ok: true });
+    const result = await nm.sendDiscord('msg', { title: 'T' });
+    expect(result.success).toBe(true);
+    expect(nm.ctx.fetchT).toHaveBeenCalledWith(
+      'https://hook.test/x',
+      expect.objectContaining({ method: 'POST' })
+    );
+  });
+
+  test('sendDiscord throws on non-2xx response', async () => {
+    nm.config.providers.discord = { enabled: true, webhookUrl: 'https://hook.test/x' };
+    nm.ctx.fetchT = jest.fn().mockResolvedValue({ ok: false, status: 500 });
+    await expect(nm.sendDiscord('msg', null)).rejects.toThrow(/Discord/);
+  });
+
+  test('sendTelegram calls Telegram API', async () => {
+    nm.config.providers.telegram = { enabled: true, botToken: 'TOK', chatId: '123' };
+    nm.ctx.fetchT = jest.fn().mockResolvedValue({ json: () => Promise.resolve({ ok: true }) });
+    const result = await nm.sendTelegram('hello');
+    expect(result.success).toBe(true);
+    expect(nm.ctx.fetchT).toHaveBeenCalledWith(
+      expect.stringContaining('api.telegram.org'),
+      expect.objectContaining({ method: 'POST' })
+    );
+  });
+
+  test('sendNtfy posts to the configured serverUrl + topic', async () => {
+    nm.config.providers.ntfy = { enabled: true, topic: 'dashcaddy', serverUrl: 'https://ntfy.sh' };
+    nm.ctx.fetchT = jest.fn().mockResolvedValue({ ok: true });
+    const result = await nm.sendNtfy('body', 'title');
+    expect(result.success).toBe(true);
+    expect(nm.ctx.fetchT).toHaveBeenCalledWith(
+      'https://ntfy.sh/dashcaddy',
+      expect.objectContaining({ method: 'POST' })
+    );
+  });
+
+  test('sendEmail uses nodemailer transporter', async () => {
+    nm.config.providers.email = {
+      enabled: true,
+      host: 'smtp.test',
+      port: 587,
+      to: 'me@test',
+      from: 'from@test',
+      username: 'u',
+      password: 'p',
+    };
+    const result = await nm.sendEmail('subject', 'body');
+    expect(result.success).toBe(true);
+    expect(nodemailer.createTransport).toHaveBeenCalled();
+  });
+
+  test('sendAlert, sendBackupComplete, sendServiceEvent do not throw', async () => {
+    const alertResult = await nm.sendAlert({
+      containerName: 'web',
+      alerts: [{ type: 'cpu', severity: 'warning', message: 'high' }],
+      timestamp: new Date().toISOString(),
+    });
+    expect(alertResult).toBeDefined();
+
+    const backupResult = await nm.sendBackupComplete({
+      name: 'daily',
+      status: 'success',
+    });
+    expect(backupResult).toBeDefined();
+
+    const serviceResult = await nm.sendServiceEvent('container-down', {
+      name: 'web',
+      containerName: 'sami-web',
+    });
+    expect(serviceResult).toBeDefined();
+  });
+
+  test('checkHealth returns checked:false when no docker client', async () => {
+    nm.ctx.docker = null;
+    const r = await nm.checkHealth();
+    expect(r.checked).toBe(false);
+  });
+
+  test('checkHealth with mocked docker returns checked:true', async () => {
+    nm.ctx.docker = {
+      listContainers: jest.fn().mockResolvedValue([
+        { Id: 'aaaabbbbcccc', Names: ['/web'], State: 'running', Status: 'Up' },
+        { Id: 'ddddeeeeffff', Names: ['/api'], State: 'exited', Status: 'Exited' },
+      ]),
+    };
+    nm.config.healthCheck = { enabled: true, intervalMinutes: 5 };
+    const r = await nm.checkHealth();
+    expect(r.checked).toBe(true);
+    expect(r.containersMonitored).toBe(2);
+  });
+
+  test('formatTitle returns a string for known events', () => {
+    expect(typeof nm._formatTitle('alert')).toBe('string');
+    expect(typeof nm._formatTitle('unknown')).toBe('string');
+  });
+
+  test('startHealthDaemon and stopHealthDaemon are idempotent', () => {
+    nm.startHealthDaemon();
+    nm.startHealthDaemon(); // should not double-schedule
+    nm.stopHealthDaemon();
+    nm.stopHealthDaemon();
+    expect(nm.healthDaemonInterval).toBeNull();
+  });
+});

dashcaddy-api/__tests__/pagination.test.js

@@ -1,4 +1,4 @@
-const { paginate, parsePaginationParams, DEFAULT_LIMIT, MAX_LIMIT } = require('../pagination');
+const { paginate, parsePaginationParams, DEFAULT_LIMIT, MAX_LIMIT } = require('../src/utilities/pagination');
 
 describe('Pagination — DashCaddy list endpoints', () => {
 

dashcaddy-api/__tests__/port-lock-manager.test.js

@@ -16,7 +16,7 @@ fs.unlinkSync.mockReturnValue(undefined);
 lockfile.lock.mockResolvedValue(jest.fn().mockResolvedValue());
 lockfile.check.mockResolvedValue(false);
 
-const portLockManager = require('../port-lock-manager');
+const portLockManager = require('../src/managers/port-lock-manager');
 
 beforeEach(() => {
   jest.clearAllMocks();

dashcaddy-api/__tests__/resource-monitor.test.js

@@ -12,7 +12,7 @@ fs.existsSync.mockReturnValue(false);
 fs.readFileSync.mockReturnValue('{}');
 fs.writeFileSync.mockReturnValue(undefined);
 
-const resourceMonitor = require('../resource-monitor');
+const resourceMonitor = require('../src/managers/resource-monitor');
 
 function makeStat(overrides = {}) {
   return {

dashcaddy-api/__tests__/routes/auth.totp.routes.test.js

@@ -0,0 +1,483 @@
+/**
+ * Integration tests for routes/auth/totp.js — the full TOTP auth flow.
+ *
+ * Covers the BACKLOG.md DC-006 acceptance criteria:
+ *   - no code      → 400 (ValidationError)
+ *   - wrong code   → 401 (AuthenticationError)
+ *   - valid TOTP   → 200 + session cookie + CSRF token
+ *   - check-session with valid session → 200 { authenticated: true }
+ *   - check-session without session    → 401 (AuthenticationError)
+ *
+ * Uses real otplib for code generation (so we exercise the actual TOTP math)
+ * but mocks credentialManager, session, totpConfig, and saveTotpConfig —
+ * because those modules own their own state machines (disk, cookies, file)
+ * that don't belong in a routes-level test.
+ *
+ * NOTE: this test exercises the src/ refactored module layout (DC-005).
+ * It depends on routes/auth/totp.js requiring ../../src/utilities/errors and
+ * ../../src/utils/responses — fix the relative paths in totp.js if they
+ * regress (see commit log for DC-006).
+ */
+
+const express = require('express');
+const request = require('supertest');
+const { authenticator } = require('otplib');
+
+// Quiet otplib's "Unescaped left brace" warning on Node 20+
+const origWarn = console.warn;
+beforeAll(() => {
+  console.warn = (...args) => {
+    const msg = args.join(' ');
+    if (msg.includes('Unescaped left brace')) return;
+    origWarn.apply(console, args);
+  };
+});
+afterAll(() => {
+  console.warn = origWarn;
+});
+
+// Minimal asyncHandler that catches errors into the express error chain
+function asyncHandler(fn) {
+  return (req, res, _next) => Promise.resolve(fn(req, res, _next)).catch(_next);
+}
+
+function createApp(depsOverride = {}) {
+  // In-memory secret store so credentialManager stays deterministic
+  const storedSecrets = new Map();
+  const credentialManager = {
+    store: jest.fn((key, value) => {
+      storedSecrets.set(key, value);
+      return Promise.resolve(true);
+    }),
+    retrieve: jest.fn((key) => Promise.resolve(storedSecrets.has(key) ? storedSecrets.get(key) : null)),
+    delete: jest.fn((key) => {
+      storedSecrets.delete(key);
+      return Promise.resolve(true);
+    }),
+    list: jest.fn(() => Promise.resolve(Array.from(storedSecrets.keys()))),
+  };
+
+  // Mutable TOTP config — tests mutate this to model setup → enable → disable
+  const totpConfig = {
+    enabled: false,
+    isSetUp: false,
+    sessionDuration: '24h',
+    secret: null, // matches main's optional backup-secret field
+  };
+
+  // Mock session context mirroring src/context/session.js
+  // isValid() is the knob — toggle it to test the auth-gate behavior
+  const sessionStore = new Map(); // ip → { expiresAt }
+  const session = {
+    create: jest.fn((req, duration) => {
+      const ip = session.getClientIP(req);
+      sessionStore.set(ip, { expiresAt: Date.now() + (duration === 'never' ? Number.MAX_SAFE_INTEGER : 3600000) });
+    }),
+    setCookie: jest.fn(),
+    clear: jest.fn((req) => {
+      const ip = session.getClientIP(req);
+      sessionStore.delete(ip);
+    }),
+    clearCookie: jest.fn(),
+    isValid: jest.fn((req) => {
+      const ip = session.getClientIP(req);
+      const entry = sessionStore.get(ip);
+      if (!entry) return false;
+      return entry.expiresAt > Date.now();
+    }),
+    // Test helper — pretend an IP has a valid session, regardless of req.ip
+    _grantSession: (ip = '127.0.0.1') => sessionStore.set(ip, { expiresAt: Date.now() + 3600000 }),
+    getClientIP: jest.fn((req) => req.ip || req.connection?.remoteAddress || '127.0.0.1'),
+    ipSessions: sessionStore,
+    durations: { '1h': 3600000, '24h': 86400000, '7d': 604800000, 'never': 0 },
+  };
+
+  const saveTotpConfig = jest.fn(() => Promise.resolve(true));
+  const renewCSRFToken = jest.fn(() => 'mock-csrf-token');
+  const log = {
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+    debug: jest.fn(),
+  };
+
+  const deps = {
+    authManager: {}, // unused by totp.js but required by the factory signature
+    credentialManager,
+    totpConfig,
+    saveTotpConfig,
+    session,
+    asyncHandler,
+    errorResponse: jest.fn(),
+    log,
+    renewCSRFToken,
+    ...depsOverride,
+  };
+
+  // Clear store between tests
+  deps._resetStore = () => {
+    storedSecrets.clear();
+    sessionStore.clear();
+    totpConfig.enabled = false;
+    totpConfig.isSetUp = false;
+    totpConfig.sessionDuration = '24h';
+    delete totpConfig.secret;
+  };
+
+  const totpRoutes = require('../../routes/auth/totp');
+  const app = express();
+  app.set('trust proxy', true); // so req.ip populates from X-Forwarded-For
+  app.use(express.json());
+  app.use('/api', totpRoutes(deps));
+  // Express error handler — surface status from thrown AppError
+  app.use((err, req, res, _next) => {
+    const status = err.statusCode || 500;
+    res.status(status).json({ success: false, error: err.message });
+  });
+
+  return { app, deps };
+}
+
+describe('TOTP Auth Routes — DC-006 Integration Test', () => {
+  let app;
+  let deps;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    ({ app, deps } = createApp());
+    authenticator.options = { window: 1 };
+  });
+
+  // Helper: derive a fresh secret + a valid current TOTP code for it
+  function freshSecret() {
+    const secret = authenticator.generateSecret();
+    const token = authenticator.generate(secret);
+    return { secret, token };
+  }
+
+  // ────────────────────────────────────────────────────────────────────
+  //  GET /api/totp/config
+  // ────────────────────────────────────────────────────────────────────
+  describe('GET /api/totp/config', () => {
+    it('returns current config (enabled=false, isSetUp=false by default)', async () => {
+      const res = await request(app).get('/api/totp/config');
+      expect(res.status).toBe(200);
+      expect(res.body.success).toBe(true);
+      expect(res.body.config).toEqual({
+        enabled: false,
+        sessionDuration: '24h',
+        isSetUp: false,
+      });
+    });
+
+    it('reflects state changes after setup completes', async () => {
+      deps.totpConfig.isSetUp = true;
+      deps.totpConfig.enabled = true;
+      const res = await request(app).get('/api/totp/config');
+      expect(res.status).toBe(200);
+      expect(res.body.config.isSetUp).toBe(true);
+      expect(res.body.config.enabled).toBe(true);
+    });
+  });
+
+  // ────────────────────────────────────────────────────────────────────
+  //  POST /api/totp/setup
+  // ────────────────────────────────────────────────────────────────────
+  describe('POST /api/totp/setup', () => {
+    it('generates a fresh secret + QR code when none is provided', async () => {
+      const res = await request(app).post('/api/totp/setup').send({});
+      expect(res.status).toBe(200);
+      expect(res.body.success).toBe(true);
+      expect(res.body.qrCode).toMatch(/^data:image\/png;base64,/);
+      expect(res.body.manualKey).toMatch(/^[A-Z2-7]{16,}$/);
+      expect(res.body.issuer).toBe('DashCaddy');
+      expect(res.body.imported).toBe(false);
+      // pending_secret should be stashed but totp.secret should NOT be active yet
+      expect(deps.credentialManager.store).toHaveBeenCalledWith('totp.pending_secret', res.body.manualKey);
+      expect(await deps.credentialManager.retrieve('totp.secret')).toBeNull();
+    });
+
+    it('accepts and normalizes a user-provided Base32 secret (0→O, 1→L, 8→B, lowercase→uppercase)', async () => {
+      const raw = 'JBSWY3DPEHPK3PXP'; // canonical example
+      const userInput = ' jbswy3dpehpk3pxp '; // spaces + lowercase
+      const res = await request(app).post('/api/totp/setup').send({ secret: userInput });
+      expect(res.status).toBe(200);
+      expect(res.body.manualKey).toBe(raw);
+      expect(res.body.imported).toBe(true);
+    });
+
+    it('rejects an obviously invalid secret (wrong alphabet)', async () => {
+      const res = await request(app).post('/api/totp/setup').send({ secret: 'NOT-VALID-BASE32!' });
+      expect(res.status).toBe(400);
+      expect(res.body.success).toBe(false);
+      expect(res.body.error).toMatch(/Invalid secret key format/);
+    });
+  });
+
+  // ────────────────────────────────────────────────────────────────────
+  //  POST /api/totp/verify-setup  (activates TOTP after setup)
+  // ────────────────────────────────────────────────────────────────────
+  describe('POST /api/totp/verify-setup', () => {
+    it('returns 400 when code is missing or malformed', async () => {
+      const res = await request(app).post('/api/totp/verify-setup').send({});
+      expect(res.status).toBe(400);
+      expect(res.body.error).toMatch(/Invalid code format/);
+    });
+
+    it('returns 400 when no pending setup exists', async () => {
+      const { token } = freshSecret();
+      const res = await request(app).post('/api/totp/verify-setup').send({ code: token });
+      expect(res.status).toBe(400);
+      expect(res.body.error).toMatch(/No pending TOTP setup/);
+    });
+
+    it('returns 401 when code is wrong', async () => {
+      const { secret } = freshSecret();
+      await request(app).post('/api/totp/setup').send({ secret });
+      const res = await request(app).post('/api/totp/verify-setup').send({ code: '000000' });
+      expect(res.status).toBe(401);
+      expect(res.body.error).toMatch(/DC-111/);
+    });
+
+    it('returns 200 + activates TOTP + creates session on valid code', async () => {
+      const { secret, token } = freshSecret();
+      await request(app).post('/api/totp/setup').send({ secret });
+      const res = await request(app).post('/api/totp/verify-setup').send({ code: token });
+      expect(res.status).toBe(200);
+      expect(res.body.success).toBe(true);
+      expect(res.body.message).toMatch(/TOTP enabled successfully/);
+
+      // TOTP config activated + persisted
+      expect(deps.totpConfig.isSetUp).toBe(true);
+      expect(deps.totpConfig.enabled).toBe(true);
+      expect(deps.saveTotpConfig).toHaveBeenCalled();
+
+      // pending_secret → totp.secret promotion, pending cleared
+      expect(await deps.credentialManager.retrieve('totp.secret')).toBe(secret);
+      expect(await deps.credentialManager.retrieve('totp.pending_secret')).toBeNull();
+
+      // Session established
+      expect(deps.session.create).toHaveBeenCalled();
+      expect(deps.session.setCookie).toHaveBeenCalled();
+      // Note: renewCSRFToken is only called on /totp/verify (login), not /totp/verify-setup
+    });
+  });
+
+  // ────────────────────────────────────────────────────────────────────
+  //  POST /api/totp/verify  (login flow — TOTP already configured)
+  // ────────────────────────────────────────────────────────────────────
+  describe('POST /api/totp/verify (login)', () => {
+    async function setupTOTP() {
+      const { secret, token } = freshSecret();
+      await request(app).post('/api/totp/setup').send({ secret });
+      await request(app).post('/api/totp/verify-setup').send({ code: token });
+      // Reset mocks but keep config/secret state for the test
+      jest.clearAllMocks();
+      return secret;
+    }
+
+    it('returns 400 when code is missing', async () => {
+      const res = await request(app).post('/api/totp/verify').send({});
+      expect(res.status).toBe(400);
+      expect(res.body.error).toMatch(/Invalid code format/);
+    });
+
+    it('returns 400 when TOTP is not enabled', async () => {
+      const res = await request(app).post('/api/totp/verify').send({ code: '123456' });
+      expect(res.status).toBe(400);
+      expect(res.body.error).toMatch(/TOTP is not enabled/);
+    });
+
+    it('returns 401 when code is wrong (TOTP active)', async () => {
+      await setupTOTP();
+      const res = await request(app).post('/api/totp/verify').send({ code: '000000' });
+      expect(res.status).toBe(401);
+      expect(res.body.error).toMatch(/DC-111/);
+    });
+
+    it('returns 200 + creates new session + rotates CSRF on valid code (BACKLOG: "valid TOTP → session token → authenticated request succeeds")', async () => {
+      const secret = await setupTOTP();
+      const token = authenticator.generate(secret);
+      const res = await request(app).post('/api/totp/verify').send({ code: token });
+      expect(res.status).toBe(200);
+      expect(res.body.success).toBe(true);
+      expect(res.body.message).toMatch(/Authenticated successfully/);
+      expect(res.body.csrfToken).toBe('mock-csrf-token');
+      expect(deps.session.create).toHaveBeenCalled();
+      expect(deps.session.setCookie).toHaveBeenCalled();
+      expect(deps.renewCSRFToken).toHaveBeenCalled();
+    });
+  });
+
+  // ────────────────────────────────────────────────────────────────────
+  //  GET /api/totp/check-session  (the auth gate Caddy calls)
+  // ────────────────────────────────────────────────────────────────────
+  describe('GET /api/totp/check-session', () => {
+    it('always returns 200 when TOTP is not enabled (passthrough)', async () => {
+      const res = await request(app).get('/api/totp/check-session');
+      expect(res.status).toBe(200);
+      expect(res.body).toEqual({ authenticated: true });
+    });
+
+    it('always returns 200 when sessionDuration is "never" (passthrough)', async () => {
+      deps.totpConfig.enabled = true;
+      deps.totpConfig.isSetUp = true;
+      deps.totpConfig.sessionDuration = 'never';
+      const res = await request(app).get('/api/totp/check-session');
+      expect(res.status).toBe(200);
+      expect(res.body).toEqual({ authenticated: true });
+    });
+
+    it('returns 401 when no session exists (BACKLOG: "no token → 401")', async () => {
+      deps.totpConfig.enabled = true;
+      deps.totpConfig.isSetUp = true;
+      deps.totpConfig.sessionDuration = '24h';
+      // session.isValid returns false because sessionStore is empty
+      const res = await request(app).get('/api/totp/check-session');
+      expect(res.status).toBe(401);
+      expect(res.body.error).toMatch(/Session expired or invalid/);
+      // Cache-control headers must be set to avoid Caddy auth loops
+      expect(res.headers['cache-control']).toMatch(/no-store/);
+    });
+
+    it('returns 200 { authenticated: true } when session is valid (BACKLOG: "authenticated request succeeds")', async () => {
+      deps.totpConfig.enabled = true;
+      deps.totpConfig.isSetUp = true;
+      deps.totpConfig.sessionDuration = '24h';
+      // Pre-populate the session store as if verify already ran
+      deps.session._grantSession('127.0.0.1');
+      const res = await request(app).get('/api/totp/check-session').set('X-Forwarded-For', '127.0.0.1');
+      expect(res.status).toBe(200);
+      expect(res.body).toEqual({ authenticated: true });
+    });
+  });
+
+  // ────────────────────────────────────────────────────────────────────
+  //  POST /api/totp/disable
+  // ────────────────────────────────────────────────────────────────────
+  describe('POST /api/totp/disable', () => {
+    async function setupTOTP() {
+      const { secret, token } = freshSecret();
+      await request(app).post('/api/totp/setup').send({ secret });
+      await request(app).post('/api/totp/verify-setup').send({ code: token });
+      jest.clearAllMocks();
+      return secret;
+    }
+
+    it('returns 400 when TOTP is active but no code is provided', async () => {
+      await setupTOTP();
+      const res = await request(app).post('/api/totp/disable').send({});
+      expect(res.status).toBe(400);
+      expect(res.body.error).toMatch(/valid TOTP code is required/);
+    });
+
+    it('returns 401 when code is wrong', async () => {
+      await setupTOTP();
+      const res = await request(app).post('/api/totp/disable').send({ code: '000000' });
+      expect(res.status).toBe(401);
+      expect(res.body.error).toMatch(/DC-111/);
+    });
+
+    it('returns 200 + clears TOTP state on valid code', async () => {
+      const secret = await setupTOTP();
+      const code = authenticator.generate(secret);
+      const res = await request(app).post('/api/totp/disable').send({ code });
+      expect(res.status).toBe(200);
+      expect(res.body.success).toBe(true);
+
+      // TOTP disabled, secrets cleared, session cleared
+      expect(deps.totpConfig.enabled).toBe(false);
+      expect(deps.totpConfig.isSetUp).toBe(false);
+      expect(deps.totpConfig.sessionDuration).toBe('never');
+      expect(await deps.credentialManager.retrieve('totp.secret')).toBeNull();
+      expect(await deps.credentialManager.retrieve('totp.pending_secret')).toBeNull();
+      expect(deps.session.clear).toHaveBeenCalled();
+      expect(deps.session.clearCookie).toHaveBeenCalled();
+      expect(deps.saveTotpConfig).toHaveBeenCalled();
+    });
+  });
+
+  // ────────────────────────────────────────────────────────────────────
+  //  POST /api/totp/config  (session duration change)
+  // ────────────────────────────────────────────────────────────────────
+  describe('POST /api/totp/config (update settings)', () => {
+    it('updates sessionDuration with a valid value', async () => {
+      const res = await request(app).post('/api/totp/config').send({ sessionDuration: '7d' });
+      expect(res.status).toBe(200);
+      expect(res.body.config.sessionDuration).toBe('7d');
+      expect(deps.saveTotpConfig).toHaveBeenCalled();
+    });
+
+    it('rejects an invalid sessionDuration', async () => {
+      const res = await request(app).post('/api/totp/config').send({ sessionDuration: '99y' });
+      expect(res.status).toBe(400);
+      expect(res.body.error).toMatch(/Invalid session duration/);
+    });
+
+    it('setting sessionDuration to "never" disables TOTP', async () => {
+      deps.totpConfig.enabled = true;
+      deps.totpConfig.isSetUp = true;
+      const res = await request(app).post('/api/totp/config').send({ sessionDuration: 'never' });
+      expect(res.status).toBe(200);
+      expect(deps.totpConfig.sessionDuration).toBe('never');
+      expect(deps.totpConfig.enabled).toBe(false);
+    });
+  });
+
+  // ────────────────────────────────────────────────────────────────────
+  //  End-to-end flow (BACKLOG: "Cover the full /api/auth/check → session → endpoint flow")
+  // ────────────────────────────────────────────────────────────────────
+  describe('End-to-end: setup → login → check-session → disable', () => {
+    it('walks the full BACKLOG DC-006 flow', async () => {
+      // 1. Setup — generate a fresh secret
+      const setupRes = await request(app).post('/api/totp/setup').send({});
+      expect(setupRes.status).toBe(200);
+      const secret = setupRes.body.manualKey;
+      const setupCode = authenticator.generate(secret);
+
+      // 2. Verify-setup — activate TOTP
+      const verifySetupRes = await request(app).post('/api/totp/verify-setup').send({ code: setupCode });
+      expect(verifySetupRes.status).toBe(200);
+      expect(deps.totpConfig.isSetUp).toBe(true);
+
+      // 3. Simulate session expiry by clearing the store
+      deps.session.ipSessions.clear();
+
+      // 4. Re-login via /totp/verify (the "login" path)
+      const loginCode = authenticator.generate(secret);
+      const loginRes = await request(app).post('/api/totp/verify').send({ code: loginCode });
+      expect(loginRes.status).toBe(200);
+      expect(loginRes.body.csrfToken).toBeDefined();
+
+      // 5. Check-session — should now be authenticated (the BACKLOG "→ endpoint succeeds" step)
+      const checkRes = await request(app).get('/api/totp/check-session');
+      expect(checkRes.status).toBe(200);
+      expect(checkRes.body).toEqual({ authenticated: true });
+
+      // 6. Logout / disable
+      const disableCode = authenticator.generate(secret);
+      const disableRes = await request(app).post('/api/totp/disable').send({ code: disableCode });
+      expect(disableRes.status).toBe(200);
+
+      // 7. After disable, check-session should be passthrough (TOTP off)
+      const afterRes = await request(app).get('/api/totp/check-session');
+      expect(afterRes.status).toBe(200);
+      expect(afterRes.body).toEqual({ authenticated: true });
+    });
+
+    it('proves otplib is real (not stubbed) by using a totally bogus code', async () => {
+      // Sanity check that the test harness is using real otplib, not a stub.
+      // otplib 12.0.1's authenticator.generate(secret) does not accept a {time} option
+      // (the signature is fixed to current-time TOTP), so a "stale code" test isn't
+      // reproducible across runs. Instead, we verify otplib rejects a code that is
+      // syntactically valid (6 digits) but doesn't match the live TOTP slot.
+      const secret = authenticator.generateSecret();
+      await request(app).post('/api/totp/setup').send({ secret });
+      // Generate the real current code, then mutate it — must be rejected
+      const realCode = authenticator.generate(secret);
+      const tampered = realCode === '000000' ? '111111' : '000000';
+      const res = await request(app).post('/api/totp/verify-setup').send({ code: tampered });
+      expect(res.status).toBe(401);
+    });
+  });
+});

dashcaddy-api/__tests__/routes/containers.routes.test.js

@@ -9,7 +9,7 @@ function buildApp(mockDeps) {
   const app = express();
   app.use(express.json());
 
-  const { errorMiddleware } = require('../../error-handler');
+  const { errorMiddleware } = require('../../src/utilities/error-handler');
   const containersRouteFactory = require('../../routes/containers');
   app.use('/api/containers', containersRouteFactory(mockDeps));
   app.use(errorMiddleware);

dashcaddy-api/__tests__/routes/health.routes.test.js

@@ -52,21 +52,21 @@ jest.mock('../../platform-paths', () => ({
 }));
 
 // Mock fs-helpers.exists
-jest.mock('../../fs-helpers', () => ({
+jest.mock('../../src/utilities/fs-helpers', () => ({
   exists: jest.fn().mockResolvedValue(true),
 }));
 
-jest.mock('../../url-resolver', () => ({
+jest.mock('../../src/utilities/url-resolver', () => ({
   resolveServiceUrl: jest.fn((id) => `https://${id}.test`),
 }));
 
-jest.mock('../../pagination', () => ({
+jest.mock('../../src/utilities/pagination', () => ({
   paginate: jest.fn((data, params) => ({ data, pagination: null })),
   parsePaginationParams: jest.fn(() => null),
 }));
 
-const { exists } = require('../../fs-helpers');
-const { resolveServiceUrl } = require('../../url-resolver');
+const { exists } = require('../../src/utilities/fs-helpers');
+const { resolveServiceUrl } = require('../../src/utilities/url-resolver');
 const { execSync } = require('child_process');
 
 describe('Health Routes', () => {

dashcaddy-api/__tests__/routes/services.routes.test.js

@@ -9,27 +9,27 @@ function asyncHandler(fn) {
 }
 
 // Mock modules that services.js requires at top-level
-jest.mock('../../constants', () => ({
+jest.mock('../../src/utilities/constants', () => ({
   APP: { USER_AGENTS: { PROBE: 'DashCaddy/1.0' } },
   REGEX: { SUBDOMAIN: /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/ },
   TIMEOUTS: { DEFAULT: 10000 },
   HTTP_STATUS: { OK: 200, CREATED: 201, NO_CONTENT: 204, BAD_REQUEST: 400, UNAUTHORIZED: 401, FORBIDDEN: 403, NOT_FOUND: 404, CONFLICT: 409, INTERNAL_ERROR: 500 }
 }));
 
-jest.mock('../../input-validator', () => ({
+jest.mock('../../src/security/input-validator', () => ({
   validateServiceConfig: jest.fn(),
   isValidPort: jest.fn(p => p >= 1 && p <= 65535),
 }));
 
-jest.mock('../../fs-helpers', () => ({
+jest.mock('../../src/utilities/fs-helpers', () => ({
   exists: jest.fn().mockResolvedValue(true),
 }));
 
-jest.mock('../../url-resolver', () => ({
+jest.mock('../../src/utilities/url-resolver', () => ({
   resolveServiceUrl: jest.fn((id) => `https://${id}.test`),
 }));
 
-jest.mock('../../pagination', () => ({
+jest.mock('../../src/utilities/pagination', () => ({
   paginate: jest.fn((data, params) => ({ data, pagination: null })),
   parsePaginationParams: jest.fn(() => null),
 }));
@@ -45,8 +45,8 @@ jest.mock('../../src/utils/responses', () => ({
 
 // errors module NOT mocked — used for real ValidationError/NotFoundError/ConflictError
 
-const { exists } = require('../../fs-helpers');
-const { validateServiceConfig } = require('../../input-validator');
+const { exists } = require('../../src/utilities/fs-helpers');
+const { validateServiceConfig } = require('../../src/security/input-validator');
 
 function createApp(depsOverride = {}) {
   const defaultDeps = {
@@ -103,12 +103,12 @@ describe('Services Routes', () => {
   });
 
   describe('GET /api/services', () => {
-    it('returns empty array when no services file', async () => {
+    it('returns empty services array (enveloped) when no services file', async () => {
       exists.mockResolvedValue(false);
       const { app } = createApp();
       const res = await request(app).get('/api/services');
       expect(res.status).toBe(200);
-      expect(res.body).toEqual([]);
+      expect(res.body).toEqual({ success: true, services: [] });
     });
 
     it('returns services list', async () => {
@@ -450,7 +450,7 @@ describe('Services Routes', () => {
     });
 
     it('rejects invalid port', async () => {
-      const { isValidPort } = require('../../input-validator');
+      const { isValidPort } = require('../../src/security/input-validator');
       isValidPort.mockReturnValue(false);
       const { app } = createApp();
       const res = await request(app)

dashcaddy-api/__tests__/ssl-monitor.test.js

@@ -0,0 +1,203 @@
+/**
+ * Smoke tests for ssl-monitor.js
+ * Verifies SSLMonitor loads, exposes the expected interface, can check
+ * certificates via mocked TLS, manage state, and persist cache.
+ */
+
+jest.mock('tls', () => ({
+  connect: jest.fn(),
+}));
+
+jest.mock('../src/utilities/fs-helpers', () => ({
+  readJsonFile: jest.fn().mockResolvedValue(null),
+  writeJsonFile: jest.fn().mockResolvedValue(undefined),
+}));
+
+const tls = require('tls');
+const fsHelpers = require('../src/utilities/fs-helpers');
+const SSLMonitor = require('../src/monitoring/ssl-monitor');
+
+function makeSocket({ cert = null, error = null } = {}) {
+  const { EventEmitter } = require('events');
+  const socket = new EventEmitter();
+  socket.destroy = jest.fn();
+  socket.getPeerCertificate = jest.fn(() => cert);
+  socket.setTimeout = jest.fn();
+
+  // Simulate 'connect' on next tick (or 'error')
+  process.nextTick(() => {
+    if (error) socket.emit('error', error);
+  });
+
+  return socket;
+}
+
+describe('SSLMonitor', () => {
+  let monitor;
+  const fakeStateManager = {
+    read: jest.fn().mockResolvedValue([]),
+  };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    fsHelpers.readJsonFile.mockResolvedValue(null);
+    fsHelpers.writeJsonFile.mockResolvedValue(undefined);
+    fakeStateManager.read.mockResolvedValue([]);
+
+    monitor = new SSLMonitor({
+      log: { error: jest.fn(), info: jest.fn(), warn: jest.fn() },
+      servicesStateManager: fakeStateManager,
+      siteConfig: {},
+      buildServiceUrl: id => `https://${id}.sami`,
+      notification: null,
+    });
+  });
+
+  afterEach(() => {
+    monitor.stop();
+  });
+
+  test('initializes with empty maps and default config', () => {
+    expect(monitor.certStatus).toBeInstanceOf(Map);
+    expect(monitor.notifiedThresholds).toBeInstanceOf(Map);
+    expect(monitor.hostnameToServiceId).toBeInstanceOf(Map);
+    expect(monitor.intervalHandle).toBeNull();
+    expect(monitor.config.enabled).toBe(true);
+    expect(typeof monitor.config.intervalMs).toBe('number');
+  });
+
+  test('getConfig returns a copy of the current config', () => {
+    const cfg = monitor.getConfig();
+    expect(cfg).toEqual(monitor.config);
+    cfg.enabled = false;
+    // The internal config must not be mutated
+    expect(monitor.config.enabled).toBe(true);
+  });
+
+  test('updateConfig updates enabled and intervalMs', () => {
+    monitor.updateConfig({ enabled: false, intervalMs: 60000 });
+    expect(monitor.config.enabled).toBe(false);
+    expect(monitor.config.intervalMs).toBe(60000);
+  });
+
+  test('updateConfig rejects intervalMs below 60000', () => {
+    const original = monitor.config.intervalMs;
+    monitor.updateConfig({ intervalMs: 1000 });
+    expect(monitor.config.intervalMs).toBe(original);
+  });
+
+  test('getStatus returns an empty object when no checks have run', () => {
+    expect(monitor.getStatus()).toEqual({});
+  });
+
+  test('getServiceCertStatus returns null for unknown service', () => {
+    expect(monitor.getServiceCertStatus('unknown-svc')).toBeNull();
+  });
+
+  test('checkCert rejects when peer cert is empty', async () => {
+    tls.connect.mockImplementation((_opts, onConnect) => {
+      const sock = makeSocket({ cert: {} });
+      // Simulate immediate 'connect'
+      setImmediate(() => onConnect && onConnect());
+      return sock;
+    });
+
+    await expect(monitor.checkCert('empty.sami')).rejects.toThrow(/No certificate/);
+  });
+
+  test('checkCert resolves with cert details on success', async () => {
+    const futureDate = new Date(Date.now() + 60 * 24 * 60 * 60 * 1000); // +60d
+    const validTo = futureDate.toUTCString();
+    tls.connect.mockImplementation((_opts, onConnect) => {
+      const sock = makeSocket({
+        cert: {
+          subject: { CN: 'test.sami' },
+          issuer: { O: "Sami's CA" },
+          valid_from: new Date(Date.now() - 1000 * 60 * 60 * 24 * 30).toUTCString(),
+          valid_to: validTo,
+          fingerprint: 'AA:BB:CC',
+        },
+      });
+      setImmediate(() => onConnect && onConnect());
+      return sock;
+    });
+
+    const result = await monitor.checkCert('test.sami', 443);
+    expect(result.hostname).toBe('test.sami');
+    expect(result.port).toBe(443);
+    expect(result.subject).toBe('test.sami');
+    expect(result.daysRemaining).toBeGreaterThan(0);
+    expect(typeof result.isExpiring).toBe('boolean');
+    expect(typeof result.checkedAt).toBe('string');
+  });
+
+  test('checkCert rejects with TLS error event', async () => {
+    tls.connect.mockImplementation(() => {
+      const sock = makeSocket({ error: new Error('TLS boom') });
+      return sock;
+    });
+    await expect(monitor.checkCert('broken.sami')).rejects.toThrow(/TLS/);
+  });
+
+  test('checkAll returns empty status when no services configured', async () => {
+    const status = await monitor.checkAll();
+    expect(status).toEqual({});
+  });
+
+  test('checkAll handles HTTPS services and stores results', async () => {
+    fakeStateManager.read.mockResolvedValue([
+      { id: 'web', name: 'Web', url: 'https://web.sami' },
+    ]);
+    const futureDate = new Date(Date.now() + 60 * 24 * 60 * 60 * 1000);
+    tls.connect.mockImplementation((_opts, onConnect) => {
+      const sock = makeSocket({
+        cert: {
+          subject: { CN: 'web.sami' },
+          issuer: { O: "Sami's CA" },
+          valid_from: new Date().toUTCString(),
+          valid_to: futureDate.toUTCString(),
+          fingerprint: 'AA:BB:CC',
+        },
+      });
+      setImmediate(() => onConnect && onConnect());
+      return sock;
+    });
+
+    const status = await monitor.checkAll();
+    expect(status['web.sami']).toBeDefined();
+    expect(status['web.sami'].hostname).toBe('web.sami');
+    expect(monitor.getServiceCertStatus('web')).not.toBeNull();
+  });
+
+  test('start() schedules periodic checks and stop() clears them', () => {
+    jest.useFakeTimers();
+    const originalCheckAll = monitor.checkAll.bind(monitor);
+    monitor.checkAll = jest.fn().mockResolvedValue(undefined);
+    monitor.start(120000);
+    expect(monitor.intervalHandle).not.toBeNull();
+    monitor.stop();
+    expect(monitor.intervalHandle).toBeNull();
+    monitor.checkAll = originalCheckAll;
+    jest.useRealTimers();
+  });
+
+  test('_saveCache and _loadCache round-trip via fs-helpers', async () => {
+    await monitor._saveCache();
+    expect(fsHelpers.writeJsonFile).toHaveBeenCalled();
+
+    fsHelpers.readJsonFile.mockResolvedValue({
+      lastChecked: new Date().toISOString(),
+      certs: { 'a.sami': { hostname: 'a.sami', daysRemaining: 30 } },
+      hostnameToServiceId: { 'a.sami': 'svc-a' },
+    });
+    const fresh = new SSLMonitor({
+      log: { error: jest.fn(), info: jest.fn(), warn: jest.fn() },
+      servicesStateManager: fakeStateManager,
+      siteConfig: {},
+      buildServiceUrl: id => `https://${id}.sami`,
+    });
+    await fresh._loadCache();
+    expect(fresh.certStatus.get('a.sami')).toBeDefined();
+    expect(fresh.hostnameToServiceId.get('a.sami')).toBe('svc-a');
+  });
+});

dashcaddy-api/__tests__/state-manager.test.js

@@ -11,7 +11,7 @@ jest.mock('fs', () => ({
 
 const lockfile = require('proper-lockfile');
 const fs = require('fs');
-const StateManager = require('../state-manager');
+const StateManager = require('../src/managers/state-manager');
 
 describe('StateManager', () => {
   let sm;

dashcaddy-api/__tests__/update-manager.test.js

@@ -22,7 +22,7 @@ fs.existsSync.mockReturnValue(false);
 fs.readFileSync.mockReturnValue('{}');
 fs.writeFileSync.mockReturnValue(undefined);
 
-const updateManager = require('../update-manager');
+const updateManager = require('../src/managers/update-manager');
 
 // Helper to create a fake https request that responds with a given statusCode/headers/body
 function mockHttpsResponse({ statusCode = 200, headers = {}, body = '' } = {}) {

dashcaddy-api/__tests__/url-resolver.test.js

@@ -1,4 +1,4 @@
-const { resolveServiceUrl } = require('../url-resolver');
+const { resolveServiceUrl } = require('../src/utilities/url-resolver');
 
 describe('URL Resolver — DashCaddy service URL resolution', () => {
   const buildServiceUrl = jest.fn(id => `https://${id}.sami`);

dashcaddy-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dashcaddy-api",
-  "version": "1.13.3",
+  "version": "1.13.4",
   "description": "DashCaddy API server - Dashboard backend for Docker, Caddy & DNS management",
   "main": "server.js",
   "scripts": {

dashcaddy-api/routes/apps/compose.js

@@ -1,8 +1,9 @@
 const express = require('express');
 const yaml = require('js-yaml');
-const { DOCKER, REGEX } = require('../../constants');
-const { ValidationError } = require('../../errors');
+const { DOCKER, REGEX } = require('../../../src/utilities/constants');
+const { ValidationError } = require('../../../src/utilities/errors');
 const platformPaths = require('../../platform-paths');
+const { ok } = require('../src/utils/responses');
 
 /**
  * Docker Compose import routes
@@ -162,7 +163,7 @@ module.exports = function({ docker, caddy, servicesStateManager, portLockManager
     }
     const name = (stackName || 'stack').replace(/[^a-zA-Z0-9_-]/g, '').substring(0, 32) || 'stack';
     const result = parseCompose(yamlStr, name);
-    res.json({ success: true, ...result });
+    ok(res, { ...result });
   }, 'compose-import'));
 
   // POST /deploy-compose — deploy parsed services
@@ -300,7 +301,7 @@ module.exports = function({ docker, caddy, servicesStateManager, portLockManager
       results.push({ type: 'container', name: svc.name, status: 'skipped', reason: svc.reason });
     }
 
-    res.json({ success: true, results, stackName: stackName || prefix });
+    ok(res, { results, stackName: stackName || prefix });
   }, 'compose-deploy'));
 
   // DELETE /compose-stack/:stackName — remove an entire stack
@@ -329,7 +330,7 @@ module.exports = function({ docker, caddy, servicesStateManager, portLockManager
     });
     await servicesStateManager.update(data => { data.services = updated; });
 
-    res.json({ success: true, removed, count: removed.length });
+    ok(res, { removed, count: removed.length });
   }, 'compose-stack-delete'));
 
   return router;

dashcaddy-api/routes/apps/deploy.js

@@ -2,12 +2,13 @@ const express = require('express');
 const fsp = require('fs').promises;
 const path = require('path');
 const validatorLib = require('validator');
-const { REGEX, DOCKER } = require('../../constants');
-const { isValidPort } = require('../../input-validator');
-const { exists } = require('../../fs-helpers');
+const { REGEX, DOCKER } = require('../../../src/utilities/constants');
+const { isValidPort } = require('../../../src/security/input-validator');
+const { exists } = require('../../../src/utilities/fs-helpers');
 const platformPaths = require('../../platform-paths');
-const { ValidationError } = require('../../errors');
-const { logError } = require('../../src/utils/logging');
+const { ValidationError } = require('../../../src/utilities/errors');
+const { logError } = require('../src/utils/logging');
+const { ok } = require('../src/utils/responses');
 /**
  * Apps deployment routes factory
  * @param {Object} deps - Explicit dependencies
@@ -243,9 +244,9 @@ module.exports = function({ docker, caddy, credentialManager, servicesStateManag
     if (!template) throw new ValidationError('Invalid app template');
     const existingContainer = await helpers.findExistingContainerByImage(template);
     if (existingContainer) {
-      res.json({ success: true, exists: true, container: existingContainer, message: `Found existing ${template.name} container: ${existingContainer.name}` });
+      ok(res, { exists: true, container: existingContainer, message: `Found existing ${template.name} container: ${existingContainer.name}` });
     } else {
-      res.json({ success: true, exists: false, message: `No existing ${template.name} container found` });
+      ok(res, { exists: false, message: `No existing ${template.name} container found` });
     }
   }, 'check-existing'));
 

dashcaddy-api/routes/apps/helpers.js

@@ -2,8 +2,8 @@ const fs = require('fs');
 const fsp = require('fs').promises;
 const path = require('path');
 const crypto = require('crypto');
-const { REGEX, DOCKER } = require('../../constants');
-const { exists } = require('../../fs-helpers');
+const { REGEX, DOCKER } = require('../../../src/utilities/constants');
+const { exists } = require('../../../src/utilities/fs-helpers');
 const platformPaths = require('../../platform-paths');
 
 /**

dashcaddy-api/routes/apps/removal.js

@@ -1,6 +1,7 @@
 const express = require('express');
-const { exists } = require('../../fs-helpers');
-const { logError } = require('../../src/utils/logging');
+const { exists } = require('../../../src/utilities/fs-helpers');
+const { logError } = require('../src/utils/logging');
+const { ok } = require('../src/utils/responses');
 
 module.exports = function({
   docker, caddy, servicesStateManager, asyncHandler, log, helpers,
@@ -135,7 +136,7 @@ module.exports = function({
         results.service = error.message;
       }
 
-      res.json({ success: true, message: `App ${appId} removal completed`, results });
+      ok(res, { message: `App ${appId} removal completed`, results });
     } catch (error) {
       await logError('app-removal', error);
       errorResponse(res, 500, ctx.safeErrorMessage(error), { results });

dashcaddy-api/routes/apps/restore.js

@@ -1,7 +1,8 @@
 const express = require('express');
 const path = require('path');
 const fs = require('fs');
-const { DOCKER } = require('../../constants');
+const { DOCKER } = require('../../../src/utilities/constants');
+const { ok, validationError, notFound, errorResponse } = require('../../../src/utilities/responses');
 
 const DEFAULT_BACKUP_DIR = process.env.BACKUP_DIR || path.join(__dirname, '..', 'backups');
 
@@ -47,7 +48,7 @@ module.exports = function({ docker, caddy, servicesStateManager, asyncHandler, e
     }
 
     const result = await restoreService(service);
-    res.json({ success: true, result });
+    ok(res, { result });
   }, 'apps-restore'));
 
   /**
@@ -59,8 +60,7 @@ module.exports = function({ docker, caddy, servicesStateManager, asyncHandler, e
     const restoreable = services.filter(s => s.deploymentManifest);
 
     if (restoreable.length === 0) {
-      return res.json({
-        success: true,
+      return ok(res, {
         message: 'No services have deployment manifests to restore',
         results: []
       });
@@ -85,8 +85,7 @@ module.exports = function({ docker, caddy, servicesStateManager, asyncHandler, e
     const skipped = results.filter(r => r.status === 'skipped').length;
     const failed = results.filter(r => r.status === 'failed').length;
 
-    res.json({
-      success: true,
+    ok(res, {
       message: `Restore complete: ${succeeded} restored, ${skipped} skipped, ${failed} failed`,
       results
     });
@@ -123,7 +122,7 @@ module.exports = function({ docker, caddy, servicesStateManager, asyncHandler, e
       status.push(entry);
     }
 
-    res.json({ success: true, services: status });
+    ok(res, { services: status });
   }, 'apps-restore-status'));
 
   // ==================== POINT-IN-TIME RESTORE (BACKUP FILE BASED) ====================
@@ -174,8 +173,7 @@ module.exports = function({ docker, caddy, servicesStateManager, asyncHandler, e
     // Sort by timestamp descending (newest first)
     files.sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp));
 
-    res.json({
-      success: true,
+    ok(res, {
       appId,
       isBackupFile: true,
       files,
@@ -190,12 +188,12 @@ module.exports = function({ docker, caddy, servicesStateManager, asyncHandler, e
 
     // Security: prevent path traversal
     if (filename.includes('..') || filename.includes('/') || filename.includes('\\')) {
-      return res.status(400).json({ success: false, error: 'Invalid filename' });
+      return validationError(res, 'Invalid filename');
     }
 
     const filepath = path.join(DEFAULT_BACKUP_DIR, filename);
     if (!fs.existsSync(filepath)) {
-      return res.status(404).json({ success: false, error: `Backup file not found: ${filename}` });
+      return notFound(res, `Backup file not found: ${filename}`);
     }
 
     try {
@@ -207,7 +205,7 @@ module.exports = function({ docker, caddy, servicesStateManager, asyncHandler, e
         try {
           fileData = await backupManager.decryptBackup(fileData, encryptionKey);
         } catch (err) {
-          return res.status(400).json({ success: false, error: 'Failed to decrypt backup: ' + err.message });
+          return validationError(res, 'Failed to decrypt backup: ' + err.message);
         }
       }
 
@@ -264,8 +262,7 @@ module.exports = function({ docker, caddy, servicesStateManager, asyncHandler, e
           // Cleanup temp dir
           fs.rmSync(tempDir, { recursive: true, force: true });
 
-          res.json({
-            success: true,
+          ok(res, {
             isBackupFile: true,
             restored: {
               services: !!restoreData.services,
@@ -277,8 +274,7 @@ module.exports = function({ docker, caddy, servicesStateManager, asyncHandler, e
         } else {
           // Preview mode
           fs.rmSync(tempDir, { recursive: true, force: true });
-          res.json({
-            success: true,
+          ok(res, {
             isBackupFile: true,
             preview: true,
             filename,
@@ -296,7 +292,7 @@ module.exports = function({ docker, caddy, servicesStateManager, asyncHandler, e
         throw err;
       }
     } catch (err) {
-      res.status(500).json({ success: false, error: err.message });
+      errorResponse(res, 500, err.message);
     }
   }, 'apps-revert'));
 

dashcaddy-api/routes/apps/templates.js

@@ -1,5 +1,5 @@
 const express = require('express');
-const { exists } = require('../../fs-helpers');
+const { exists } = require('../../../src/utilities/fs-helpers');
 /**
  * Apps templates routes factory
  * @param {Object} deps - Explicit dependencies
@@ -19,7 +19,8 @@ const { exists } = require('../../fs-helpers');
  * @param {string} deps.SERVICES_FILE - Services file path
  * @returns {express.Router}
  */
-const { REGEX } = require('../../constants');
+const { REGEX } = require('../../../src/utilities/constants');
+const { ok } = require('../src/utils/responses');
 
 module.exports = function({
   servicesStateManager, asyncHandler, helpers,
@@ -42,8 +43,7 @@ module.exports = function({
 
   // Get available app templates
   router.get('/templates', asyncHandler(async (req, res) => {
-    res.json({
-      success: true,
+    ok(res, {
       templates: ctx.APP_TEMPLATES,
       categories: ctx.TEMPLATE_CATEGORIES,
       difficultyLevels: ctx.DIFFICULTY_LEVELS
@@ -55,10 +55,10 @@ module.exports = function({
     const { appId } = req.params;
     const template = ctx.APP_TEMPLATES[appId];
     if (!template) {
-      const { NotFoundError } = require('../../errors');
+      const { NotFoundError } = require('../../../src/utilities/errors');
       throw new NotFoundError('App template');
     }
-    res.json({ success: true, template });
+    ok(res, { template });
   }, 'apps-template-detail'));
 
   // Check port availability
@@ -80,7 +80,7 @@ module.exports = function({
     const usedPorts = await docker.getUsedPorts();
     for (let port = basePort; port < basePort + maxAttempts; port++) {
       if (!usedPorts.has(port)) {
-        res.json({ success: true, suggestedPort: port, basePort });
+        ok(res, { suggestedPort: port, basePort });
         return;
       }
     }
@@ -90,7 +90,7 @@ module.exports = function({
   // Update subdomain for deployed app
   router.post('/update-subdomain', asyncHandler(async (req, res) => {
     const { serviceId, oldSubdomain, newSubdomain, containerId, ip } = req.body;
-    const { ValidationError } = require('../../errors');
+    const { ValidationError } = require('../../../src/utilities/errors');
 
     if (!oldSubdomain || typeof oldSubdomain !== 'string') {
       throw new ValidationError('oldSubdomain is required');
@@ -170,8 +170,7 @@ module.exports = function({
       log.warn('deploy', 'Service update warning', { error: error.message || String(error) });
     }
 
-    res.json({
-      success: true,
+    ok(res, {
       message: `Subdomain updated: ${oldSubdomain} -> ${newSubdomain}`,
       newUrl: `https://${ctx.buildDomain(newSubdomain)}`,
       results

dashcaddy-api/routes/arr/config.js

@@ -1,8 +1,9 @@
 const express = require('express');
-const { APP_PORTS, ARR_SERVICES } = require('../../constants');
-const { validateURL, validateToken } = require('../../input-validator');
-const { ValidationError, AuthenticationError, NotFoundError } = require('../../errors');
-const { logError } = require('../../src/utils/logging');
+const { APP_PORTS, ARR_SERVICES } = require('../../../src/utilities/constants');
+const { validateURL, validateToken } = require('../../../src/security/input-validator');
+const { ValidationError, AuthenticationError, NotFoundError } = require('../../../src/utilities/errors');
+const { logError } = require('../src/utils/logging');
+const { ok, successMessage } = require('../src/utils/responses');
 
 /**
  * Arr configuration routes factory
@@ -258,11 +259,7 @@ module.exports = function(ctx) {
         const version = service === 'plex' ? data.MediaContainer?.version : data.version;
         const appName = service === 'plex' ? 'Plex' : data.appName;
         log.info('arr', 'Service connection successful', { service, appName, version });
-        return res.json({
-          success: true,
-          version,
-          appName
-        });
+        return ok(res, { version, appName });
       } else if (response.status === 401) {
         throw new AuthenticationError('Invalid API key');
       } else if (response.status === 404) {
@@ -553,7 +550,7 @@ module.exports = function(ctx) {
       const metadata = await credentialManager.getMetadata(`arr.${service}.apikey`);
       const storedProfileId = metadata?.qualityProfileId || null;
 
-      res.json({ success: true, profiles: mapped, storedProfileId });
+      ok(res, { profiles: mapped, storedProfileId });
     } catch (e) {
       if (e.cause?.code === 'ECONNREFUSED') {
         return errorResponse(res, 502, 'Connection refused — is the service running?');
@@ -588,7 +585,7 @@ module.exports = function(ctx) {
     existing.qualityProfileName = qualityProfileName || null;
     await credentialManager.storeMetadata(credKey, existing);
 
-    res.json({ success: true, message: `Quality profile updated for ${service}` });
+    successMessage(res, `Quality profile updated for ${service}`);
   }, 'arr-quality-profile-save'));
 
   return router;

dashcaddy-api/routes/arr/credentials.js

@@ -1,6 +1,7 @@
 const express = require('express');
-const { validateURL, validateToken } = require('../../input-validator');
-const { ValidationError } = require('../../errors');
+const { validateURL, validateToken } = require('../../../src/security/input-validator');
+const { ValidationError } = require('../../../src/utilities/errors');
+const { ok, successMessage } = require('../src/utils/responses');
 
 /**
  * Arr credentials routes factory
@@ -101,12 +102,7 @@ module.exports = function({ credentialManager, servicesStateManager, asyncHandle
 
     log.info('arr', 'Stored API key', { service, verified: connectionTest?.success || false });
 
-    res.json({
-      success: true,
-      message: `${service} API key stored`,
-      connectionTest,
-      url: resolvedUrl
-    });
+    ok(res, { message: `${service} API key stored`, connectionTest, url: resolvedUrl });
   }, 'arr-credentials-store'));
 
   // List stored arr credentials (keys only, not values)
@@ -131,7 +127,7 @@ module.exports = function({ credentialManager, servicesStateManager, asyncHandle
     // Get seedbox base URL
     const seedboxBaseUrl = await credentialManager.retrieve('arr.seedbox.baseurl');
 
-    res.json({ success: true, credentials, seedboxBaseUrl: seedboxBaseUrl || null });
+    ok(res, { credentials, seedboxBaseUrl: seedboxBaseUrl || null });
   }, 'arr-credentials-list'));
 
   // Delete stored arr credentials
@@ -140,7 +136,7 @@ module.exports = function({ credentialManager, servicesStateManager, asyncHandle
     const credKey = service === 'plex' ? 'arr.plex.token' : `arr.${service}.apikey`;
     await credentialManager.delete(credKey);
     log.info('arr', 'Deleted credentials', { service });
-    res.json({ success: true, message: `${service} credentials removed` });
+    successMessage(res, `${service} credentials removed`);
   }, 'arr-credentials-delete'));
 
   return router;

dashcaddy-api/routes/arr/detect.js

@@ -1,5 +1,6 @@
 const express = require('express');
-const { APP_PORTS, ARR_SERVICES } = require('../../constants');
+const { APP_PORTS, ARR_SERVICES } = require('../../../src/utilities/constants');
+const { ok } = require('../src/utils/responses');
 
 /**
  * Arr service detection routes factory
@@ -62,8 +63,7 @@ module.exports = function({ docker, servicesStateManager, credentialManager, fet
       detected.plex.token = await helpers.getPlexToken(detected.plex.containerName);
     }
 
-    res.json({
-      success: true,
+    ok(res, {
       services: detected,
       summary: {
         plexReady: !!(detected.plex?.token),
@@ -287,7 +287,7 @@ module.exports = function({ docker, servicesStateManager, credentialManager, fet
       readyForAutoConnect: statuses.filter(s => s.status === 'connected').length >= 2
     };
 
-    res.json({ success: true, services: result, seedboxBaseUrl: detectedSeedboxUrl, summary });
+    ok(res, { services: result, seedboxBaseUrl: detectedSeedboxUrl, summary });
   }, 'smart-detect'));
 
   return router;

dashcaddy-api/routes/arr/helpers.js

@@ -1,4 +1,4 @@
-const { APP_PORTS } = require('../../constants');
+const { APP_PORTS } = require('../../../src/utilities/constants');
 
 /**
  * Arr helpers factory

dashcaddy-api/routes/arr/plex.js

@@ -1,5 +1,6 @@
 const express = require('express');
-const { APP_PORTS } = require('../../constants');
+const { APP_PORTS } = require('../../../src/utilities/constants');
+const { ok } = require('../src/utils/responses');
 
 /**
  * Plex routes factory
@@ -86,7 +87,7 @@ module.exports = function({ fetchT, asyncHandler, errorResponse, log: _log, help
       lastVerified: new Date().toISOString()
     });
 
-    res.json({ success: true, serverName, version, libraries });
+    ok(res, { serverName, version, libraries });
   }, 'plex-libraries'));
 
   return router;

dashcaddy-api/routes/arr/smart-connect.js

@@ -1,5 +1,5 @@
 const express = require('express');
-const { APP_PORTS } = require('../../constants');
+const { APP_PORTS } = require('../../../src/utilities/constants');
 
 /**
  * Arr smart-connect routes factory

dashcaddy-api/routes/auth/keys.js

@@ -1,5 +1,6 @@
 const express = require('express');
-const { ValidationError, ForbiddenError, NotFoundError } = require('../../errors');
+const { ValidationError, ForbiddenError, NotFoundError } = require('../../../src/utilities/errors');
+const { ok, successMessage } = require('../src/utils/responses');
 /**
  * Auth API keys routes factory
  * @param {Object} deps - Explicit dependencies
@@ -39,7 +40,7 @@ module.exports = function({ authManager, asyncHandler, log }) {
     }
 
     const keys = await authManager.listAPIKeys();
-    res.json({ success: true, keys });
+    ok(res, { keys });
   }, 'auth-keys-list'));
 
   // Generate new API key
@@ -66,8 +67,7 @@ module.exports = function({ authManager, asyncHandler, log }) {
       scopes || ['read', 'write']
     );
 
-    res.json({
-      success: true,
+    ok(res, {
       key: keyData.key,
       id: keyData.id,
       name: keyData.name,
@@ -93,7 +93,7 @@ module.exports = function({ authManager, asyncHandler, log }) {
     const success = await authManager.revokeAPIKey(keyId);
 
     if (success) {
-      res.json({ success: true, message: 'API key revoked successfully' });
+      successMessage(res, 'API key revoked successfully');
     } else {
       throw new NotFoundError(`API key ${keyId}`);
     }
@@ -126,8 +126,7 @@ module.exports = function({ authManager, asyncHandler, log }) {
     const expiresInMs = parseExpiration(expiresIn || '24h');
     const expiresAt = new Date(Date.now() + expiresInMs).toISOString();
 
-    res.json({
-      success: true,
+    ok(res, {
       token,
       expiresAt,
       usage: 'Include in Authorization header as: Bearer <token>'

dashcaddy-api/routes/auth/session-handlers.js

@@ -1,5 +1,5 @@
-const { SESSION_TTL, APP, PLEX, TIMEOUTS, buildMediaAuth } = require('../../constants');
-const { createCache, CACHE_CONFIGS } = require('../../cache-config');
+const { SESSION_TTL, APP, PLEX, TIMEOUTS, buildMediaAuth } = require('../../../src/utilities/constants');
+const { createCache, CACHE_CONFIGS } = require('../../../src/utilities/cache-config');
 
 /**
  * Auth session handlers routes factory

dashcaddy-api/routes/auth/sso-gate.js

@@ -1,6 +1,6 @@
 const express = require('express');
-const { SESSION_TTL, APP, PLEX, TIMEOUTS, buildMediaAuth } = require('../../constants');
-const { AuthenticationError, NotFoundError } = require('../../errors');
+const { SESSION_TTL, APP, PLEX, TIMEOUTS, buildMediaAuth } = require('../../../src/utilities/constants');
+const { AuthenticationError, NotFoundError } = require('../../../src/utilities/errors');
 
 /**
  * Auth SSO gate routes factory

dashcaddy-api/routes/auth/totp.js

@@ -1,5 +1,6 @@
 const express = require('express');
-const { ValidationError, AuthenticationError } = require('../../errors');
+const { ValidationError, AuthenticationError } = require('../../src/utilities/errors');
+const { ok, successMessage } = require('../../src/utils/responses');
 
 /**
  * Auth TOTP routes factory
@@ -27,8 +28,7 @@ module.exports = function({ authManager, credentialManager, totpConfig, saveTotp
 
   // Get current TOTP config (public route)
   router.get('/totp/config', asyncHandler(async (req, res) => {
-    res.json({
-      success: true,
+    ok(res, {
       config: {
         enabled: ctx.totpConfig.enabled,
         sessionDuration: ctx.totpConfig.sessionDuration,
@@ -62,7 +62,7 @@ module.exports = function({ authManager, credentialManager, totpConfig, saveTotp
       color: { dark: '#ffffff', light: '#00000000' }
     });
 
-    res.json({ success: true, qrCode: qrDataUrl, manualKey: secret, issuer: 'DashCaddy', imported: !!req.body?.secret });
+    ok(res, { qrCode: qrDataUrl, manualKey: secret, issuer: 'DashCaddy', imported: !!req.body?.secret });
   }, 'totp-setup'));
 
   // Verify first code to confirm setup, then activate TOTP
@@ -99,7 +99,7 @@ module.exports = function({ authManager, credentialManager, totpConfig, saveTotp
     ctx.session.create(req, ctx.totpConfig.sessionDuration);
     ctx.session.setCookie(res, ctx.totpConfig.sessionDuration);
 
-    res.json({ success: true, message: 'TOTP enabled successfully', sessionDuration: ctx.totpConfig.sessionDuration });
+    ok(res, { message: 'TOTP enabled successfully', sessionDuration: ctx.totpConfig.sessionDuration });
   }, 'totp-verify-setup'));
 
   // Login: verify TOTP code and set session cookie
@@ -133,7 +133,7 @@ module.exports = function({ authManager, credentialManager, totpConfig, saveTotp
     const newCsrfToken = renewCSRFToken(res, req.secure || req.protocol === 'https');
 
     log.debug('auth', 'Session created', { sessions: ctx.session.ipSessions.size });
-    res.json({ success: true, message: 'Authenticated successfully', sessionDuration: ctx.totpConfig.sessionDuration, csrfToken: newCsrfToken });
+    ok(res, { message: 'Authenticated successfully', sessionDuration: ctx.totpConfig.sessionDuration, csrfToken: newCsrfToken });
   }, 'totp-verify'));
 
   // Check session validity (used by Caddy forward_auth)
@@ -185,7 +185,7 @@ module.exports = function({ authManager, credentialManager, totpConfig, saveTotp
 
     ctx.session.clear(req);
     ctx.session.clearCookie(res);
-    res.json({ success: true, message: 'TOTP disabled' });
+    successMessage(res, 'TOTP disabled');
   }, 'totp-disable'));
 
   // Update TOTP settings (session duration)
@@ -204,8 +204,7 @@ module.exports = function({ authManager, credentialManager, totpConfig, saveTotp
     }
 
     await ctx.saveTotpConfig();
-    res.json({
-      success: true,
+    ok(res, {
       config: { enabled: ctx.totpConfig.enabled, sessionDuration: ctx.totpConfig.sessionDuration, isSetUp: ctx.totpConfig.isSetUp }
     });
   }, 'totp-config'));

dashcaddy-api/routes/auto-restart.js

@@ -9,7 +9,7 @@
 
 const express = require('express');
 const { success } = require('../src/utils/responses');
-const { ValidationError, NotFoundError } = require('../errors');
+const { ValidationError, NotFoundError } = require('../src/utilities/errors');
 
 /**
  * Auto-restart route factory

dashcaddy-api/routes/backups.js

@@ -55,7 +55,7 @@ module.exports = function({ backupManager, licenseManager, asyncHandler }) {
     const { appId, enabled, schedule, retention, runImmediately, destination, destinationPath } = req.body;
     
     if (!appId) {
-      const { ValidationError } = require('../errors');
+      const { ValidationError } = require('../src/utilities/errors');
       throw new ValidationError('appId is required');
     }
 
@@ -93,7 +93,7 @@ module.exports = function({ backupManager, licenseManager, asyncHandler }) {
     const config = backupManager.getConfig();
     
     if (!config.backups || !config.backups[appId]) {
-      const { NotFoundError } = require('../errors');
+      const { NotFoundError } = require('../src/utilities/errors');
       throw new NotFoundError(`No backup schedule found for app: ${appId}`, 'DC-404');
     }
 
@@ -153,7 +153,7 @@ module.exports = function({ backupManager, licenseManager, asyncHandler }) {
     
     const backupConfig = config.backups && config.backups[appId];
     if (!backupConfig) {
-      const { NotFoundError } = require('../errors');
+      const { NotFoundError } = require('../src/utilities/errors');
       throw new NotFoundError(`No backup schedule found for app: ${appId}`, 'DC-404');
     }
 
@@ -229,13 +229,13 @@ module.exports = function({ backupManager, licenseManager, asyncHandler }) {
 
     // Security: prevent path traversal
     if (filename.includes('..') || filename.includes('/') || filename.includes('\\')) {
-      const { ValidationError } = require('../errors');
+      const { ValidationError } = require('../src/utilities/errors');
       throw new ValidationError('Invalid filename');
     }
 
     const filepath = path.join(DEFAULT_BACKUP_DIR, filename);
     if (!fs.existsSync(filepath)) {
-      const { NotFoundError } = require('../errors');
+      const { NotFoundError } = require('../src/utilities/errors');
       throw new NotFoundError(`Backup file not found: ${filename}`, 'DC-404');
     }
 
@@ -365,13 +365,13 @@ module.exports = function({ backupManager, licenseManager, asyncHandler }) {
 
     // Security: prevent path traversal
     if (filename.includes('..') || filename.includes('/') || filename.includes('\\')) {
-      const { ValidationError } = require('../errors');
+      const { ValidationError } = require('../src/utilities/errors');
       throw new ValidationError('Invalid filename');
     }
 
     const filepath = path.join(DEFAULT_BACKUP_DIR, filename);
     if (!fs.existsSync(filepath)) {
-      const { NotFoundError } = require('../errors');
+      const { NotFoundError } = require('../src/utilities/errors');
       throw new NotFoundError(`Backup file not found: ${filename}`, 'DC-404');
     }
 
@@ -502,7 +502,7 @@ module.exports = function({ backupManager, licenseManager, asyncHandler }) {
   router.post('/backups/test-destination', asyncHandler(async (req, res) => {
     const destination = req.body;
     if (!destination || !destination.type) {
-      const { ValidationError } = require('../errors');
+      const { ValidationError } = require('../src/utilities/errors');
       throw new ValidationError('destination.type is required');
     }
     const result = await backupManager.testDestination(destination);
@@ -512,10 +512,10 @@ module.exports = function({ backupManager, licenseManager, asyncHandler }) {
   // Get cloud credentials (masked) for a provider
   // Provider: dropbox | webdav | sftp
   router.get('/backups/credentials/:provider', asyncHandler(async (req, res) => {
-    const credentialManager = require('../credential-manager');
+    const credentialManager = require('../src/managers/credential-manager');
     const provider = req.params.provider;
     if (!['dropbox', 'webdav', 'sftp'].includes(provider)) {
-      const { ValidationError } = require('../errors');
+      const { ValidationError } = require('../src/utilities/errors');
       throw new ValidationError('Invalid provider');
     }
 
@@ -544,8 +544,8 @@ module.exports = function({ backupManager, licenseManager, asyncHandler }) {
 
   // Save cloud credentials for a provider
   router.post('/backups/credentials/:provider', asyncHandler(async (req, res) => {
-    const credentialManager = require('../credential-manager');
-    const { ValidationError } = require('../errors');
+    const credentialManager = require('../src/managers/credential-manager');
+    const { ValidationError } = require('../src/utilities/errors');
     const provider = req.params.provider;
 
     if (!['dropbox', 'webdav', 'sftp'].includes(provider)) {
@@ -585,8 +585,8 @@ module.exports = function({ backupManager, licenseManager, asyncHandler }) {
 
   // Delete cloud credentials for a provider
   router.delete('/backups/credentials/:provider', asyncHandler(async (req, res) => {
-    const credentialManager = require('../credential-manager');
-    const { ValidationError } = require('../errors');
+    const credentialManager = require('../src/managers/credential-manager');
+    const { ValidationError } = require('../src/utilities/errors');
     const provider = req.params.provider;
 
     if (!['dropbox', 'webdav', 'sftp'].includes(provider)) {

dashcaddy-api/routes/browse.js

@@ -2,9 +2,10 @@ const express = require('express');
 const fs = require('fs');
 const fsp = require('fs').promises;
 const path = require('path');
-const { exists, isAccessible } = require('../fs-helpers');
-const { paginate, parsePaginationParams } = require('../pagination');
-const { ValidationError, ForbiddenError } = require('../errors');
+const { exists, isAccessible } = require('../src/utilities/fs-helpers');
+const { paginate, parsePaginationParams } = require('../src/utilities/pagination');
+const { ValidationError, ForbiddenError } = require('../src/utilities/errors');
+const { ok } = require('../src/utils/responses');
 
 /**
  * Browse route factory
@@ -44,7 +45,7 @@ module.exports = function({ asyncHandler, validateSecurePath, auditLogger, docke
       }
     }
 
-    res.json({ success: true, roots });
+    return ok(res, { roots });
   }, 'browse-roots'));
 
   // Browse directory contents
@@ -64,7 +65,7 @@ module.exports = function({ asyncHandler, validateSecurePath, auditLogger, docke
           roots.push(r);
         }
       }
-      return res.json({ success: true, path: '', items: roots });
+      return ok(res, { path: '', items: roots });
     }
 
     const matchingRoot = BROWSE_ROOTS.find(r =>
@@ -98,7 +99,7 @@ module.exports = function({ asyncHandler, validateSecurePath, auditLogger, docke
     }
 
     if (!await exists(resolvedPath)) {
-      const { NotFoundError } = require('../errors');
+      const { NotFoundError } = require('../src/utilities/errors');
       throw new NotFoundError('Path');
     }
 
@@ -124,8 +125,7 @@ module.exports = function({ asyncHandler, validateSecurePath, auditLogger, docke
 
     const paginationParams = parsePaginationParams(req.query);
     const result = paginate(folders, paginationParams);
-    res.json({
-      success: true,
+    ok(res, {
       path: requestedPath,
       parent: path.dirname(requestedPath).replace(/\\/g, '/') || null,
       items: result.data,
@@ -190,8 +190,7 @@ module.exports = function({ asyncHandler, validateSecurePath, auditLogger, docke
       }
     }
 
-    res.json({
-      success: true,
+    ok(res, {
       mounts: detectedMounts,
       message: detectedMounts.length > 0
         ? `Found ${detectedMounts.length} media mount(s) from existing containers`

dashcaddy-api/routes/ca.js

@@ -3,8 +3,9 @@ const fs = require('fs');
 const fsp = require('fs').promises;
 const path = require('path');
 const { execSync } = require('child_process');
-const { exists } = require('../fs-helpers');
-const { ValidationError } = require('../errors');
+const { exists } = require('../src/utilities/fs-helpers');
+const { ValidationError } = require('../src/utilities/errors');
+const { ok } = require('../src/utils/responses');
 const platformPaths = require('../platform-paths');
 
 module.exports = function(ctx) {
@@ -18,7 +19,7 @@ module.exports = function(ctx) {
     if (await exists(certInfoPath)) {
       certInfoFile = certInfoPath;
     } else {
-      const { NotFoundError } = require('../errors');
+      const { NotFoundError } = require('../src/utilities/errors');
       throw new NotFoundError('CA certificate information');
     }
 
@@ -26,8 +27,7 @@ module.exports = function(ctx) {
       const expirationDate = new Date(certInfo.validUntil);
       const daysUntilExpiration = Math.floor((expirationDate - new Date()) / (1000 * 60 * 60 * 24));
 
-      res.json({
-        success: true,
+      ok(res, {
         certificate: {
           name: certInfo.name,
           fingerprint: certInfo.fingerprint,
@@ -50,7 +50,7 @@ module.exports = function(ctx) {
     if (await exists(dashcaCertPath)) certPath = dashcaCertPath;
     else if (await exists(hostCertPath)) certPath = hostCertPath;
     else {
-      const { NotFoundError } = require('../errors');
+      const { NotFoundError } = require('../src/utilities/errors');
       throw new NotFoundError('Root CA certificate');
     }
 
@@ -73,7 +73,7 @@ module.exports = function(ctx) {
     if (await exists(certInfoPath)) {
       certInfoFile = certInfoPath;
     } else {
-      const { NotFoundError } = require('../errors');
+      const { NotFoundError } = require('../src/utilities/errors');
       throw new NotFoundError('CA certificate information. Deploy DashCA first or ensure cert-info.json exists.');
     }
 
@@ -106,7 +106,7 @@ module.exports = function(ctx) {
     }
 
     if (!templateContent) {
-      const { NotFoundError } = require('../errors');
+      const { NotFoundError } = require('../src/utilities/errors');
       throw new NotFoundError(`Install script template (${templateName})`);
     }
 
@@ -243,7 +243,7 @@ ${safeDomain.includes('.') ? `DNS.2 = *.${safeDomain}` : ''}`;
     const certsDir = platformPaths.generatedCertsDir;
 
     if (!await exists(certsDir)) {
-      return res.json({ success: true, certificates: [] });
+      return ok(res, { certificates: [] });
     }
 
     const dirEntries = await fsp.readdir(certsDir);
@@ -278,7 +278,7 @@ ${safeDomain.includes('.') ? `DNS.2 = *.${safeDomain}` : ''}`;
         }
       }))).filter(Boolean);
 
-    res.json({ success: true, certificates });
+    ok(res, { certificates });
   }, 'ca-certs'));
 
   return router;

dashcaddy-api/routes/config-drift.js

@@ -9,7 +9,7 @@
 
 const express = require('express');
 const { success } = require('../src/utils/responses');
-const { ValidationError, NotFoundError } = require('../errors');
+const { ValidationError, NotFoundError } = require('../src/utilities/errors');
 
 /**
  * Config-drift route factory

dashcaddy-api/routes/config/assets.js

@@ -1,10 +1,11 @@
 const express = require('express');
 const fsp = require('fs').promises;
 const path = require('path');
-const { LIMITS } = require('../../constants');
-const { exists } = require('../../fs-helpers');
-const { ValidationError } = require('../../errors');
+const { LIMITS } = require('../../../src/utilities/constants');
+const { exists } = require('../../../src/utilities/fs-helpers');
+const { ValidationError } = require('../../../src/utilities/errors');
 const platformPaths = require('../../platform-paths');
+const { ok, successMessage } = require('../src/utils/responses');
 /**
  * Config assets routes factory
  * @param {Object} deps - Explicit dependencies
@@ -63,8 +64,7 @@ module.exports = function({ servicesStateManager: _servicesStateManager, asyncHa
     const filePath = path.join(assetsPath, safeFilename);
     await fsp.writeFile(filePath, buffer);
 
-    res.json({
-      success: true,
+    ok(res, {
       path: `/assets/${safeFilename}`,
       message: `Logo saved to ${filePath}`
     });
@@ -76,8 +76,7 @@ module.exports = function({ servicesStateManager: _servicesStateManager, asyncHa
   // Get current logo path, position, and title
   router.get('/logo', asyncHandler(async (req, res) => {
     const config = await ctx.readConfig();
-    res.json({
-      success: true,
+    ok(res, {
       // Dark/light variants (new)
       customLogoDark: config.customLogoDark || null,
       customLogoLight: config.customLogoLight || null,
@@ -156,8 +155,7 @@ module.exports = function({ servicesStateManager: _servicesStateManager, asyncHa
     config.updatedAt = new Date().toISOString();
     await fsp.writeFile(ctx.CONFIG_FILE, JSON.stringify(config, null, 2), 'utf8');
 
-    res.json({
-      success: true,
+    ok(res, {
       pathDark: pathDark,
       pathLight: pathLight,
       // Legacy compat
@@ -195,10 +193,7 @@ module.exports = function({ servicesStateManager: _servicesStateManager, asyncHa
     config.updatedAt = new Date().toISOString();
     await fsp.writeFile(ctx.CONFIG_FILE, JSON.stringify(config, null, 2), 'utf8');
 
-    res.json({
-      success: true,
-      message: 'Branding reset to defaults'
-    });
+    successMessage(res, 'Branding reset to defaults');
   }, 'logo-delete'));
 
   // ===== FAVICON ENDPOINTS =====
@@ -207,8 +202,7 @@ module.exports = function({ servicesStateManager: _servicesStateManager, asyncHa
   // Get current favicon
   router.get('/favicon', asyncHandler(async (req, res) => {
     const config = await ctx.readConfig();
-    res.json({
-      success: true,
+    ok(res, {
       customFavicon: config.customFavicon || null,
       isDefault: !config.customFavicon
     });
@@ -268,8 +262,7 @@ module.exports = function({ servicesStateManager: _servicesStateManager, asyncHa
     // Update config
     await ctx.saveConfig({ customFavicon: '/assets/favicon.ico', updatedAt: new Date().toISOString() });
 
-    res.json({
-      success: true,
+    ok(res, {
       path: '/assets/favicon.ico',
       message: 'Favicon created successfully'
     });
@@ -293,10 +286,7 @@ module.exports = function({ servicesStateManager: _servicesStateManager, asyncHa
     config.updatedAt = new Date().toISOString();
     await fsp.writeFile(ctx.CONFIG_FILE, JSON.stringify(config, null, 2), 'utf8');
 
-    res.json({
-      success: true,
-      message: 'Favicon reset to default'
-    });
+    successMessage(res, 'Favicon reset to default');
   }, 'favicon-delete'));
 
   return router;

dashcaddy-api/routes/config/backup.js

@@ -1,10 +1,11 @@
 const fsp = require('fs').promises;
 const fs = require('fs');
 const path = require('path');
-const { CADDY } = require('../../constants');
-const { exists } = require('../../fs-helpers');
-const { ValidationError, AuthenticationError } = require('../../errors');
+const { CADDY } = require('../../../src/utilities/constants');
+const { exists } = require('../../../src/utilities/fs-helpers');
+const { ValidationError, AuthenticationError } = require('../../../src/utilities/errors');
 const platformPaths = require('../../platform-paths');
+const { ok } = require('../src/utils/responses');
 
 /**
  * Config backup routes factory
@@ -210,7 +211,7 @@ module.exports = function(deps) {
       preview.browserStateCount = Object.keys(backup.browserState).length;
     }
 
-    res.json({ success: true, preview });
+    ok(res, { preview });
   }, 'backup-preview'));
 
   // Restore configuration from backup
@@ -379,7 +380,7 @@ module.exports = function(deps) {
     if (results.restored.includes('encryptionKey')) {
       try {
         // Clear the cached key so crypto-utils reloads from the new file on next use
-        const cryptoUtils = require('../../crypto-utils');
+        const cryptoUtils = require('../../../src/security/crypto-utils');
         if (typeof cryptoUtils.clearCachedKey === 'function') {
           cryptoUtils.clearCachedKey();
         }
@@ -391,13 +392,17 @@ module.exports = function(deps) {
 
     const success = results.restored.length > 0 && results.errors.length === 0;
 
-    res.json({
-      success,
-      message: success
-        ? `Restored ${results.restored.length} file(s) successfully`
-        : `Restore completed with ${results.errors.length} error(s)`,
-      results
-    });
+    if (success) {
+      ok(res, {
+        message: `Restored ${results.restored.length} file(s) successfully`,
+        results
+      });
+    } else {
+      ok(res, {
+        message: `Restore completed with ${results.errors.length} error(s)`,
+        results
+      }, 200);
+    }
 
     log.info('backup', 'Backup restore completed', { restored: results.restored.length, errors: results.errors.length });
   }, 'backup-restore'));

dashcaddy-api/routes/config/settings.js

@@ -1,7 +1,8 @@
 const fsp = require('fs').promises;
-const { validateConfig } = require('../../config-schema');
-const { exists } = require('../../fs-helpers');
-const { ValidationError } = require('../../errors');
+const { validateConfig } = require('../../../src/utilities/config-schema');
+const { exists } = require('../../../src/utilities/fs-helpers');
+const { ValidationError } = require('../../../src/utilities/errors');
+const { ok, successMessage } = require('../src/utils/responses');
 
 /**
  * Config settings routes factory
@@ -71,14 +72,14 @@ module.exports = function({ configStateManager: _configStateManager, asyncHandle
     }
     log.info('config', 'Config saved', { path: ctx.CONFIG_FILE });
 
-    res.json({ success: true, message: 'Configuration saved', config, warnings });
+    ok(res, { message: 'Configuration saved', config, warnings });
   }, 'config-save'));
 
   router.delete('/config', asyncHandler(async (req, res) => {
     if (await exists(ctx.CONFIG_FILE)) {
       await fsp.unlink(ctx.CONFIG_FILE);
     }
-    res.json({ success: true, message: 'Configuration reset' });
+    successMessage(res, 'Configuration reset');
   }, 'config-delete'));
 
   return router;

dashcaddy-api/routes/containers.js

@@ -1,7 +1,7 @@
 const express = require('express');
-const { DOCKER } = require('../constants');
-const { paginate, parsePaginationParams } = require('../pagination');
-const { NotFoundError } = require('../errors');
+const { DOCKER } = require('../src/utilities/constants');
+const { paginate, parsePaginationParams } = require('../src/utilities/pagination');
+const { NotFoundError } = require('../src/utilities/errors');
 const { success } = require('../src/utils/responses');
 
 /**

dashcaddy-api/routes/dependencies.js

@@ -16,7 +16,7 @@
 
 const express = require('express');
 const { success, error: errorResponse } = require('../src/utils/responses');
-const { NotFoundError, ValidationError } = require('../errors');
+const { NotFoundError, ValidationError } = require('../src/utilities/errors');
 
 /**
  * Dependencies route factory

dashcaddy-api/routes/dns.js

@@ -2,10 +2,10 @@ const express = require('express');
 const fs = require('fs');
 const fsp = require('fs').promises;
 const validatorLib = require('validator');
-const { APP, TIMEOUTS, CADDY, DNS_RECORD_TYPES, REGEX, SESSION_TTL } = require('../constants');
-const { exists } = require('../fs-helpers');
+const { APP, TIMEOUTS, CADDY, DNS_RECORD_TYPES, REGEX, SESSION_TTL } = require('../src/utilities/constants');
+const { exists } = require('../src/utilities/fs-helpers');
 const { success, error: errorResponse } = require('../src/utils/responses');
-const { ValidationError, AuthenticationError, NotFoundError } = require('../errors');
+const { ValidationError, AuthenticationError, NotFoundError } = require('../src/utilities/errors');
 
 /**
  * DNS routes factory
@@ -552,7 +552,7 @@ module.exports = function({
         }
       }
 
-      return res.json({
+      return ok(res, {
         success: anySuccess,
         message: anySuccess ? 'Credentials saved for one or more servers' : 'All server credential tests failed',
         results

dashcaddy-api/routes/docker-resources.js

@@ -1,6 +1,6 @@
 const express = require('express');
 const { success } = require('../src/utils/responses');
-const { ValidationError } = require('../errors');
+const { ValidationError } = require('../src/utilities/errors');
 
 /**
  * Docker resources route factory (volumes, networks, disk usage)

dashcaddy-api/routes/errorlogs.js

@@ -1,8 +1,8 @@
 const express = require('express');
 const fs = require('fs');
 const fsp = require('fs').promises;
-const { exists } = require('../fs-helpers');
-const { paginate, parsePaginationParams } = require('../pagination');
+const { exists } = require('../src/utilities/fs-helpers');
+const { paginate, parsePaginationParams } = require('../src/utilities/pagination');
 const { success } = require('../src/utils/responses');
 
 /**

dashcaddy-api/routes/events.js

@@ -1,4 +1,5 @@
 const express = require('express');
+const { ok } = require('../src/utils/responses');
 
 /**
  * Server-Sent Events route factory
@@ -147,7 +148,7 @@ module.exports = function({ resourceMonitor, healthChecker, updateManager, logEr
 
   // Client count (useful for debugging)
   router.get('/clients', (req, res) => {
-    res.json({ success: true, count: clients.size });
+    ok(res, { count: clients.size });
   });
 
   return router;

dashcaddy-api/routes/health.js

@@ -2,13 +2,13 @@ const express = require('express');
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
-const { TIMEOUTS } = require('../constants');
-const { exists } = require('../fs-helpers');
-const { paginate, parsePaginationParams } = require('../pagination');
+const { TIMEOUTS } = require('../src/utilities/constants');
+const { exists } = require('../src/utilities/fs-helpers');
+const { paginate, parsePaginationParams } = require('../src/utilities/pagination');
 const platformPaths = require('../platform-paths');
-const { resolveServiceUrl } = require('../url-resolver');
-const { success, error: errorResponse } = require('../src/utils/responses');
-const { ValidationError } = require('../errors');
+const { resolveServiceUrl } = require('../src/utilities/url-resolver');
+const { success, error: errorResponse, errorResponse: sendError, ok, notFound } = require('../src/utils/responses');
+const { ValidationError } = require('../src/utilities/errors');
 
 /**
  * Health routes factory
@@ -190,7 +190,7 @@ module.exports = function({
 
     // Load service config
     if (!await exists(SERVICES_FILE)) {
-      const { NotFoundError } = require('../errors');
+      const { NotFoundError } = require('../src/utilities/errors');
       throw new NotFoundError('Services file');
     }
 
@@ -199,7 +199,7 @@ module.exports = function({
     const service = services.find(s => (s.id || s.name?.toLowerCase()) === serviceId);
 
     if (!service) {
-      const { NotFoundError } = require('../errors');
+      const { NotFoundError } = require('../src/utilities/errors');
       throw new NotFoundError('Service');
     }
 
@@ -273,12 +273,7 @@ module.exports = function({
     try {
       // Check if certificate exists
       if (!await exists(rootCertPath)) {
-        return res.status(404).json({
-          success: false,
-          error: 'Root CA certificate not found',
-          caStatus: 'error',
-          daysUntilExpiration: null
-        });
+        return sendError(res, 404, 'Root CA certificate not found', { caStatus: 'error', daysUntilExpiration: null });
       }
 
       const dates = execSync(`openssl x509 -in "${rootCertPath}" -noout -dates`).toString();
@@ -304,8 +299,7 @@ module.exports = function({
         message = `CA certificate expires in ${daysUntilExpiration} days`;
       }
 
-      res.json({
-        success: true,
+      ok(res, {
         caStatus,
         message,
         daysUntilExpiration,
@@ -313,12 +307,7 @@ module.exports = function({
       });
     } catch (error) {
       await logError('GET /api/health/ca', error);
-      res.status(500).json({
-        success: false,
-        error: error.message,
-        caStatus: 'error',
-        daysUntilExpiration: null
-      });
+      sendError(res, 500, error.message, { caStatus: 'error', daysUntilExpiration: null });
     }
   }, 'health-ca'));
 
@@ -342,7 +331,7 @@ module.exports = function({
     const hours = parseInt(req.query.hours) || 24;
     const stats = healthChecker.getServiceStats(req.params.serviceId, hours);
     if (!stats) {
-      const { NotFoundError } = require('../errors');
+      const { NotFoundError } = require('../src/utilities/errors');
       throw new NotFoundError('Service');
     }
     success(res, { stats });

dashcaddy-api/routes/license.js

@@ -1,6 +1,6 @@
 const express = require('express');
 const { success, error: errorResponse } = require('../src/utils/responses');
-const { ValidationError } = require('../errors');
+const { ValidationError } = require('../src/utilities/errors');
 
 /**
  * License routes factory

dashcaddy-api/routes/logs.js

@@ -2,9 +2,10 @@ const express = require('express');
 const fs = require('fs');
 const fsp = require('fs').promises;
 const path = require('path');
-const { exists } = require('../fs-helpers');
-const { paginate, parsePaginationParams } = require('../pagination');
-const { NotFoundError, ValidationError, ForbiddenError } = require('../errors');
+const { exists } = require('../src/utilities/fs-helpers');
+const { paginate, parsePaginationParams } = require('../src/utilities/pagination');
+const { NotFoundError, ValidationError, ForbiddenError } = require('../src/utilities/errors');
+const { ok } = require('../src/utils/responses');
 
 /**
  * Logs route factory
@@ -31,7 +32,7 @@ module.exports = function({ asyncHandler, docker, logDigest, dockerMaintenance }
 
     const paginationParams = parsePaginationParams(req.query);
     const result = paginate(containerList, paginationParams);
-    res.json({ success: true, containers: result.data, ...(result.pagination && { pagination: result.pagination }) });
+    ok(res, { containers: result.data, ...(result.pagination && { pagination: result.pagination }) });
   }, 'logs-containers'));
 
   // Get logs for a specific container
@@ -47,7 +48,7 @@ module.exports = function({ asyncHandler, docker, logDigest, dockerMaintenance }
       info = await container.inspect();
     } catch (err) {
       if (err.statusCode === 404 || (err.message && err.message.includes('no such container'))) {
-        const { NotFoundError } = require('../errors');
+        const { NotFoundError } = require('../src/utilities/errors');
         throw new NotFoundError(`Container ${containerId}`);
       }
       throw err;
@@ -81,8 +82,7 @@ module.exports = function({ asyncHandler, docker, logDigest, dockerMaintenance }
       offset += 8 + size;
     }
 
-    res.json({
-      success: true,
+    ok(res, {
       containerId, containerName,
       logs: lines,
       count: lines.length
@@ -97,7 +97,7 @@ module.exports = function({ asyncHandler, docker, logDigest, dockerMaintenance }
       await container.inspect();
     } catch (err) {
       if (err.statusCode === 404 || (err.message && err.message.includes('no such container'))) {
-        const { NotFoundError } = require('../errors');
+        const { NotFoundError } = require('../src/utilities/errors');
         throw new NotFoundError(`Container ${containerId}`);
       }
       throw err;
@@ -153,23 +153,23 @@ module.exports = function({ asyncHandler, docker, logDigest, dockerMaintenance }
     if (!logDigest) throw new Error('Log digest not available');
     const digest = await logDigest.getLatestDigest();
     if (!digest) {
-      return res.json({ success: true, digest: null, message: 'No digest available yet. First digest is generated at midnight.' });
+      return ok(res, { digest: null, message: 'No digest available yet. First digest is generated at midnight.' });
     }
-    res.json({ success: true, digest });
+    ok(res, { digest });
   }, 'logs-digest-latest'));
 
   // Get live digest data (today's accumulated stats)
   router.get('/logs/digest/live', asyncHandler(async (req, res) => {
     if (!logDigest) throw new Error('Log digest not available');
     const live = logDigest.getLiveData();
-    res.json({ success: true, ...live });
+    ok(res, { ...live });
   }, 'logs-digest-live'));
 
   // List available digest dates
   router.get('/logs/digest/history', asyncHandler(async (req, res) => {
     if (!logDigest) throw new Error('Log digest not available');
     const dates = await logDigest.listDigests();
-    res.json({ success: true, dates });
+    ok(res, { dates });
   }, 'logs-digest-history'));
 
   // Generate digest on demand (for today or a specific date)
@@ -177,7 +177,7 @@ module.exports = function({ asyncHandler, docker, logDigest, dockerMaintenance }
     if (!logDigest) throw new Error('Log digest not available');
     const date = req.body.date || new Date().toISOString().slice(0, 10);
     const digest = await logDigest.generateDailyDigest(date);
-    res.json({ success: true, digest });
+    ok(res, { digest });
   }, 'logs-digest-generate'));
 
   // Get digest for a specific date (JSON)
@@ -196,7 +196,7 @@ module.exports = function({ asyncHandler, docker, logDigest, dockerMaintenance }
     }
     const digest = await logDigest.getDigestByDate(date);
     if (!digest) throw new NotFoundError(`Digest for ${date}`);
-    res.json({ success: true, digest });
+    ok(res, { digest });
   }, 'logs-digest-date'));
 
   // Get Docker disk usage snapshot
@@ -204,14 +204,14 @@ module.exports = function({ asyncHandler, docker, logDigest, dockerMaintenance }
     if (!dockerMaintenance) throw new Error('Docker maintenance not available');
     const diskUsage = await dockerMaintenance.getDiskUsage();
     const status = dockerMaintenance.getStatus();
-    res.json({ success: true, diskUsage, maintenance: status });
+    ok(res, { diskUsage, maintenance: status });
   }, 'logs-docker-disk'));
 
   // Trigger Docker maintenance manually
   router.post('/logs/docker-maintenance', asyncHandler(async (req, res) => {
     if (!dockerMaintenance) throw new Error('Docker maintenance not available');
     const result = await dockerMaintenance.runMaintenance();
-    res.json({ success: true, result });
+    ok(res, { result });
   }, 'logs-docker-maintenance'));
 
   // Get logs from a file path (for native applications)
@@ -232,7 +232,7 @@ module.exports = function({ asyncHandler, docker, logDigest, dockerMaintenance }
     try {
       resolvedPath = await fsp.realpath(normalizedPath);
     } catch {
-      const { NotFoundError } = require('../errors');
+      const { NotFoundError } = require('../src/utilities/errors');
       throw new NotFoundError('Log file');
     }
 
@@ -247,7 +247,7 @@ module.exports = function({ asyncHandler, docker, logDigest, dockerMaintenance }
     }
 
     if (!await exists(resolvedPath)) {
-      const { NotFoundError } = require('../errors');
+      const { NotFoundError } = require('../src/utilities/errors');
       throw new NotFoundError('Log file');
     }
 
@@ -261,8 +261,7 @@ module.exports = function({ asyncHandler, docker, logDigest, dockerMaintenance }
       timestamp: extractTimestamp(line)
     }));
 
-    res.json({
-      success: true,
+    ok(res, {
       logPath: normalizedPath,
       logs,
       count: logs.length,

dashcaddy-api/routes/monitoring.js

@@ -39,7 +39,7 @@ module.exports = function({ resourceMonitor, docker, asyncHandler, log, notifica
   router.get('/monitoring/stats/:containerId', asyncHandler(async (req, res) => {
     const stats = resourceMonitor.getCurrentStats(req.params.containerId);
     if (!stats) {
-      const { NotFoundError } = require('../errors');
+      const { NotFoundError } = require('../src/utilities/errors');
       throw new NotFoundError('Container');
     }
     success(res, { stats });
@@ -55,7 +55,7 @@ module.exports = function({ resourceMonitor, docker, asyncHandler, log, notifica
       const startTime = parseInt(req.query.startTime, 10);
       const endTime = parseInt(req.query.endTime, 10);
       if (Number.isNaN(startTime) || Number.isNaN(endTime) || startTime >= endTime) {
-        const { ValidationError } = require('../errors');
+        const { ValidationError } = require('../src/utilities/errors');
         throw new ValidationError('Invalid startTime/endTime');
       }
       const result = resourceMonitor.getHistoryByRange(containerId, startTime, endTime);
@@ -74,7 +74,7 @@ module.exports = function({ resourceMonitor, docker, asyncHandler, log, notifica
     const hours = parseInt(req.query.hours) || 24;
     const aggregated = resourceMonitor.getAggregatedStats(req.params.containerId, hours);
     if (!aggregated) {
-      const { NotFoundError } = require('../errors');
+      const { NotFoundError } = require('../src/utilities/errors');
       throw new NotFoundError('Monitoring data');
     }
     success(res, { aggregated, hours });
@@ -92,7 +92,7 @@ module.exports = function({ resourceMonitor, docker, asyncHandler, log, notifica
   router.post('/monitoring/alerts/config', asyncHandler(async (req, res) => {
     const { configs } = req.body;
     if (!configs || typeof configs !== 'object') {
-      const { ValidationError } = require('../errors');
+      const { ValidationError } = require('../src/utilities/errors');
       throw new ValidationError('configs object required');
     }
     for (const [containerId, config] of Object.entries(configs)) {

dashcaddy-api/routes/notifications.js

@@ -1,8 +1,9 @@
 const express = require('express');
-const { validateURL, validateToken } = require('../input-validator');
+const { validateURL, validateToken } = require('../src/security/input-validator');
 const validatorLib = require('validator');
-const { paginate, parsePaginationParams } = require('../pagination');
-const { ValidationError } = require('../errors');
+const { paginate, parsePaginationParams } = require('../src/utilities/pagination');
+const { ValidationError } = require('../src/utilities/errors');
+const { ok, successMessage } = require('../src/utils/responses');
 
 /**
  * Notifications route factory
@@ -44,7 +45,7 @@ module.exports = function({ notification, asyncHandler }) {
         events: notificationConfig.events,
         healthCheck: notificationConfig.healthCheck
       };
-      res.json({ success: true, config: safeConfig });
+      ok(res, { config: safeConfig });
   }, 'notifications-config-get'));
 
   // POST /config — Update notification configuration
@@ -150,7 +151,7 @@ module.exports = function({ notification, asyncHandler }) {
       }
 
       await notification.saveConfig();
-      res.json({ success: true, message: 'Notification config updated' });
+      successMessage(res, 'Notification config updated');
   }, 'notifications-config-update'));
 
   // POST /test — Test notification delivery
@@ -176,11 +177,11 @@ module.exports = function({ notification, asyncHandler }) {
         default:
           throw new ValidationError('Unknown provider');
       }
-      res.json({ success: result.success, provider, error: result.error });
+      ok(res, { success: result.success, provider, error: result.error });
     } else {
       // Test all enabled providers
       const result = await notification.send('test', 'Test Notification', 'This is a test notification from DashCaddy.', 'info');
-      res.json({ success: true, ...result });
+      ok(res, { success: true, ...result });
     }
   }, 'notifications-test'));
 
@@ -190,11 +191,10 @@ module.exports = function({ notification, asyncHandler }) {
     const paginationParams = parsePaginationParams(req.query);
     if (paginationParams) {
       const result = paginate(notificationHistory, paginationParams);
-      res.json({ success: true, history: result.data, total: notificationHistory.length, pagination: result.pagination });
+      ok(res, { history: result.data, total: notificationHistory.length, pagination: result.pagination });
     } else {
       const limit = parseInt(req.query.limit) || 50;
-      res.json({
-        success: true,
+      ok(res, {
         history: notificationHistory.slice(0, limit),
         total: notificationHistory.length
       });
@@ -204,15 +204,14 @@ module.exports = function({ notification, asyncHandler }) {
   // DELETE /history — Clear notification history
   router.delete('/history', asyncHandler(async (req, res) => {
     notification.clearHistory();
-    res.json({ success: true, message: 'Notification history cleared' });
+    successMessage(res, 'Notification history cleared');
   }, 'notifications-history-clear'));
 
   // POST /health-check — Manually trigger health check
   router.post('/health-check', asyncHandler(async (req, res) => {
     await notification.checkHealth();
     const notificationConfig = notification.getConfig();
-    res.json({
-      success: true,
+    ok(res, {
       lastCheck: notificationConfig.healthCheck.lastCheck,
       containersMonitored: Object.keys(notification.getHealthState()).length
     });
@@ -223,8 +222,7 @@ module.exports = function({ notification, asyncHandler }) {
     const notificationConfig = notification.getConfig();
     const providers = notificationConfig.providers || {};
     
-    res.json({
-      success: true,
+    ok(res, {
       enabled: notificationConfig.enabled,
       providers: {
         discord: providers.discord?.enabled && !!providers.discord?.webhookUrl,
@@ -252,7 +250,7 @@ module.exports = function({ notification, asyncHandler }) {
     // Use 'test' as the event for manual sends
     const result = await notification.send(event, data || {}, type || 'info');
     
-    res.json({ 
+    ok(res, { 
       success: result.success, 
       event,
       results: result.results 

dashcaddy-api/routes/openclaw.js

@@ -1,5 +1,6 @@
 const express = require('express');
 const http = require('http');
+const { ok, errorResponse, notFound, conflict } = require('../src/utils/responses');
 
 /**
  * OpenClaw management routes
@@ -93,8 +94,8 @@ module.exports = function openClawRoutes(ctx) {
         proxyRes.on('data', function(d) { res.write(d); });
         proxyRes.on('end', function() { res.end(); });
       });
-      proxyReq.on('error', function(e) { res.status(502).json({ success: false, error: e.message }); });
-      proxyReq.setTimeout(15000, function() { proxyReq.destroy(); res.status(504).json({ success: false, error: 'gateway timeout' }); });
+      proxyReq.on('error', function(e) { errorResponse(res, 502, e.message); });
+      proxyReq.setTimeout(15000, function() { proxyReq.destroy(); errorResponse(res, 504, 'gateway timeout'); });
       proxyReq.write(body);
       proxyReq.end();
     } else {
@@ -104,8 +105,8 @@ module.exports = function openClawRoutes(ctx) {
         proxyRes.on('data', function(d) { res.write(d); });
         proxyRes.on('end', function() { res.end(); });
       });
-      proxyReq.on('error', function(e) { res.status(502).json({ success: false, error: e.message }); });
-      proxyReq.setTimeout(15000, function() { proxyReq.destroy(); res.status(504).json({ success: false, error: 'gateway timeout' }); });
+      proxyReq.on('error', function(e) { errorResponse(res, 502, e.message); });
+      proxyReq.setTimeout(15000, function() { proxyReq.destroy(); errorResponse(res, 504, 'gateway timeout'); });
     }
   }
 
@@ -115,7 +116,7 @@ module.exports = function openClawRoutes(ctx) {
     const container = await findOpenClawContainer();
 
     if (!container) {
-      return res.json({ success: true, deployed: false });
+      return ok(res, { deployed: false });
     }
 
     const token = await getGatewayToken(container.Id);
@@ -123,8 +124,7 @@ module.exports = function openClawRoutes(ctx) {
     const baseUrl = 'http://localhost:' + port;
     const health = await gatewayHealth(baseUrl, token);
 
-    res.json({
-      success: true,
+    ok(res, {
       deployed: true,
       container: {
         id: container.Id.slice(0, 12),
@@ -149,7 +149,7 @@ module.exports = function openClawRoutes(ctx) {
   router.post('/deploy', asyncHandler(async function(req, res) {
     const existing = await findOpenClawContainer();
     if (existing) {
-      return res.status(409).json({ success: false, error: 'OpenClaw is already deployed' });
+      return conflict(res, 'OpenClaw is already deployed');
     }
 
     const image = 'ghcr.io/nousresearch/openclaw:latest';
@@ -170,7 +170,7 @@ module.exports = function openClawRoutes(ctx) {
       });
     } catch(e) {
       log.error('OpenClaw pull failed: ' + e.message);
-      return res.status(500).json({ success: false, error: 'Failed to pull image: ' + e.message });
+      return errorResponse(res, 500, 'Failed to pull image: ' + e.message);
     }
 
     // Create + start container
@@ -196,8 +196,7 @@ module.exports = function openClawRoutes(ctx) {
       await container.start();
       log.info('OpenClaw deployed: ' + container.id.slice(0, 12));
 
-      res.json({
-        success: true,
+      ok(res, {
         deployed: true,
         container: { id: container.id.slice(0, 12), name: name },
         gateway: {
@@ -207,7 +206,7 @@ module.exports = function openClawRoutes(ctx) {
       });
     } catch(e) {
       log.error('OpenClaw deploy failed: ' + e.message);
-      res.status(500).json({ success: false, error: 'Deploy failed: ' + e.message });
+      errorResponse(res, 500, 'Deploy failed: ' + e.message);
     }
   }));
 
@@ -215,7 +214,7 @@ module.exports = function openClawRoutes(ctx) {
 
   router.get('/proxy/*', asyncHandler(async function(req, res) {
     const container = await findOpenClawContainer();
-    if (!container) return res.status(404).json({ success: false, error: 'OpenClaw not deployed' });
+    if (!container) return notFound(res, 'OpenClaw not deployed');
 
     const token = await getGatewayToken(container.Id);
     const port = await getContainerPort(container.Id);
@@ -229,7 +228,7 @@ module.exports = function openClawRoutes(ctx) {
 
   router.post('/proxy/*', asyncHandler(async function(req, res) {
     const container = await findOpenClawContainer();
-    if (!container) return res.status(404).json({ success: false, error: 'OpenClaw not deployed' });
+    if (!container) return notFound(res, 'OpenClaw not deployed');
 
     const token = await getGatewayToken(container.Id);
     const port = await getContainerPort(container.Id);
@@ -243,17 +242,17 @@ module.exports = function openClawRoutes(ctx) {
 
   router.delete('/', asyncHandler(async function(req, res) {
     const container = await findOpenClawContainer();
-    if (!container) return res.status(404).json({ success: false, error: 'OpenClaw not deployed' });
+    if (!container) return notFound(res, 'OpenClaw not deployed');
 
     try {
       const c = docker.client.container(container.Id);
       await c.stop().catch(function() {});
       await c.remove({ force: true });
       log.info('OpenClaw container ' + container.Id.slice(0, 12) + ' removed');
-      res.json({ success: true, message: 'OpenClaw removed' });
+      ok(res, { message: 'OpenClaw removed' });
     } catch(e) {
       log.error('Failed to remove OpenClaw: ' + e.message);
-      res.status(500).json({ success: false, error: e.message });
+      errorResponse(res, 500, e.message);
     }
   }));
 

dashcaddy-api/routes/recipes/deploy.js

@@ -1,7 +1,8 @@
 const express = require('express');
-const { ValidationError } = require('../../errors');
+const { ValidationError } = require('../../../src/utilities/errors');
 const crypto = require('crypto');
-const { DOCKER } = require('../../constants');
+const { DOCKER } = require('../../../src/utilities/constants');
+const { ok } = require('../src/utils/responses');
 
 /**
  * Recipes deployment routes factory
@@ -27,7 +28,7 @@ module.exports = function({ docker, credentialManager: _credentialManager, servi
   // eslint-disable-next-line complexity
   router.post('/deploy', asyncHandler(async (req, res) => {
     const { recipeId, config } = req.body;
-    const { RECIPE_TEMPLATES } = require('../../recipe-templates');
+    const { RECIPE_TEMPLATES } = require('../../../src/recipes/recipe-templates');
 
     const recipe = RECIPE_TEMPLATES[recipeId];
     if (!recipe) throw new ValidationError('Invalid recipe template', 'recipeId');
@@ -146,7 +147,7 @@ module.exports = function({ docker, credentialManager: _credentialManager, servi
         'success'
       );
 
-      res.json(response);
+      ok(res, response);
     } catch (error) {
       log.error('recipe', 'Recipe deployment failed', { recipeId, error: error.message });
 

dashcaddy-api/routes/recipes/index.js

@@ -1,7 +1,8 @@
 const express = require('express');
 const deployRoutes = require('./deploy');
 const manageRoutes = require('./manage');
-const { NotFoundError } = require('../../errors');
+const { NotFoundError } = require('../../../src/utilities/errors');
+const { ok } = require('../src/utils/responses');
 
 /**
  * Recipes routes aggregator
@@ -31,7 +32,7 @@ module.exports = function(ctx) {
 
   // GET /api/recipes/templates — list all recipe templates
   router.get('/templates', deps.asyncHandler(async (req, res) => {
-    const { RECIPE_TEMPLATES, RECIPE_CATEGORIES } = require('../../recipe-templates');
+    const { RECIPE_TEMPLATES, RECIPE_CATEGORIES } = require('../../../src/recipes/recipe-templates');
     const templates = Object.entries(RECIPE_TEMPLATES).map(([id, recipe]) => ({
       id,
       name: recipe.name,
@@ -55,16 +56,16 @@ module.exports = function(ctx) {
       setupInstructions: recipe.setupInstructions
     }));
 
-    res.json({ success: true, templates, categories: RECIPE_CATEGORIES });
+    ok(res, { templates, categories: RECIPE_CATEGORIES });
   }, 'recipe-templates'));
 
   // GET /api/recipes/templates/:recipeId — get single recipe template detail
   router.get('/templates/:recipeId', deps.asyncHandler(async (req, res) => {
-    const { RECIPE_TEMPLATES } = require('../../recipe-templates');
+    const { RECIPE_TEMPLATES } = require('../../../src/recipes/recipe-templates');
     const recipe = RECIPE_TEMPLATES[req.params.recipeId];
     if (!recipe) throw new NotFoundError(`Recipe template ${req.params.recipeId}`);
 
-    res.json({ success: true, recipe: { id: req.params.recipeId, ...recipe } });
+    ok(res, { recipe: { id: req.params.recipeId, ...recipe } });
   }, 'recipe-template-detail'));
 
   // Mount deploy and manage sub-routes — pass full ctx for sub-routes that reference ctx.*

dashcaddy-api/routes/recipes/manage.js

@@ -1,6 +1,7 @@
 const express = require('express');
-const { DOCKER } = require('../../constants');
-const { NotFoundError } = require('../../errors');
+const { DOCKER } = require('../../../src/utilities/constants');
+const { NotFoundError } = require('../../../src/utilities/errors');
+const { ok } = require('../src/utils/responses');
 
 module.exports = function({ servicesStateManager, asyncHandler, log, docker, notification, buildDomain, caddy }) {
   const router = express.Router();
@@ -98,7 +99,7 @@ module.exports = function({ servicesStateManager, asyncHandler, log, docker, not
       }
     }
 
-    res.json({ success: true, recipes: Object.values(recipeGroups) });
+    ok(res, { recipes: Object.values(recipeGroups) });
   }, 'recipe-deployed'));
 
   /**
@@ -129,7 +130,7 @@ module.exports = function({ servicesStateManager, asyncHandler, log, docker, not
     }
 
     log.info('recipe', 'Recipe started', { recipeId, results });
-    res.json({ success: true, recipeId, results });
+    ok(res, { recipeId, results });
   }, 'recipe-start'));
 
   /**
@@ -161,7 +162,7 @@ module.exports = function({ servicesStateManager, asyncHandler, log, docker, not
     }
 
     log.info('recipe', 'Recipe stopped', { recipeId, results });
-    res.json({ success: true, recipeId, results });
+    ok(res, { recipeId, results });
   }, 'recipe-stop'));
 
   /**
@@ -187,7 +188,7 @@ module.exports = function({ servicesStateManager, asyncHandler, log, docker, not
     }
 
     log.info('recipe', 'Recipe restarted', { recipeId, results });
-    res.json({ success: true, recipeId, results });
+    ok(res, { recipeId, results });
   }, 'recipe-restart'));
 
   /**
@@ -259,7 +260,7 @@ module.exports = function({ servicesStateManager, asyncHandler, log, docker, not
     );
 
     log.info('recipe', 'Recipe removed', { recipeId, results });
-    res.json({ success: true, recipeId, results });
+    ok(res, { recipeId, results });
   }, 'recipe-remove'));
 
   // === Helper functions ===
@@ -268,7 +269,7 @@ module.exports = function({ servicesStateManager, asyncHandler, log, docker, not
    * Find all Docker containers belonging to a recipe by label
    */
   async function findRecipeContainers(recipeId) {
-    const { RECIPE_TEMPLATES } = require('../../recipe-templates');
+    const { RECIPE_TEMPLATES } = require('../../../src/recipes/recipe-templates');
     const recipe = RECIPE_TEMPLATES[recipeId];
     const recipeLabel = recipe
       ? recipe.name.toLowerCase().replace(/\s+/g, '-')
@@ -292,7 +293,7 @@ module.exports = function({ servicesStateManager, asyncHandler, log, docker, not
    * Find recipe ID by its label (name slug)
    */
   function findRecipeIdByLabel(label) {
-    const { RECIPE_TEMPLATES } = require('../../recipe-templates');
+    const { RECIPE_TEMPLATES } = require('../../../src/recipes/recipe-templates');
     for (const [id, recipe] of Object.entries(RECIPE_TEMPLATES)) {
       if (recipe.name.toLowerCase().replace(/\s+/g, '-') === label) {
         return id;

dashcaddy-api/routes/services.js

@@ -4,12 +4,12 @@ const http = require('http');
 const https = require('https');
 const tls = require('tls');
 const validatorLib = require('validator');
-const { APP, REGEX, TIMEOUTS } = require('../constants');
-const { validateServiceConfig, isValidPort } = require('../input-validator');
-const { exists } = require('../fs-helpers');
-const { paginate, parsePaginationParams } = require('../pagination');
-const { ValidationError, NotFoundError, ConflictError } = require('../errors');
-const { resolveServiceUrl } = require('../url-resolver');
+const { APP, REGEX, TIMEOUTS } = require('../src/utilities/constants');
+const { validateServiceConfig, isValidPort } = require('../src/security/input-validator');
+const { exists } = require('../src/utilities/fs-helpers');
+const { paginate, parsePaginationParams } = require('../src/utilities/pagination');
+const { ValidationError, NotFoundError, ConflictError } = require('../src/utilities/errors');
+const { resolveServiceUrl } = require('../src/utilities/url-resolver');
 const { success, error: errorResponse } = require('../src/utils/responses');
 const platformPaths = require('../platform-paths');
 
@@ -197,7 +197,7 @@ module.exports = function({
   // ===== SERVICE CREDENTIAL ENDPOINTS =====
 
   // Store credentials for a service
-  router.post('/:serviceId/credentials', asyncHandler(async (req, res) => {
+  router.post('/services/:serviceId/credentials', asyncHandler(async (req, res) => {
     const { serviceId } = req.params;
 
     // Validate serviceId to prevent path traversal in credential keys
@@ -221,7 +221,7 @@ module.exports = function({
   }, 'store-service-creds'));
 
   // Delete credentials for a service
-  router.delete('/:serviceId/credentials', asyncHandler(async (req, res) => {
+  router.delete('/services/:serviceId/credentials', asyncHandler(async (req, res) => {
     const { serviceId } = req.params;
 
     // Validate serviceId to prevent path traversal in credential keys
@@ -236,7 +236,7 @@ module.exports = function({
   }, 'delete-service-creds'));
 
   // Check credential status for a service (what's stored)
-  router.get('/:serviceId/credentials', asyncHandler(async (req, res) => {
+  router.get('/services/:serviceId/credentials', asyncHandler(async (req, res) => {
     const { serviceId } = req.params;
 
     // Validate serviceId to prevent path traversal in credential keys
@@ -356,9 +356,11 @@ module.exports = function({
   }, 'services-status'));
 
   // List all services
+  // Always returns the standard envelope. The `services` field is the array
+  // (paginated if ?page=N&limit=M is in the query, otherwise the full list).
   router.get('/services', asyncHandler(async (req, res) => {
     if (!await exists(SERVICES_FILE)) {
-      return res.json([]);
+      return success(res, { services: [] });
     }
     const services = await servicesStateManager.read();
     const paginationParams = parsePaginationParams(req.query);
@@ -366,7 +368,7 @@ module.exports = function({
     if (paginationParams) {
       success(res, { services: result.data, pagination: result.pagination });
     } else {
-      res.json(result.data);
+      success(res, { services: result.data });
     }
   }, 'services-list'));
 

dashcaddy-api/routes/sites.js

@@ -1,9 +1,9 @@
 const express = require('express');
 const fs = require('fs');
-const { CADDY, REGEX, LIMITS } = require('../constants');
-const { ValidationError, ConflictError, NotFoundError } = require('../errors');
-const { validateURL } = require('../input-validator');
-const { ok } = require('../src/utils/responses');
+const { CADDY, REGEX, LIMITS } = require('../src/utilities/constants');
+const { ValidationError, ConflictError, NotFoundError } = require('../src/utilities/errors');
+const { validateURL } = require('../src/security/input-validator');
+const { ok, successMessage } = require('../src/utils/responses');
 
 /**
  * Sites route factory
@@ -24,14 +24,14 @@ module.exports = function({ asyncHandler, caddy, dns, fetchT, buildDomain, addSe
   // Get Caddyfile contents
   router.get('/caddyfile', asyncHandler(async (req, res) => {
     const content = await caddy.read();
-    res.json({ success: true, content });
+    ok(res, { content });
   }, 'caddyfile-get'));
 
   // Get current Caddy config (from admin API)
   router.get('/caddy/config', asyncHandler(async (req, res) => {
     const response = await fetchT(`${caddy.adminUrl}/config/`);
     const config = await response.json();
-    res.json({ success: true, config });
+    ok(res, { config });
   }, 'caddy-config'));
 
   // Reload Caddy configuration via admin API
@@ -50,7 +50,7 @@ module.exports = function({ asyncHandler, caddy, dns, fetchT, buildDomain, addSe
       throw new Error('Caddy reload failed. Check server logs for details.');
     }
 
-    res.json({ success: true, message: 'Caddy configuration reloaded successfully' });
+    successMessage(res, 'Caddy configuration reloaded successfully');
   }, 'caddy-reload'));
 
   // Get Certificate Authorities from Caddyfile
@@ -153,7 +153,7 @@ module.exports = function({ asyncHandler, caddy, dns, fetchT, buildDomain, addSe
       throw new NotFoundError(`Site block for "" in Caddyfile`);
     }
 
-    res.json({ success: true, message: `Site "${domain}" removed from Caddyfile and Caddy reloaded` });
+    successMessage(res, `Site "${domain}" removed from Caddyfile and Caddy reloaded`);
   }, 'site-delete'));
 
   // Add a new site to Caddyfile and reload
@@ -181,7 +181,7 @@ module.exports = function({ asyncHandler, caddy, dns, fetchT, buildDomain, addSe
         result.rolledBack ? { note: 'Caddyfile was rolled back to previous state' } : {});
     }
 
-    res.json({ success: true, message: `Site "${domain}" added to Caddyfile and Caddy reloaded successfully` });
+    successMessage(res, `Site "${domain}" added to Caddyfile and Caddy reloaded successfully`);
   }, 'site-add'));
 
   // Add external service reverse proxy to Caddyfile
@@ -261,12 +261,11 @@ module.exports = function({ asyncHandler, caddy, dns, fetchT, buildDomain, addSe
         }
       }
 
-      const response = {
-        success: true,
+      const responseData = {
         message: `External service proxy for ${domain} -> ${externalUrl} created${shouldReload ? ' and Caddy reloaded' : ''}`
       };
-      if (dnsWarning) response.warning = dnsWarning;
-      res.json(response);
+      if (dnsWarning) responseData.warning = dnsWarning;
+      ok(res, responseData);
   }, 'site-external'));
 
   return router;

dashcaddy-api/routes/tailscale.js

@@ -1,8 +1,9 @@
 const express = require('express');
 const fs = require('fs');
-const { TAILSCALE } = require('../constants');
-const { exists } = require('../fs-helpers');
-const { ValidationError, NotFoundError } = require('../errors');
+const { TAILSCALE } = require('../src/utilities/constants');
+const { exists } = require('../src/utilities/fs-helpers');
+const { ValidationError, NotFoundError } = require('../src/utilities/errors');
+const { ok, successMessage, unauthorized } = require('../src/utils/responses');
 
 /**
  * Tailscale route factory
@@ -35,8 +36,7 @@ module.exports = function({
     const localIP = await tailscale.getLocalIP();
 
     if (!status) {
-      return res.json({
-        success: true,
+      return ok(res, {
         installed: false,
         connected: false,
         message: 'Tailscale not available or not running'
@@ -58,8 +58,7 @@ module.exports = function({
       }
     }
 
-    res.json({
-      success: true,
+    ok(res, {
       installed: true,
       connected: status.BackendState === 'Running',
       backendState: status.BackendState,
@@ -85,8 +84,7 @@ module.exports = function({
 
     await tailscale.save();
 
-    res.json({
-      success: true,
+    ok(res, {
       message: 'Tailscale configuration updated',
       config: tailscale.config
     });
@@ -101,8 +99,7 @@ module.exports = function({
     const ipsToCheck = [clientIP, forwardedFor, realIP].filter(Boolean);
     const isTailscale = ipsToCheck.some(ip => tailscale.isTailscaleIP(ip.toString().split(',')[0].trim()));
 
-    res.json({
-      success: true,
+    ok(res, {
       isTailscale,
       clientIP,
       forwardedFor: forwardedFor || null,
@@ -114,7 +111,7 @@ module.exports = function({
   router.get('/devices', asyncHandler(async (req, res) => {
     const status = await tailscale.getStatus();
     if (!status || !status.Peer) {
-      return res.json({ success: true, devices: [] });
+      return ok(res, { devices: [] });
     }
 
     const devices = [];
@@ -141,7 +138,7 @@ module.exports = function({
       });
     }
 
-    res.json({ success: true, devices });
+    ok(res, { devices });
   }, 'tailscale-devices'));
 
   // Toggle Tailscale-only mode for an existing service
@@ -159,7 +156,7 @@ module.exports = function({
     const match = content.match(blockRegex);
 
     if (!match) {
-      const { NotFoundError } = require('../errors');
+      const { NotFoundError } = require('../src/utilities/errors');
       throw new NotFoundError(`Service ${domain} in Caddyfile`);
     }
 
@@ -190,8 +187,7 @@ module.exports = function({
       });
     }
 
-    res.json({
-      success: true,
+    ok(res, {
       message: `Service ${domain} is now ${tailscaleOnly !== false ? 'protected by' : 'no longer restricted to'} Tailscale`,
       tailscaleOnly: tailscaleOnly !== false
     });
@@ -254,7 +250,7 @@ module.exports = function({
       log.warn('tailscale', 'Initial sync after OAuth config failed', { error: e.message });
     }
 
-    res.json({ success: true, config: tailscale.config });
+    ok(res, { config: tailscale.config });
   }, 'tailscale-oauth-config'));
 
   // Remove OAuth credentials and disable API sync
@@ -269,7 +265,7 @@ module.exports = function({
 
     tailscale.stopSync();
 
-    res.json({ success: true, message: 'Tailscale OAuth credentials removed' });
+    successMessage(res, 'Tailscale OAuth credentials removed');
   }, 'tailscale-oauth-delete'));
 
   // Get enriched device list from Tailscale API
@@ -279,8 +275,7 @@ module.exports = function({
     }
 
     // Return cached devices from last sync
-    res.json({
-      success: true,
+    ok(res, {
       devices: tailscale.config.devices || [],
       lastSync: tailscale.config.lastSync
     });
@@ -294,8 +289,7 @@ module.exports = function({
 
     const devices = await tailscale.syncAPI();
 
-    res.json({
-      success: true,
+    ok(res, {
       devices: devices || [],
       lastSync: tailscale.config.lastSync
     });
@@ -325,7 +319,7 @@ module.exports = function({
       sshRuleCount: (acl.ssh || []).length
     };
 
-    res.json({ success: true, acl, summary });
+    ok(res, { acl, summary });
   }, 'tailscale-acl'));
 
   return router;

dashcaddy-api/routes/themes.js

@@ -2,7 +2,7 @@ const express = require('express');
 const fs = require('fs');
 const path = require('path');
 const { success } = require('../src/utils/responses');
-const { ValidationError, NotFoundError } = require('../errors');
+const { ValidationError, NotFoundError } = require('../src/utilities/errors');
 const platformPaths = require('../platform-paths');
 
 /**

dashcaddy-api/routes/updates.js

@@ -1,6 +1,7 @@
 const express = require('express');
-const { paginate, parsePaginationParams } = require('../pagination');
-const { ValidationError } = require('../errors');
+const { paginate, parsePaginationParams } = require('../src/utilities/pagination');
+const { ValidationError } = require('../src/utilities/errors');
+const { ok, successMessage } = require('../src/utils/responses');
 
 /**
  * Updates route factory
@@ -20,7 +21,7 @@ module.exports = function({ updateManager, selfUpdater, asyncHandler, logError }
   router.post('/updates/check', asyncHandler(async (req, res) => {
     await updateManager.checkForUpdates();
     const updates = updateManager.getAvailableUpdates();
-    res.json({ success: true, updates, count: updates.length });
+    ok(res, { updates, count: updates.length });
   }, 'updates-check'));
 
   // Get available updates
@@ -28,19 +29,19 @@ module.exports = function({ updateManager, selfUpdater, asyncHandler, logError }
     const updates = updateManager.getAvailableUpdates();
     const paginationParams = parsePaginationParams(req.query);
     const result = paginate(updates, paginationParams);
-    res.json({ success: true, updates: result.data, count: updates.length, ...(result.pagination && { pagination: result.pagination }) });
+    ok(res, { updates: result.data, count: updates.length, ...(result.pagination && { pagination: result.pagination }) });
   }, 'updates-available'));
 
   // Update a container
   router.post('/updates/update/:containerId', asyncHandler(async (req, res) => {
     const result = await updateManager.updateContainer(req.params.containerId, req.body);
-    res.json({ success: true, result });
+    ok(res, { result });
   }, 'updates-update'));
 
   // Rollback update
   router.post('/updates/rollback/:containerId', asyncHandler(async (req, res) => {
     await updateManager.rollbackUpdate(req.params.containerId);
-    res.json({ success: true, message: 'Rollback completed' });
+    successMessage(res, 'Rollback completed');
   }, 'updates-rollback'));
 
   // Get update history
@@ -50,19 +51,19 @@ module.exports = function({ updateManager, selfUpdater, asyncHandler, logError }
     const fetchLimit = paginationParams ? Number.MAX_SAFE_INTEGER : (parseInt(req.query.limit) || 50);
     const history = updateManager.getHistory(fetchLimit);
     const result = paginate(history, paginationParams);
-    res.json({ success: true, history: result.data, ...(result.pagination && { pagination: result.pagination }) });
+    ok(res, { history: result.data, ...(result.pagination && { pagination: result.pagination }) });
   }, 'updates-history'));
 
   // Configure auto-update
   router.post('/updates/auto-update/:containerId', asyncHandler(async (req, res) => {
     updateManager.configureAutoUpdate(req.params.containerId, req.body);
-    res.json({ success: true, message: 'Auto-update configured' });
+    successMessage(res, 'Auto-update configured');
   }, 'updates-auto-update'));
 
   // Get auto-update configuration
   router.get('/updates/auto-update', asyncHandler(async (req, res) => {
     const config = updateManager.getAutoUpdateConfig();
-    res.json({ success: true, config });
+    ok(res, { config });
   }, 'updates-auto-update-config'));
 
   // Schedule update
@@ -72,7 +73,7 @@ module.exports = function({ updateManager, selfUpdater, asyncHandler, logError }
       throw new ValidationError('scheduledTime is required');
     }
     updateManager.scheduleUpdate(req.params.containerId, scheduledTime);
-    res.json({ success: true, message: 'Update scheduled', scheduledTime });
+    ok(res, { message: 'Update scheduled', scheduledTime });
   }, 'updates-schedule'));
 
   // ===== DASHCADDY SELF-UPDATE ENDPOINTS =====
@@ -80,20 +81,20 @@ module.exports = function({ updateManager, selfUpdater, asyncHandler, logError }
   // Get current version
   router.get('/system/version', asyncHandler(async (req, res) => {
     const local = selfUpdater.getLocalVersion();
-    res.json({ success: true, name: 'DashCaddy', version: local.version, commit: local.commit });
+    ok(res, { name: 'DashCaddy', version: local.version, commit: local.commit });
   }, 'system-version'));
 
   // Check for DashCaddy update
   router.get('/system/update-check', asyncHandler(async (req, res) => {
     const result = await selfUpdater.checkForUpdate();
-    res.json({ success: true, ...result });
+    ok(res, result);
   }, 'system-update-check'));
 
   // Apply available update
   router.post('/system/update-apply', asyncHandler(async (req, res) => {
     const check = await selfUpdater.checkForUpdate();
     if (!check.available) {
-      return res.json({ success: true, message: 'Already up to date' });
+      return successMessage(res, 'Already up to date');
     }
     // Refuse same-version applies. The check.available flag can theoretically be
     // true with equal versions (commit-mismatch path); applying anyway just
@@ -102,14 +103,13 @@ module.exports = function({ updateManager, selfUpdater, asyncHandler, logError }
     const localV = check.local && check.local.version;
     const remoteV = check.remote && check.remote.version;
     if (localV && remoteV && localV === remoteV) {
-      return res.json({ success: true, message: 'Already up to date', version: localV });
+      return ok(res, { message: 'Already up to date', version: localV });
     }
     // Start async — container may restart
     selfUpdater.applyUpdate(check.remote).catch(err => {
       logError('self-update', err);
     });
-    res.json({
-      success: true,
+    ok(res, {
       message: 'Update initiated',
       fromVersion: localV,
       toVersion: remoteV,
@@ -132,16 +132,15 @@ module.exports = function({ updateManager, selfUpdater, asyncHandler, logError }
       presentedBuf.length > 0 &&
       require('crypto').timingSafeEqual(presentedBuf, expectedBuf);
     if (!ok) {
-      return res.status(401).json({ success: false, error: 'Invalid notify secret' });
+      return unauthorized(res, 'Invalid notify secret');
     }
     const result = selfUpdater.notifyAndApply('http-notify');
-    res.json({ success: true, ...result });
+    ok(res, result);
   }, 'system-update-notify'));
 
   // Get update status
   router.get('/system/update-status', asyncHandler(async (req, res) => {
-    res.json({
-      success: true,
+    ok(res, {
       status: selfUpdater.getStatus(),
       lastCheck: selfUpdater.lastCheckTime,
       lastResult: selfUpdater.lastCheckResult,
@@ -151,13 +150,13 @@ module.exports = function({ updateManager, selfUpdater, asyncHandler, logError }
   // Get self-update history
   router.get('/system/update-history', asyncHandler(async (req, res) => {
     const history = selfUpdater.getUpdateHistory();
-    res.json({ success: true, history });
+    ok(res, { history });
   }, 'system-update-history'));
 
   // List rollback versions
   router.get('/system/rollback-versions', asyncHandler(async (req, res) => {
     const versions = selfUpdater.getAvailableRollbacks();
-    res.json({ success: true, versions });
+    ok(res, { versions });
   }, 'system-rollback-versions'));
 
   // Rollback to a previous version
@@ -167,7 +166,7 @@ module.exports = function({ updateManager, selfUpdater, asyncHandler, logError }
     selfUpdater.rollbackToVersion(version).catch(err => {
       logError('self-rollback', err);
     });
-    res.json({ success: true, message: `Rollback to ${version} initiated` });
+    ok(res, { message: `Rollback to ${version} initiated` });
   }, 'system-rollback'));
 
   return router;

dashcaddy-api/routes/workflows.js

@@ -1,4 +1,5 @@
 const express = require('express');
+const { ok } = require('../src/utils/responses');
 
 /**
  * Workflows routes factory
@@ -19,21 +20,21 @@ module.exports = function({ workflowEngine, licenseManager, asyncHandler }) {
   // List all bundled workflows
   router.get('/workflows', asyncHandler(async (req, res) => {
     const workflows = workflowEngine.listWorkflows();
-    res.json({ success: true, workflows });
+    ok(res, { workflows });
   }, 'workflows-list'));
   
   // Enable a workflow
   router.post('/workflows/:workflowId/enable', asyncHandler(async (req, res) => {
     const { workflowId } = req.params;
     const result = workflowEngine.setWorkflowEnabled(workflowId, true);
-    res.json({ success: true, ...result });
+    ok(res, result);
   }, 'workflows-enable'));
   
   // Disable a workflow
   router.post('/workflows/:workflowId/disable', asyncHandler(async (req, res) => {
     const { workflowId } = req.params;
     const result = workflowEngine.setWorkflowEnabled(workflowId, false);
-    res.json({ success: true, ...result });
+    ok(res, result);
   }, 'workflows-disable'));
   
   // Manually trigger a workflow
@@ -43,7 +44,7 @@ module.exports = function({ workflowEngine, licenseManager, asyncHandler }) {
     triggerData.trigger = 'manual';
     
     const result = await workflowEngine.executeWorkflow(workflowId, triggerData);
-    res.json({ success: true, result });
+    ok(res, { result });
   }, 'workflows-run'));
   
   // Get execution history for a workflow
@@ -51,14 +52,14 @@ module.exports = function({ workflowEngine, licenseManager, asyncHandler }) {
     const { workflowId } = req.params;
     const limit = parseInt(req.query.limit) || 50;
     const history = workflowEngine.getHistory(workflowId, limit);
-    res.json({ success: true, history });
+    ok(res, { history });
   }, 'workflows-history'));
   
   // Get all workflow execution history
   router.get('/workflows/history', asyncHandler(async (req, res) => {
     const limit = parseInt(req.query.limit) || 100;
     const history = workflowEngine.getHistory(null, limit);
-    res.json({ success: true, history });
+    ok(res, { history });
   }, 'workflows-all-history'));
   
   return router;

dashcaddy-api/scripts/fix-remaining-paths.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""
+Fix the remaining broken require paths after DC-005 refactor.
+
+Two patterns to fix:
+1. `require('./src/...')` and `require('../../src/...')` and `require('../../../src/...')`
+   in files inside `src/` directories → should be `require('../...')` (relative to src/)
+2. `require('../../../src/...')` in test files in `__tests__/` → should be `require('../src/...')`
+"""
+import os
+import re
+from pathlib import Path
+
+DASHCADDY_API = Path('/root/dashcaddy-krystie/dashcaddy-api')
+
+# Pattern to match require('../../../src/X/Y') and capture
+# We need to detect the file's location and rewrite based on that
+# A simple approach: find any require that contains 'src/' in the path,
+# and rewrite it to be relative to the file's location.
+
+def fix_file(filepath: Path) -> bool:
+    """Returns True if file was changed."""
+    content = filepath.read_text()
+    original = content
+
+    # Find the file's directory relative to dashcaddy-api root
+    rel_dir = filepath.parent.relative_to(DASHCADDY_API)
+    depth = len(rel_dir.parts)
+
+    # If file is in src/X/Y/file.js, depth is 3 (src, X, Y)
+    # If file is in __tests__/file.js, depth is 1
+    # If file is in __tests__/routes/file.js, depth is 2
+
+    # Find all require() calls that contain 'src/'
+    # Pattern: require('(.....)*src/path')
+    def replacer(match):
+        quote = match.group(1)  # the quote char
+        path = match.group(2)   # the path inside quotes
+        # Calculate what the path SHOULD be
+        if 'src/' not in path:
+            return match.group(0)
+
+        # Extract the part after 'src/'
+        idx = path.find('src/')
+        after_src = path[idx + 4:]  # everything after 'src/'
+
+        if filepath.parts[-3] == 'src':
+            # File is in src/X/file.js - depth 3
+            # Should be '../<after_src>'
+            new_path = '../' + after_src
+        elif filepath.parts[-4] == 'src':
+            # File is in src/X/Y/file.js - depth 4
+            # Should be '../../<after_src>'
+            new_path = '../../' + after_src
+        elif filepath.parts[-2] == '__tests__' or filepath.parent.name == '__tests__':
+            # File is in __tests__/file.js - depth 1 (relative to api root)
+            # Should be '../src/<after_src>'
+            new_path = '../src/' + after_src
+        elif filepath.parts[-2] == 'routes' and filepath.parts[-3] == '__tests__':
+            # File is in __tests__/routes/file.js - depth 2
+            # Should be '../../src/<after_src>'
+            new_path = '../../src/' + after_src
+        elif 'src' in rel_dir.parts:
+            # Other src nested location
+            # Count how many .. we need
+            src_depth = len(rel_dir.parts) - list(rel_dir.parts).index('src') - 1
+            new_path = '../' * src_depth + after_src
+        else:
+            # Other location, leave it
+            return match.group(0)
+
+        return f"require({quote}{new_path}{quote})"
+
+    new_content = re.sub(
+        r"require\((['\"])([^'\"]*src/[^'\"]*)\1\)",
+        replacer,
+        content
+    )
+
+    if new_content != original:
+        filepath.write_text(new_content)
+        return True
+    return False
+
+
+def main():
+    changed = []
+    for js_file in DASHCADDY_API.rglob('*.js'):
+        # Skip node_modules
+        if 'node_modules' in js_file.parts:
+            continue
+        if fix_file(js_file):
+            changed.append(str(js_file.relative_to(DASHCADDY_API)))
+
+    print(f"Changed {len(changed)} files:")
+    for f in changed:
+        print(f"  {f}")
+
+
+if __name__ == '__main__':
+    main()

dashcaddy-api/scripts/refactor-requires.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+/**
+ * Refactor helper: rewrites require('./xxx') / require('../xxx') paths in
+ * dashcaddy-api to point to the new src/<subdir>/xxx.js locations.
+ *
+ * Algorithm:
+ *   1. For each require() call with a relative spec:
+ *   2. If the resolved file exists, leave it alone.
+ *   3. If the resolved file does NOT exist, the bare name of the spec
+ *      (or the directory name 'dns-providers') might be one of the
+ *      modules that was moved out of the repo root. In that case, rewrite
+ *      the spec to the correct relative path to the new location.
+ *   4. Otherwise leave alone.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const REPO = process.cwd();
+
+// Map: bare module name (no extension) -> new repo-relative path (no extension)
+const NEW_LOCATIONS = {
+  'auth-manager': 'src/managers/auth-manager',
+  'credential-manager': 'src/managers/credential-manager',
+  'license-manager': 'src/managers/license-manager',
+  'port-lock-manager': 'src/managers/port-lock-manager',
+  'state-manager': 'src/managers/state-manager',
+  'notification-manager': 'src/managers/notification-manager',
+  'resource-monitor': 'src/managers/resource-monitor',
+  'config-drift-detector': 'src/managers/config-drift-detector',
+  'auto-restart-manager': 'src/managers/auto-restart-manager',
+  'update-manager': 'src/managers/update-manager',
+  'dependency-manager': 'src/managers/dependency-manager',
+  'csrf-protection': 'src/security/csrf-protection',
+  'crypto-utils': 'src/security/crypto-utils',
+  'docker-security': 'src/security/docker-security',
+  'input-validator': 'src/security/input-validator',
+  'keychain-manager': 'src/security/keychain-manager',
+  'log-digest': 'src/security/log-digest',
+  'audit-logger': 'src/security/audit-logger',
+  'docker-maintenance': 'src/docker/docker-maintenance',
+  'app-templates': 'src/docker/app-templates',
+  'self-updater': 'src/docker/self-updater',
+  'dns-propagation': 'src/dns/dns-propagation',
+  'recipe-templates': 'src/recipes/recipe-templates',
+  'bundled-workflows': 'src/recipes/bundled-workflows',
+  'health-checker': 'src/monitoring/health-checker',
+  'metrics': 'src/monitoring/metrics',
+  'ssl-monitor': 'src/monitoring/ssl-monitor',
+  'backup-manager': 'src/utilities/backup-manager',
+  'error-handler': 'src/utilities/error-handler',
+  'errors': 'src/utilities/errors',
+  'fs-helpers': 'src/utilities/fs-helpers',
+  'pagination': 'src/utilities/pagination',
+  'url-resolver': 'src/utilities/url-resolver',
+  'config-schema': 'src/utilities/config-schema',
+  'constants': 'src/utilities/constants',
+  'middleware': 'src/utilities/middleware',
+  'startup-validator': 'src/utilities/startup-validator',
+  'cache-config': 'src/utilities/cache-config',
+};
+
+const SKIP_DIRS = new Set(['node_modules', '.git']);
+const SKIP_FILE_PATTERNS = [/\/scripts\/refactor-requires\.js$/];
+
+function* walk(dir) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (SKIP_DIRS.has(entry.name)) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walk(full);
+    } else if (entry.name.endsWith('.js')) {
+      yield full;
+    }
+  }
+}
+
+function toRelativeFromFile(filePath, targetRel) {
+  const fromDir = path.dirname(filePath);
+  const targetAbs = path.resolve(REPO, targetRel);
+  let rel = path.relative(fromDir, targetAbs);
+  if (!rel.startsWith('.')) rel = './' + rel;
+  return rel.split(path.sep).join('/');
+}
+
+function fileExistsWithJsOrIndex(p) {
+  // exists if p is a file, or p is a dir with index.js
+  try {
+    if (fs.existsSync(p) && fs.statSync(p).isFile()) return true;
+  } catch (_) {}
+  try {
+    if (fs.existsSync(p + '.js') && fs.statSync(p + '.js').isFile()) return true;
+  } catch (_) {}
+  try {
+    if (
+      fs.existsSync(p) &&
+      fs.statSync(p).isDirectory() &&
+      fs.existsSync(path.join(p, 'index.js'))
+    )
+      return true;
+  } catch (_) {}
+  return false;
+}
+
+function refactor(filePath) {
+  const relFile = path.relative(REPO, filePath);
+  if (SKIP_FILE_PATTERNS.some((re) => re.test(relFile))) return false;
+
+  const content = fs.readFileSync(filePath, 'utf8');
+  let changed = false;
+
+  const requireRe = /require\(\s*(['"])([^'"]+)\1\s*\)/g;
+  const newContent = content.replace(requireRe, (full, quote, spec) => {
+    if (!spec.startsWith('.')) return full; // package require, leave alone
+    const fromDir = path.dirname(filePath);
+    const resolvedBase = path.resolve(fromDir, spec);
+    // If the resolved file exists, the require is correct as-is.
+    if (fileExistsWithJsOrIndex(resolvedBase)) {
+      // But — check for the special case: require to <REPO>/dns-providers/x
+      // which after move becomes <REPO>/src/dns/dns-providers/x — wait,
+      // that doesn't exist anymore. The dir was moved.
+      const dnsProvidersOld = path.resolve(REPO, 'dns-providers');
+      if (
+        resolvedBase === dnsProvidersOld ||
+        resolvedBase.startsWith(dnsProvidersOld + path.sep)
+      ) {
+        const subPath = resolvedBase === dnsProvidersOld ? '' : resolvedBase.slice(dnsProvidersOld.length + 1);
+        const newResolved = path.resolve(REPO, 'src/dns/dns-providers', subPath);
+        let rel = path.relative(fromDir, newResolved);
+        if (!rel.startsWith('.')) rel = './' + rel;
+        const newSpec = rel.split(path.sep).join('/');
+        changed = true;
+        return `require(${quote}${newSpec}${quote})`;
+      }
+      return full;
+    }
+    // The file does not exist. Check if the bare name is a moved module.
+    const bare = path.basename(resolvedBase);
+    if (bare in NEW_LOCATIONS) {
+      const target = NEW_LOCATIONS[bare];
+      const newSpec = toRelativeFromFile(filePath, target);
+      changed = true;
+      return `require(${quote}${newSpec}${quote})`;
+    }
+    // Bare not in map. Check for the special case: the spec points into
+    // the OLD dns-providers dir (now src/dns/dns-providers). E.g. spec
+    // could be '../dns-providers/registry' or './dns-providers/registry'
+    // from somewhere else.
+    if (spec.includes('dns-providers')) {
+      const dnsProvidersOld = path.resolve(REPO, 'dns-providers');
+      if (
+        resolvedBase === dnsProvidersOld ||
+        resolvedBase.startsWith(dnsProvidersOld + path.sep)
+      ) {
+        const subPath =
+          resolvedBase === dnsProvidersOld ? '' : resolvedBase.slice(dnsProvidersOld.length + 1);
+        const newResolved = path.resolve(REPO, 'src/dns/dns-providers', subPath);
+        let rel = path.relative(fromDir, newResolved);
+        if (!rel.startsWith('.')) rel = './' + rel;
+        const newSpec = rel.split(path.sep).join('/');
+        changed = true;
+        return `require(${quote}${newSpec}${quote})`;
+      }
+    }
+    return full;
+  });
+
+  if (changed) {
+    fs.writeFileSync(filePath, newContent);
+  }
+  return changed;
+}
+
+let count = 0;
+for (const file of walk(REPO)) {
+  if (refactor(file)) {
+    count += 1;
+    console.log('rewrote', path.relative(REPO, file));
+  }
+}
+console.log(`\nDone: rewrote ${count} file(s).`);

dashcaddy-api/server.js

@@ -33,7 +33,7 @@ process.on('uncaughtException', (error) => {
     const CONFIG_FILE = process.env.CONFIG_FILE || platformPaths.servicesFile.replace('services.json', 'config.json');
 
     // Validate startup configuration
-    const { validateStartupConfig } = require('./startup-validator');
+    const { validateStartupConfig } = require('../src/utilities/startup-validator');
     await validateStartupConfig({
       log,
       CADDYFILE_PATH,
@@ -56,23 +56,23 @@ process.on('uncaughtException', (error) => {
 
       // Attach WebSocket exec handler (with auth)
       const attachExecWS = require('./routes/exec');
-      const authManager = require('./auth-manager');
+      const authManager = require('../src/managers/auth-manager');
       attachExecWS(server, log, authManager);
       log.info('server', 'WebSocket exec handler attached (auth enforced)');
 
       // Start feature modules
-      const resourceMonitor = require('./resource-monitor');
-      const backupManager = require('./backup-manager');
-      const healthChecker = require('./health-checker');
-      const updateManager = require('./update-manager');
-      const selfUpdater = require('./self-updater');
-      const portLockManager = require('./port-lock-manager');
+      const resourceMonitor = require('../src/managers/resource-monitor');
+      const backupManager = require('../src/utilities/backup-manager');
+      const healthChecker = require('../src/monitoring/health-checker');
+      const updateManager = require('../src/managers/update-manager');
+      const selfUpdater = require('../src/docker/self-updater');
+      const portLockManager = require('../src/managers/port-lock-manager');
 
       // Optional modules
       let dockerMaintenance, logDigest, bundledWorkflows;
-      try { dockerMaintenance = require('./docker-maintenance'); } catch { /* optional */ }
-      try { logDigest = require('./log-digest'); } catch { /* optional */ }
-      try { bundledWorkflows = require('./bundled-workflows'); } catch { /* optional */ }
+      try { dockerMaintenance = require('../src/docker/docker-maintenance'); } catch { /* optional */ }
+      try { logDigest = require('../src/security/log-digest'); } catch { /* optional */ }
+      try { bundledWorkflows = require('../src/recipes/bundled-workflows'); } catch { /* optional */ }
 
       // Initialize workflow engine if bundled-workflows is available
       // NOTE: createApp() already initializes the workflow engine in src/app.js
@@ -85,7 +85,7 @@ process.on('uncaughtException', (error) => {
           // Create a context with needed services
           const workflowCtx = {
             docker: { client: require('dockerode')() },
-            notification: require('./notification-manager')({ 
+            notification: require('../src/managers/notification-manager')({ 
               NOTIFICATIONS_FILE: process.env.NOTIFICATIONS_FILE || require('./platform-paths').notificationsFile,
               fetchT,
               log,
@@ -137,8 +137,8 @@ process.on('uncaughtException', (error) => {
       // Health checker (with service sync)
       (async () => {
         try {
-          const { syncHealthCheckerServices } = require('./startup-validator');
-          const StateManager = require('./state-manager');
+          const { syncHealthCheckerServices } = require('../src/utilities/startup-validator');
+          const StateManager = require('../src/managers/state-manager');
           const servicesStateManager = new StateManager(SERVICES_FILE);
           
           await syncHealthCheckerServices({
@@ -150,7 +150,7 @@ process.on('uncaughtException', (error) => {
               ? `https://${config.domain}/${subdomain}`
               : `https://${subdomain}${config.tld}`,
             siteConfig: config,
-            APP: require('./constants').APP
+            APP: require('../src/utilities/constants').APP
           });
           
           healthChecker.start();
@@ -232,11 +232,11 @@ process.on('uncaughtException', (error) => {
     const shutdown = (signal) => {
       log.info('shutdown', `${signal} received, draining connections...`);
       
-      const resourceMonitor = require('./resource-monitor');
-      const backupManager = require('./backup-manager');
-      const healthChecker = require('./health-checker');
-      const updateManager = require('./update-manager');
-      const selfUpdater = require('./self-updater');
+      const resourceMonitor = require('../src/managers/resource-monitor');
+      const backupManager = require('../src/utilities/backup-manager');
+      const healthChecker = require('../src/monitoring/health-checker');
+      const updateManager = require('../src/managers/update-manager');
+      const selfUpdater = require('../src/docker/self-updater');
       
       resourceMonitor.stop();
       backupManager.stop();
@@ -245,12 +245,12 @@ process.on('uncaughtException', (error) => {
       selfUpdater.stop();
       
       try {
-        const dockerMaintenance = require('./docker-maintenance');
+        const dockerMaintenance = require('../src/docker/docker-maintenance');
         dockerMaintenance.stop();
       } catch { /* optional */ }
       
       try {
-        const logDigest = require('./log-digest');
+        const logDigest = require('../src/security/log-digest');
         logDigest.stop();
       } catch { /* optional */ }
 

dashcaddy-api/src/app.js

@@ -15,41 +15,41 @@ const { errorResponse, ok } = require('./utils/responses');
 const { asyncHandler } = require('./utils/async-handler');
 
 // Managers and utilities
-const StateManager = require('../state-manager');
+const StateManager = require('managers/state-manager');
 const platformPaths = require('../platform-paths');
-const { LicenseManager } = require('../license-manager');
-const credentialManager = require('../credential-manager');
-const authManager = require('../auth-manager');
-const dockerSecurity = require('../docker-security');
-const auditLogger = require('../audit-logger');
-const portLockManager = require('../port-lock-manager');
-const resourceMonitor = require('../resource-monitor');
-const backupManager = require('../backup-manager');
-const healthChecker = require('../health-checker');
-const updateManager = require('../update-manager');
-const selfUpdater = require('../self-updater');
-const configureMiddleware = require('../middleware');
-const { validateStartupConfig, syncHealthCheckerServices } = require('../startup-validator');
-const { CSRF_HEADER_NAME } = require('../csrf-protection');
-const { resolveServiceUrl } = require('../url-resolver');
-const metrics = require('../metrics');
-const { validateURL } = require('../input-validator');
+const { LicenseManager } = require('managers/license-manager');
+const credentialManager = require('managers/credential-manager');
+const authManager = require('managers/auth-manager');
+const dockerSecurity = require('security/docker-security');
+const auditLogger = require('security/audit-logger');
+const portLockManager = require('managers/port-lock-manager');
+const resourceMonitor = require('managers/resource-monitor');
+const backupManager = require('utilities/backup-manager');
+const healthChecker = require('monitoring/health-checker');
+const updateManager = require('managers/update-manager');
+const selfUpdater = require('docker/self-updater');
+const configureMiddleware = require('utilities/middleware');
+const { validateStartupConfig: _validateStartupConfig, syncHealthCheckerServices } = require('utilities/startup-validator');
+const { CSRF_HEADER_NAME } = require('security/csrf-protection');
+const { resolveServiceUrl } = require('utilities/url-resolver');
+const metrics = require('monitoring/metrics');
+const { validateURL } = require('security/input-validator');
 
 // Optional modules
 let dockerMaintenance, logDigest;
-try { dockerMaintenance = require('../docker-maintenance'); } catch (_) { /* optional module */ }
-try { logDigest = require('../log-digest'); } catch (_) { /* optional module */ }
+try { dockerMaintenance = require('docker/docker-maintenance'); } catch (_) { /* optional module */ }
+try { logDigest = require('security/log-digest'); } catch (_) { /* optional module */ }
 
 // Workflow engine (bundled workflows)
 let bundledWorkflowsModule;
 let workflowEngine = null;
 try { 
-  bundledWorkflowsModule = require('../bundled-workflows'); 
+  bundledWorkflowsModule = require('recipes/bundled-workflows'); 
 } catch (_) { /* optional module */ }
 
 // Templates
-const { APP_TEMPLATES, TEMPLATE_CATEGORIES, DIFFICULTY_LEVELS } = require('../app-templates');
-const { RECIPE_TEMPLATES, RECIPE_CATEGORIES } = require('../recipe-templates');
+const { APP_TEMPLATES, TEMPLATE_CATEGORIES, DIFFICULTY_LEVELS } = require('docker/app-templates');
+const { RECIPE_TEMPLATES, RECIPE_CATEGORIES } = require('recipes/recipe-templates');
 
 // Route modules
 const healthRoutes = require('../routes/health');
@@ -79,21 +79,22 @@ const dockerResourcesRoutes = require('../routes/docker-resources');
 const eventsRoutes = require('../routes/events');
 const workflowsRoutes = require('../routes/workflows');
 const dependenciesRoutes = require('../routes/dependencies');
-const DependencyManager = require('../dependency-manager');
+const DependencyManager = require('managers/dependency-manager');
 const autoRestartRoutes = require('../routes/auto-restart');
 const configDriftRoutes = require('../routes/config-drift');
 const sslMonitorRoutes = require('../routes/ssl-monitor');
-const { AutoRestartManager } = require('../auto-restart-manager');
-const { ConfigDriftDetector } = require('../config-drift-detector');
-const SSLMonitor = require('../ssl-monitor');
-const DNSPropagationChecker = require('../dns-propagation');
+const { AutoRestartManager } = require('managers/auto-restart-manager');
+const { ConfigDriftDetector } = require('managers/config-drift-detector');
+const SSLMonitor = require('monitoring/ssl-monitor');
+const DNSPropagationChecker = require('dns/dns-propagation');
 
 // Constants
-const { APP } = require('../constants');
+const { APP } = require('utilities/constants');
 
 /**
  * Create and configure the Express application
  */
+// eslint-disable-next-line require-await -- kept async for API consistency with other factory functions
 async function createApp() {
   const app = express();
 
@@ -182,6 +183,25 @@ async function createApp() {
     return first === 100 && second >= 64 && second <= 127;
   }
 
+  function isPrivateLan(ip) {
+    if (!ip) return false;
+    if (ip.startsWith('192.168.') || ip.startsWith('10.')) return true;
+    return /^172\.(1[6-9]|2[0-9]|3[0-1])\./.test(ip);
+  }
+
+  function collectNetworkInterfaces(osModule) {
+    const out = [];
+    const interfaces = osModule.networkInterfaces();
+    for (const [name, addrs] of Object.entries(interfaces)) {
+      for (const addr of addrs) {
+        if (addr.internal || addr.family !== 'IPv4') continue;
+        out.push({ name, ip: addr.address });
+      }
+    }
+    return out;
+  }
+
+  // eslint-disable-next-line require-await -- stub for now, will gain await when wired into context
   async function getTailscaleStatus() {
     // Stub for now - will be populated by context
     return null;
@@ -196,15 +216,15 @@ async function createApp() {
     auditLogger,
     authManager,
     log,
-    cryptoUtils: require('../crypto-utils'),
+    cryptoUtils: require('security/crypto-utils'),
     isValidContainerId,
     isTailscaleIP,
     getTailscaleStatus,
-    RATE_LIMITS: require('../constants').RATE_LIMITS,
-    LIMITS: require('../constants').LIMITS,
-    APP: require('../constants').APP,
-    CACHE_CONFIGS: require('../cache-config').CACHE_CONFIGS,
-    createCache: require('../cache-config').createCache,
+    RATE_LIMITS: require('utilities/constants').RATE_LIMITS,
+    LIMITS: require('utilities/constants').LIMITS,
+    APP: require('utilities/constants').APP,
+    CACHE_CONFIGS: require('utilities/cache-config').CACHE_CONFIGS,
+    createCache: require('utilities/cache-config').createCache,
   });
 
   const { strictLimiter } = middlewareResult;
@@ -215,8 +235,9 @@ async function createApp() {
     return services.find(s => s.id === serviceId) || null;
   }
 
+  // eslint-disable-next-line require-await -- may grow awaits as config loading evolves
   async function readConfig() {
-    const { readJsonFile } = require('../fs-helpers');
+    const { readJsonFile } = require('utilities/fs-helpers');
     return readJsonFile(config.CONFIG_FILE, {});
   }
 
@@ -239,7 +260,7 @@ async function createApp() {
 
   async function saveTotpConfig() {
     try {
-      const { writeJsonFile } = require('../fs-helpers');
+      const { writeJsonFile } = require('utilities/fs-helpers');
       await writeJsonFile(config.TOTP_CONFIG_FILE, totpConfig);
     } catch (e) {
       log.error('config', 'Could not save TOTP config', { error: e.message });
@@ -250,6 +271,7 @@ async function createApp() {
     // Stub - will be implemented
   }
 
+  // eslint-disable-next-line require-await -- health checker sync is sync; kept async for caller API stability
   async function resyncHealthChecker() {
     return syncHealthCheckerServices({
       log,
@@ -404,8 +426,7 @@ async function createApp() {
     appName = pkg.name || appName;
   } catch { /* package.json unreadable — keep fallback */ }
   apiRouter.get('/version', (req, res) => {
-    res.json({
-      success: true,
+    ok(res, {
       name: appName,
       version: appVersion,
       node: process.version,
@@ -608,15 +629,15 @@ async function createApp() {
 
   // Inline API routes
   apiRouter.get('/health', (req, res) => {
-    res.json({ status: 'ok', timestamp: new Date().toISOString() });
+    ok(res, { status: 'ok', timestamp: new Date().toISOString() });
   });
   
   apiRouter.get('/csrf-token', (req, res) => {
-    res.json({ success: true, token: req.csrfToken, headerName: CSRF_HEADER_NAME });
+    ok(res, { token: req.csrfToken, headerName: CSRF_HEADER_NAME });
   });
   
   apiRouter.get('/metrics', (req, res) => {
-    res.json({ success: true, metrics: metrics.getSummary() });
+    ok(res, { metrics: metrics.getSummary() });
   });
 
   // Mount at /api/v1 (canonical, single version)
@@ -624,7 +645,7 @@ async function createApp() {
 
   // Root-level health check
   app.get('/health', (req, res) => {
-    res.json({ status: 'ok', timestamp: new Date().toISOString() });
+    ok(res, { status: 'ok', timestamp: new Date().toISOString() });
   });
 
   // Liveness probe — "is the process alive?"
@@ -632,7 +653,7 @@ async function createApp() {
   // Used by k8s/Docker to decide whether to RESTART the container.
   // DO NOT add dependency checks here — those belong in /health/ready.
   app.get('/health/live', (req, res) => {
-    res.json({ status: 'alive', uptime: process.uptime() });
+    ok(res, { status: 'alive', uptime: process.uptime() });
   });
 
   // Readiness probe — "is the app ready to serve traffic?"
@@ -704,13 +725,13 @@ async function createApp() {
       timestamp: new Date().toISOString(),
       checks
     };
-    res.status(allOk ? 200 : 503).json(body);
+    ok(res, body, allOk ? 200 : 503);
   }));
 
   // Lightweight probe endpoint
   app.get('/probe/:id', boundAsyncHandler(async (req, res) => {
     const id = req.params.id;
-    const { exists } = require('../fs-helpers');
+    const { exists } = require('utilities/fs-helpers');
 
     let service = null;
     if (id !== 'internet' && await exists(config.SERVICES_FILE)) {
@@ -814,23 +835,16 @@ async function createApp() {
       };
 
       if (!envLan || !envTailscale) {
-        const interfaces = os.networkInterfaces();
-        for (const [name, addrs] of Object.entries(interfaces)) {
-          for (const addr of addrs) {
-            if (addr.internal || addr.family !== 'IPv4') continue;
-            const ip = addr.address;
-            result.all.push({ name, ip });
-
-            if (!result.tailscale && ip.startsWith('100.')) {
-              result.tailscale = ip;
-            } else if (!result.lan && (ip.startsWith('192.168.') || ip.startsWith('10.') || ip.match(/^172\.(1[6-9]|2[0-9]|3[0-1])\./))) {
-              result.lan = ip;
-            }
-          }
+        result.all = collectNetworkInterfaces(os);
+        if (!result.tailscale) {
+          result.tailscale = result.all.find(i => isTailscaleIP(i.ip))?.ip || null;
+        }
+        if (!result.lan) {
+          result.lan = result.all.find(i => isPrivateLan(i.ip))?.ip || null;
         }
       }
 
-      res.json(result);
+      ok(res, result);
     } catch (error) {
       errorResponse(res, 500, safeErrorMessage(error));
     }
@@ -857,7 +871,7 @@ async function createApp() {
 
   app.get('/api/v1/docs/spec', boundAsyncHandler(async (req, res) => {
     const path = require('path');
-    const { exists } = require('../fs-helpers');
+    const { exists } = require('utilities/fs-helpers');
     const fsp = require('fs').promises;
     
     const specPath = path.join(__dirname, '../openapi.yaml');
@@ -870,7 +884,7 @@ async function createApp() {
   }, 'api-docs-spec'));
 
   // Error handlers (MUST be last)
-  const { notFoundHandler, errorMiddleware } = require('../error-handler');
+  const { notFoundHandler, errorMiddleware } = require('utilities/error-handler');
   app.use('/api', notFoundHandler);
   app.use(errorMiddleware);
 

dashcaddy-api/src/config/index.js

@@ -4,7 +4,7 @@
  */
 const paths = require('./paths');
 const site = require('./site');
-const { APP, LIMITS, TIMEOUTS, RETRIES, CADDY } = require('../../constants');
+const { APP, LIMITS, TIMEOUTS, RETRIES, CADDY } = require('../utilities/constants');
 
 // Load logging level
 const LOG_LEVELS = { debug: 0, info: 1, warn: 2, error: 3 };

dashcaddy-api/src/config/migrations.js

@@ -17,7 +17,7 @@
  */
 const fs = require('fs');
 const path = require('path');
-const platformPaths = require('../../platform-paths');
+const _platformPaths = require('../../platform-paths');
 
 const CURRENT_VERSION = 2;
 

dashcaddy-api/src/config/site.js

@@ -7,8 +7,8 @@
  * updated config back, and the rest of the app only ever sees the current
  * schema.
  */
-const { validateConfig } = require('../../config-schema');
-const { CADDY } = require('../../constants');
+const { validateConfig } = require('../utilities/config-schema');
+const { CADDY } = require('../utilities/constants');
 const { loadAndMigrate, CURRENT_VERSION } = require('./migrations');
 
 const siteConfig = {
@@ -24,6 +24,33 @@ const siteConfig = {
   routingMode: 'subdomain'
 };
 
+function applyConfigFields(raw) {
+  siteConfig.tld = raw.tld || '.home';
+  if (!siteConfig.tld.startsWith('.')) siteConfig.tld = '.' + siteConfig.tld;
+  siteConfig.caName = raw.caName || '';
+  siteConfig.dnsServerIp = (raw.dns && raw.dns.ip) || '';
+  siteConfig.dnsServerPort = (raw.dns && raw.dns.port) || CADDY.DEFAULT_DNS_PORT;
+  siteConfig.dashboardHost = raw.dashboardHost || `status${siteConfig.tld}`;
+  siteConfig.timezone = raw.timezone || 'UTC';
+  siteConfig.dnsServers = raw.dnsServers || {};
+  siteConfig.configurationType = raw.configurationType || 'homelab';
+  siteConfig.domain = raw.domain || '';
+  siteConfig.routingMode = raw.routingMode || 'subdomain';
+  siteConfig.pylon = raw.pylon || null;
+}
+
+function validateAndLogConfig(raw, log) {
+  const { valid, errors: configErrors, warnings: configWarnings } = validateConfig(raw);
+  if (log && log.warn) {
+    if (!valid) {
+      log.warn('config', 'Config validation errors', { errors: configErrors });
+    }
+    for (const w of configWarnings) {
+      log.warn('config', w);
+    }
+  }
+}
+
 function loadSiteConfig(CONFIG_FILE, log) {
   try {
     // Run migrations first — this handles config.json files from older
@@ -31,29 +58,8 @@ function loadSiteConfig(CONFIG_FILE, log) {
     const raw = loadAndMigrate(CONFIG_FILE, log);
 
     if (raw && Object.keys(raw).length > 0) {
-      // Validate config and log any issues
-      const { valid, errors: configErrors, warnings: configWarnings } = validateConfig(raw);
-      if (log && log.warn) {
-        if (!valid) {
-          log.warn('config', 'Config validation errors', { errors: configErrors });
-        }
-        for (const w of configWarnings) {
-          log.warn('config', w);
-        }
-      }
-
-      siteConfig.tld = raw.tld || '.home';
-      if (!siteConfig.tld.startsWith('.')) siteConfig.tld = '.' + siteConfig.tld;
-      siteConfig.caName = raw.caName || '';
-      siteConfig.dnsServerIp = (raw.dns && raw.dns.ip) || '';
-      siteConfig.dnsServerPort = (raw.dns && raw.dns.port) || CADDY.DEFAULT_DNS_PORT;
-      siteConfig.dashboardHost = raw.dashboardHost || `status${siteConfig.tld}`;
-      siteConfig.timezone = raw.timezone || 'UTC';
-      siteConfig.dnsServers = raw.dnsServers || {};
-      siteConfig.configurationType = raw.configurationType || 'homelab';
-      siteConfig.domain = raw.domain || '';
-      siteConfig.routingMode = raw.routingMode || 'subdomain';
-      siteConfig.pylon = raw.pylon || null;
+      validateAndLogConfig(raw, log);
+      applyConfigFields(raw);
     }
   } catch (e) {
     if (log && log.error) {

dashcaddy-api/src/context/caddy.js

@@ -2,7 +2,7 @@
  * Caddy context - Caddyfile manipulation and reload
  */
 const fsp = require('fs').promises;
-const { RETRIES } = require('../../constants');
+const { RETRIES } = require('../utilities/constants');
 
 /**
  * Atomically read-modify-write the Caddyfile and reload Caddy.
@@ -43,6 +43,7 @@ async function modifyCaddyfile(CADDYFILE_PATH, reloadCaddy, modifyFn) {
 /**
  * Read the current Caddyfile content
  */
+// eslint-disable-next-line require-await -- fsp.readFile already returns a promise
 async function readCaddyfile(CADDYFILE_PATH) {
   return fsp.readFile(CADDYFILE_PATH, 'utf8');
 }

dashcaddy-api/src/context/dns.js

@@ -6,8 +6,8 @@
  * 
  * This module now delegates to the provider system internally.
  */
-const { TIMEOUTS, SESSION_TTL, CADDY } = require('../../constants');
-const { createCache, CACHE_CONFIGS } = require('../../cache-config');
+const { TIMEOUTS, SESSION_TTL, CADDY } = require('../utilities/constants');
+const { createCache, CACHE_CONFIGS } = require('../utilities/cache-config');
 const { createProviderDnsContext } = require('./provider-dns');
 
 // DNS token management
@@ -82,6 +82,20 @@ async function refreshDnsToken(username, password, server, fetchT, log) {
 /**
  * Ensure we have a valid DNS token (auto-refresh if needed)
  */
+async function tryCredentialPair(dnsId, role, primaryIp, siteConfig, credentialManager, fetchT, log) {
+  try {
+    const username = await credentialManager.retrieve(`dns.${dnsId}.${role}.username`);
+    const password = await credentialManager.retrieve(`dns.${dnsId}.${role}.password`);
+    if (username && password) {
+      return await refreshDnsToken(username, password, primaryIp, fetchT, log);
+    }
+    return null;
+  } catch (err) {
+    log.error('dns', `Per-server ${role} credential error`, { dnsId, error: err.message });
+    return null;
+  }
+}
+
 async function ensureValidDnsToken(siteConfig, credentialManager, fetchT, log) {
   // Check if token is valid and not expired
   if (dnsToken && dnsTokenExpiry && new Date() < new Date(dnsTokenExpiry)) {
@@ -93,15 +107,8 @@ async function ensureValidDnsToken(siteConfig, credentialManager, fetchT, log) {
     const dnsId = dnsIpToDnsId(primaryIp, siteConfig);
     if (dnsId) {
       for (const role of ['admin', 'readonly']) {
-        try {
-          const username = await credentialManager.retrieve(`dns.${dnsId}.${role}.username`);
-          const password = await credentialManager.retrieve(`dns.${dnsId}.${role}.password`);
-          if (username && password) {
-            return await refreshDnsToken(username, password, primaryIp, fetchT, log);
-          }
-        } catch (err) {
-          log.error('dns', `Per-server ${role} credential error`, { dnsId, error: err.message });
-        }
+        const result = await tryCredentialPair(dnsId, role, primaryIp, siteConfig, credentialManager, fetchT, log);
+        if (result) return result;
       }
     }
   }

dashcaddy-api/src/context/docker.js

@@ -2,7 +2,7 @@
  * Docker context - Docker client and operations
  */
 const Docker = require('dockerode');
-const { DOCKER } = require('../../constants');
+const { DOCKER } = require('../utilities/constants');
 
 const docker = new Docker();
 

dashcaddy-api/src/context/index.js

@@ -6,7 +6,7 @@ const { createDockerContext } = require('./docker');
 const { createCaddyContext } = require('./caddy');
 const { createDnsContext } = require('./dns');
 const { createSessionContext } = require('./session');
-const NotificationManager = require('../../notification-manager');
+const NotificationManager = require('../managers/notification-manager');
 
 /**
  * Assemble the full application context

dashcaddy-api/src/context/provider-dns.js

@@ -6,8 +6,8 @@
  * Falls back to legacy Technitium context for backward compatibility
  * when no provider is explicitly configured.
  */
-const { createCache, CACHE_CONFIGS } = require('../../cache-config');
-const { TIMEOUTS, SESSION_TTL, CADDY } = require('../../constants');
+const { createCache, CACHE_CONFIGS } = require('../utilities/cache-config');
+const { TIMEOUTS, SESSION_TTL, CADDY } = require('../utilities/constants');
 const registry = require('../../dns-providers/registry');
 
 // Per-server token cache (legacy Technitium)
@@ -34,35 +34,30 @@ function createProviderDnsContext(siteConfig, buildDomain, credentialManager, fe
   /** Get provider-specific config from site config */
   function getProviderConfig(providerId) {
     const dnsConfig = siteConfig.dns || {};
-
-    switch (providerId) {
-      case 'technitium':
-        return {
-          serverIp: siteConfig.dnsServerIp || dnsConfig.ip || '',
-          serverPort: siteConfig.dnsServerPort || dnsConfig.port || '5380',
-          dnsServers: siteConfig.dnsServers || {},
-          dnsId: Object.keys(siteConfig.dnsServers || {})[0] || 'dns1'
-        };
-      case 'cloudflare':
-        return {
-          apiToken: dnsConfig.apiToken || '',
-          zoneId: dnsConfig.zoneId || '',
-          domain: siteConfig.domain || ''
-        };
-      case 'rfc2136':
-        return {
-          server: dnsConfig.server || siteConfig.dnsServerIp || '',
-          port: dnsConfig.port || 53,
-          zone: siteConfig.tld?.replace(/^\./, '') || '',
-          tsigAlgorithm: dnsConfig.tsigAlgorithm || 'hmac-sha256',
-          tsigKeyName: dnsConfig.tsigKeyName || '',
-          tsigSecret: dnsConfig.tsigSecret || ''
-        };
-      case 'manual':
-        return {};
-      default:
-        return dnsConfig;
-    }
+    const builders = {
+      technitium: () => ({
+        serverIp: siteConfig.dnsServerIp || dnsConfig.ip || '',
+        serverPort: siteConfig.dnsServerPort || dnsConfig.port || '5380',
+        dnsServers: siteConfig.dnsServers || {},
+        dnsId: Object.keys(siteConfig.dnsServers || {})[0] || 'dns1'
+      }),
+      cloudflare: () => ({
+        apiToken: dnsConfig.apiToken || '',
+        zoneId: dnsConfig.zoneId || '',
+        domain: siteConfig.domain || ''
+      }),
+      rfc2136: () => ({
+        server: dnsConfig.server || siteConfig.dnsServerIp || '',
+        port: dnsConfig.port || 53,
+        zone: siteConfig.tld?.replace(/^\./, '') || '',
+        tsigAlgorithm: dnsConfig.tsigAlgorithm || 'hmac-sha256',
+        tsigKeyName: dnsConfig.tsigKeyName || '',
+        tsigSecret: dnsConfig.tsigSecret || ''
+      }),
+      manual: () => ({})
+    };
+    const builder = builders[providerId];
+    return builder ? builder() : dnsConfig;
   }
 
   /** Get or create the active provider adapter */
@@ -120,6 +115,25 @@ function createProviderDnsContext(siteConfig, buildDomain, credentialManager, fe
     return null;
   }
 
+  async function tryServerRoleCredentials(dnsId, role, primaryIp) {
+    try {
+      const username = await credentialManager.retrieve(`dns.${dnsId}.${role}.username`);
+      const password = await credentialManager.retrieve(`dns.${dnsId}.${role}.password`);
+      if (username && password) return await refreshDnsToken(username, password, primaryIp);
+    } catch (err) { /* try next */ }
+    return null;
+  }
+
+  async function tryGlobalCredentials(primaryIp) {
+    try {
+      const username = await credentialManager.retrieve('dns.username');
+      const password = await credentialManager.retrieve('dns.password');
+      const server = await credentialManager.retrieve('dns.server');
+      if (username && password) return await refreshDnsToken(username, password, server || primaryIp);
+    } catch (err) { /* no global creds */ }
+    return null;
+  }
+
   async function ensureValidDnsToken() {
     if (dnsToken && dnsTokenExpiry && new Date() < new Date(dnsTokenExpiry)) {
       return { success: true, token: dnsToken };
@@ -129,20 +143,13 @@ function createProviderDnsContext(siteConfig, buildDomain, credentialManager, fe
       const dnsId = dnsIpToDnsId(primaryIp);
       if (dnsId) {
         for (const role of ['admin', 'readonly']) {
-          try {
-            const username = await credentialManager.retrieve(`dns.${dnsId}.${role}.username`);
-            const password = await credentialManager.retrieve(`dns.${dnsId}.${role}.password`);
-            if (username && password) return await refreshDnsToken(username, password, primaryIp);
-          } catch (err) { /* try next */ }
+          const result = await tryServerRoleCredentials(dnsId, role, primaryIp);
+          if (result) return result;
         }
       }
     }
-    try {
-      const username = await credentialManager.retrieve('dns.username');
-      const password = await credentialManager.retrieve('dns.password');
-      const server = await credentialManager.retrieve('dns.server');
-      if (username && password) return await refreshDnsToken(username, password, server || primaryIp);
-    } catch (err) { /* no global creds */ }
+    const globalResult = await tryGlobalCredentials(primaryIp);
+    if (globalResult) return globalResult;
     return { success: false, error: 'No DNS credentials configured' };
   }