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.

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 = {
@@ -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/routes/apps/compose.js

@@ -1,9 +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');
+const { ok } = require('../src/utils/responses');
 
 /**
  * Docker Compose import routes

dashcaddy-api/routes/apps/deploy.js

@@ -2,13 +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 { ok } = require('../../src/utils/responses');
+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

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,7 +1,7 @@
 const express = require('express');
-const { exists } = require('../../fs-helpers');
-const { logError } = require('../../src/utils/logging');
-const { ok } = require('../../src/utils/responses');
+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,

dashcaddy-api/routes/apps/restore.js

@@ -1,8 +1,8 @@
 const express = require('express');
 const path = require('path');
 const fs = require('fs');
-const { DOCKER } = require('../../constants');
-const { ok, validationError, notFound, errorResponse } = require('../../src/utils/responses');
+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');
 

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,8 +19,8 @@ const { exists } = require('../../fs-helpers');
  * @param {string} deps.SERVICES_FILE - Services file path
  * @returns {express.Router}
  */
-const { REGEX } = require('../../constants');
-const { ok } = require('../../src/utils/responses');
+const { REGEX } = require('../../../src/utilities/constants');
+const { ok } = require('../src/utils/responses');
 
 module.exports = function({
   servicesStateManager, asyncHandler, helpers,
@@ -55,7 +55,7 @@ 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');
     }
     ok(res, { template });
@@ -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');

dashcaddy-api/routes/arr/config.js

@@ -1,9 +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 { ok, successMessage } = require('../../src/utils/responses');
+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

dashcaddy-api/routes/arr/credentials.js

@@ -1,7 +1,7 @@
 const express = require('express');
-const { validateURL, validateToken } = require('../../input-validator');
-const { ValidationError } = require('../../errors');
-const { ok, successMessage } = require('../../src/utils/responses');
+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

dashcaddy-api/routes/arr/detect.js

@@ -1,6 +1,6 @@
 const express = require('express');
-const { APP_PORTS, ARR_SERVICES } = require('../../constants');
-const { ok } = require('../../src/utils/responses');
+const { APP_PORTS, ARR_SERVICES } = require('../../../src/utilities/constants');
+const { ok } = require('../src/utils/responses');
 
 /**
  * Arr service detection routes factory

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,6 +1,6 @@
 const express = require('express');
-const { APP_PORTS } = require('../../constants');
-const { ok } = require('../../src/utils/responses');
+const { APP_PORTS } = require('../../../src/utilities/constants');
+const { ok } = require('../src/utils/responses');
 
 /**
  * Plex routes factory

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,6 +1,6 @@
 const express = require('express');
-const { ValidationError, ForbiddenError, NotFoundError } = require('../../errors');
-const { ok, successMessage } = require('../../src/utils/responses');
+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

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,5 @@
 const express = require('express');
-const { ValidationError, AuthenticationError } = require('../../errors');
+const { ValidationError, AuthenticationError } = require('../../src/utilities/errors');
 const { ok, successMessage } = require('../../src/utils/responses');
 
 /**

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,9 @@ 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');
 
 /**
@@ -99,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');
     }
 

dashcaddy-api/routes/ca.js

@@ -3,8 +3,8 @@ 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');
 
@@ -19,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');
     }
 
@@ -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})`);
     }
 

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,11 +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');
+const { ok, successMessage } = require('../src/utils/responses');
 /**
  * Config assets routes factory
  * @param {Object} deps - Explicit dependencies

dashcaddy-api/routes/config/backup.js

@@ -1,11 +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');
+const { ok } = require('../src/utils/responses');
 
 /**
  * Config backup routes factory
@@ -380,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();
         }

dashcaddy-api/routes/config/settings.js

@@ -1,8 +1,8 @@
 const fsp = require('fs').promises;
-const { validateConfig } = require('../../config-schema');
-const { exists } = require('../../fs-helpers');
-const { ValidationError } = require('../../errors');
-const { ok, successMessage } = require('../../src/utils/responses');
+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

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

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/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 { resolveServiceUrl } = require('../src/utilities/url-resolver');
 const { success, error: errorResponse, errorResponse: sendError, ok, notFound } = require('../src/utils/responses');
-const { ValidationError } = require('../errors');
+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');
     }
 
@@ -331,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,9 @@ 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');
 
 /**
@@ -48,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;
@@ -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;
@@ -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');
     }
 

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,8 @@
 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');
 
 /**

dashcaddy-api/routes/recipes/deploy.js

@@ -1,8 +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 { ok } = require('../../src/utils/responses');
+const { DOCKER } = require('../../../src/utilities/constants');
+const { ok } = require('../src/utils/responses');
 
 /**
  * Recipes deployment routes factory
@@ -28,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');

dashcaddy-api/routes/recipes/index.js

@@ -1,8 +1,8 @@
 const express = require('express');
 const deployRoutes = require('./deploy');
 const manageRoutes = require('./manage');
-const { NotFoundError } = require('../../errors');
-const { ok } = require('../../src/utils/responses');
+const { NotFoundError } = require('../../../src/utilities/errors');
+const { ok } = require('../src/utils/responses');
 
 /**
  * Recipes routes aggregator
@@ -32,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,
@@ -61,7 +61,7 @@ module.exports = function(ctx) {
 
   // 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}`);
 

dashcaddy-api/routes/recipes/manage.js

@@ -1,7 +1,7 @@
 const express = require('express');
-const { DOCKER } = require('../../constants');
-const { NotFoundError } = require('../../errors');
-const { ok } = require('../../src/utils/responses');
+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();
@@ -269,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, '-')
@@ -293,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

dashcaddy-api/routes/sites.js

@@ -1,8 +1,8 @@
 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 { 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');
 
 /**

dashcaddy-api/routes/tailscale.js

@@ -1,8 +1,8 @@
 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');
 
 /**
@@ -156,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`);
     }
 

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,6 @@
 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');
 
 /**

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,
@@ -709,7 +731,7 @@ async function createApp() {
   // 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)) {
@@ -813,19 +835,12 @@ 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;
         }
       }
 
@@ -856,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');
@@ -869,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' };
   }
 

dashcaddy-api/src/docker/docker-maintenance.js

@@ -9,7 +9,7 @@
 
 const Docker = require('dockerode');
 const EventEmitter = require('events');
-const { DOCKER } = require('./constants');
+const { DOCKER } = require('../utilities/constants');
 
 const docker = new Docker();
 

dashcaddy-api/src/managers/auth-manager.js

@@ -7,7 +7,7 @@
 const jwt = require('jsonwebtoken');
 const crypto = require('crypto');
 const credentialManager = require('./credential-manager');
-const cryptoUtils = require('./crypto-utils');
+const cryptoUtils = require('../security/crypto-utils');
 
 // JWT signing secret - derived from encryption key for consistency
 const JWT_SECRET = cryptoUtils.loadOrCreateKey();

dashcaddy-api/src/managers/auto-restart-manager.js

@@ -10,7 +10,7 @@
 
 const EventEmitter = require('events');
 const path = require('path');
-const { readJsonFile, writeJsonFile } = require('./fs-helpers');
+const { readJsonFile, writeJsonFile } = require('../utilities/fs-helpers');
 
 /**
  * Default policy values applied when a new policy is created.