# Phase 24: AWS Route 53 DNS Sync - Pattern Map

**Mapped:** 2026-08-05
**Files analyzed:** 12 new, 3 modified
**Analogs found:** 15 / 15

## File Classification

| New/Modified File | Role | Data Flow | Closest Analog | Match Quality |
|--------------------|------|-----------|-----------------|----------------|
| `lib/services/route53-factory.ts` | service (factory) | request-response | `lib/services/veeam-factory.ts` / `lib/services/datto-rmm-factory.ts` | exact |
| `lib/services/route53-sync-service.ts` | service (sync) | CRUD (batch upsert) | `lib/services/veeam-sync-service.ts` | exact |
| `lib/services/route53-client-helpers.ts` (optional) | utility | transform | `lib/services/veeam-sync-service.ts` (FK-safety-set helpers, inline) | role-match |
| `lib/types/route53.ts` | model (types) | — | `lib/types/veeam.ts` (barrel domain types) | exact |
| `migrations/102_route53_tables.sql` | migration | — | `migrations/091_pax8_tables.sql` (dedicated integration schema) + `migrations/075_itglue_audit.sql` (audit/write ledger shape) | exact |
| `app/api/route53/sync/route.ts` | route | request-response (fire-and-forget trigger) | `app/api/pax8/sync/route.ts` | exact |
| `app/api/route53/zones/route.ts` | route | CRUD (read) | `app/api/pax8/companies/route.ts` | role-match |
| `app/api/route53/zones/[zoneId]/records/route.ts` | route | CRUD (list + create) | `app/api/analyzer/itglue/applications/route.ts` (list) + `.../apply/route.ts` (write) | role-match |
| `app/api/route53/zones/[zoneId]/records/[recordId]/route.ts` | route | CRUD (update/delete) | `app/api/analyzer/itglue/applications/[id]/apply/route.ts` | exact |
| `app/api/route53/zones/[zoneId]/records/[recordId]/history/route.ts` | route | CRUD (read, append-only ledger) | `app/api/analyzer/itglue/applications/[id]/audit/route.ts` | role-match |
| `app/admin/sync/route53/page.tsx` | component (page) | request-response | `app/admin/sync/veeam/page.tsx` | exact |
| `app/admin/sync/page.tsx` (modified) | component (page, tile list) | request-response | itself — extend `INTEGRATIONS` array in place | exact |
| `lib/services/sync-scheduler.ts` (modified) | service (scheduler) | event-driven (cron) | itself — extend `sync_type` union + `defaultSchedules` + dispatch branch | exact |
| `lib/services/integration-health.ts` (modified) | service (health check) | request-response | itself — add `checkRoute53()` alongside `checkDattoRmm()`/`checkItglue()` | exact |
| `lib/services/route53-write-persistence.ts` (helper, optional split) | service | CRUD | `lib/services/analyzer/asset-audit/persistence.ts` | exact |

## Pattern Assignments

### `lib/services/route53-factory.ts` (service, request-response)

**Analog:** `lib/services/veeam-factory.ts` (singleton client + config check), cross-checked against `lib/services/datto-rmm-factory.ts` (multi-var config check)

**Full file for reference** (`lib/services/veeam-factory.ts`, lines 1-41):
```typescript
import { VeeamClient, VeeamClientConfig } from './veeam-client';

let veeamClientInstance: VeeamClient | null = null;

export function isVeeamConfigured(): boolean {
  return !!(process.env.VEEAM_VSPC_URL && process.env.VEEAM_VSPC_API_KEY);
}

export function getVeeamClient(): VeeamClient {
  if (!veeamClientInstance) {
    const config: VeeamClientConfig = {
      baseUrl: process.env.VEEAM_VSPC_URL || '',
      apiKey: process.env.VEEAM_VSPC_API_KEY || '',
    };
    if (!config.baseUrl || !config.apiKey) {
      throw new Error(
        'Veeam VSPC API credentials missing. Please set VEEAM_VSPC_URL and VEEAM_VSPC_API_KEY environment variables.'
      );
    }
    veeamClientInstance = new VeeamClient(config);
    console.log('Veeam VSPC client initialized');
  }
  return veeamClientInstance;
}

export function resetVeeamClient(): void {
  veeamClientInstance = null;
}
```

**Adaptation for Route 53** (per RESEARCH.md's Pattern 1 — literal `AWS_*` env vars, no custom `ROUTE53_*` prefix, per Pitfall 1):
```typescript
import { Route53Client } from '@aws-sdk/client-route-53';

let route53ClientInstance: Route53Client | null = null;

export function isRoute53Configured(): boolean {
  return !!(process.env.AWS_ACCESS_KEY_ID && process.env.AWS_SECRET_ACCESS_KEY);
}

export function getRoute53Client(): Route53Client {
  if (!route53ClientInstance) {
    if (!isRoute53Configured()) {
      throw new Error(
        'AWS credentials missing. Please set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (and AWS_REGION) environment variables.'
      );
    }
    // No explicit `credentials` option — @aws-sdk/credential-provider-node's
    // default chain reads AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_SESSION_TOKEN
    // from process.env automatically. Region defaults to us-east-1 (Route 53 is
    // global but the SDK still requires a signing region).
    route53ClientInstance = new Route53Client({
      region: process.env.AWS_REGION || 'us-east-1',
    });
  }
  return route53ClientInstance;
}

export function resetRoute53Client(): void {
  route53ClientInstance = null;
}
```
Do NOT construct an explicit `credentials:` object — that defeats the SDK default chain BWS relies on (RESEARCH.md Pitfall 1).

---

### `lib/services/route53-sync-service.ts` (service, CRUD/batch upsert)

**Analog:** `lib/services/veeam-sync-service.ts`

**Imports pattern** (lines 1-19):
```typescript
import postgresClient from './postgres-client';
import { VeeamClient } from './veeam-client';
import { getVeeamClient } from './veeam-factory';
import { VspcOrganization, /* ... */ } from '@/lib/types/veeam';
```
For Route 53, mirror with:
```typescript
import { ListHostedZonesCommand, ListResourceRecordSetsCommand } from '@aws-sdk/client-route-53';
import { getRoute53Client } from './route53-factory';
import postgresClient from './postgres-client';
```

**Class shape + sync-history bookkeeping pattern** (lines 40-91, `VeeamSyncService` constructor + `executeSync()` header):
```typescript
export class VeeamSyncService {
  private client: VeeamClient;
  private isSyncing = false;

  constructor(client?: VeeamClient) {
    this.client = client || getVeeamClient();
  }

  isSyncInProgress(): boolean {
    return this.isSyncing;
  }

  async fullSync(triggeredBy: string = 'system'): Promise<VeeamSyncResult> {
    return this.executeSync('full', triggeredBy);
  }

  async incrementalSync(triggeredBy: string = 'system'): Promise<VeeamSyncResult> {
    return this.executeSync('incremental', triggeredBy);
  }

  private async executeSync(syncType: 'full' | 'incremental', triggeredBy: string): Promise<VeeamSyncResult> {
    if (this.isSyncing) {
      throw new Error('A Veeam sync operation is already in progress');
    }
    this.isSyncing = true;
    const syncId = `veeam-${Date.now()}`;
    const startTime = new Date();
    // ... INSERT INTO sync_history (entity_type, sync_type, status, started_at, ...)
    //     VALUES ($1, $2, $3, $4, 0, 0, 0, $5) RETURNING id
  }
}
```
Route53SyncService should follow this exact shape: `isSyncInProgress()`, `fullSync()`/`incrementalSync()` both delegating to a private `executeSync()`, and the same `sync_history` bookkeeping insert/update pair (lines 78-89 and 139-149 of the analog). **Difference from Veeam:** D-06 requires writing `route53_record_history` (`source='sync_detected_drift'`) whenever a synced record differs from the current mirror row — Veeam's sync has no equivalent diff-and-history step, so this part must be newly composed (diff before `INSERT ... ON CONFLICT DO UPDATE`, not after).

**Step-loop + per-step error isolation pattern** (lines 94-120):
```typescript
const steps: Array<{ name: string; fn: () => Promise<number> }> = [
  { name: 'organizations', fn: () => this.syncOrganizations() },
  { name: 'backup_servers', fn: () => this.syncBackupServers() },
  // ...
];
for (const step of steps) {
  const stepStart = Date.now();
  try {
    const count = await step.fn();
    entityResults.push({ entity: step.name, success: true, recordsUpserted: count, duration: Date.now() - stepStart });
  } catch (error) {
    const msg = error instanceof Error ? error.message : String(error);
    errors.push(`${step.name}: ${msg}`);
    entityResults.push({ entity: step.name, success: false, recordsUpserted: 0, duration: Date.now() - stepStart, error: msg });
  }
}
```
Route 53 steps: `{ name: 'zones', fn: () => this.syncZones() }`, `{ name: 'records', fn: () => this.syncRecords() }` (zones must sync first — records reference zone id).

**Upsert-with-FK-safety-set pattern** (lines 219-247, `syncBackupServers()`):
```typescript
const knownOrgs = await postgresClient.query('SELECT instance_uid FROM veeam_organizations');
const orgUids = new Set(knownOrgs.rows.map((r: any) => r.instance_uid));

let count = 0;
for (const s of servers) {
  const orgUid = orgUids.has(s.organizationUid) ? s.organizationUid : null;
  await postgresClient.query(
    `INSERT INTO veeam_backup_servers (instance_uid, name, organization_uid, ..., synced_at)
     VALUES ($1,$2,$3,...,NOW())
     ON CONFLICT (instance_uid) DO UPDATE SET
       name=EXCLUDED.name, organization_uid=EXCLUDED.organization_uid, ...,
       synced_at=NOW(), updated_at=NOW()`,
    [s.instanceUid, s.name, orgUid, /* ... */]
  );
  count++;
}
```
For `route53_records`, the FK-safety set is zone ids from `route53_zones` (loaded once, checked with `.has()` before insert) — same shape, swap `instance_uid` for `id` (Route 53's own ids, not synthetic UUIDs — zone id after stripping `/hostedzone/` prefix per RESEARCH.md Pattern 2).

**Pagination pattern** (RESEARCH.md Pattern 2, `ListHostedZonesCommand`):
```typescript
async function syncZones(client = getRoute53Client()) {
  let marker: string | undefined;
  let count = 0;
  do {
    const page = await client.send(new ListHostedZonesCommand({ Marker: marker }));
    for (const z of page.HostedZones ?? []) {
      const zoneId = (z.Id ?? '').replace('/hostedzone/', '');
      await postgresClient.query(
        `INSERT INTO route53_zones (id, name, comment, private_zone, record_count, raw_payload, synced_at)
         VALUES ($1,$2,$3,$4,$5,$6,NOW())
         ON CONFLICT (id) DO UPDATE SET
           name=EXCLUDED.name, comment=EXCLUDED.comment, private_zone=EXCLUDED.private_zone,
           record_count=EXCLUDED.record_count, raw_payload=EXCLUDED.raw_payload,
           synced_at=NOW(), updated_at=NOW()`,
        [zoneId, z.Name, z.Config?.Comment ?? null, !!z.Config?.PrivateZone,
         z.ResourceRecordSetCount ?? 0, JSON.stringify(z)]
      );
      count++;
    }
    marker = page.IsTruncated ? page.NextMarker : undefined;
  } while (marker);
  return count;
}
```

**Error handling pattern** (lines 152-173, catastrophic-failure fallback):
```typescript
} catch (error) {
  const completedAt = new Date();
  const msg = error instanceof Error ? error.message : String(error);
  console.error('[VEEAM-SYNC] Sync failed catastrophically:', msg);
  if (historyId) {
    try {
      await postgresClient.query(
        `UPDATE sync_history SET status = 'failed', completed_at = $1, error_message = $2 WHERE id = $3`,
        [completedAt, msg, historyId]
      );
    } catch (e) { /* ignore */ }
  }
  return { syncId, syncType, status: 'failed', startedAt: startTime, completedAt, duration: completedAt.getTime() - startTime.getTime(), entities: entityResults, errors: [msg] };
} finally {
  this.isSyncing = false;
}
```

---

### `migrations/102_route53_tables.sql` (migration)

**Analog 1 — dedicated multi-table integration schema:** `migrations/091_pax8_tables.sql`

**Header comment + soft-ref convention pattern** (lines 1-19, 69-73):
```sql
-- PAX8 integration — Postgres schema.
--
-- Lays down the full PAX8 schema Phases 11-14 will populate and consume.
-- ...
CREATE TABLE IF NOT EXISTS pax8_subscriptions (
    id                  UUID PRIMARY KEY,
    pax8_company_id     UUID,  -- soft ref -> pax8_companies(id)
    product_id          UUID,  -- soft ref -> pax8_products(id)
    ...
    raw_payload JSONB,
    synced_at           TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    is_deleted          BOOLEAN NOT NULL DEFAULT false,
    deleted_at          TIMESTAMPTZ
);
CREATE INDEX IF NOT EXISTS idx_pax8_subscriptions_is_deleted ON pax8_subscriptions(is_deleted);
CREATE INDEX IF NOT EXISTS idx_pax8_subscriptions_company    ON pax8_subscriptions(pax8_company_id);
```
`route53_zones` / `route53_records` should follow this exact shape (`raw_payload JSONB`, `synced_at`/`is_deleted`/`deleted_at` audit columns, per-table `idx_*_is_deleted` index) — Route 53's own ids are the PK (zone id string, recordset composite key), not synthetic UUIDs.

**Analog 2 — audit/write ledger with pending→committed/failed lifecycle:** `migrations/075_itglue_audit.sql`

**`itglue_writes` table** (lines 60-88) is the direct precedent for `route53_audit_log`:
```sql
CREATE TABLE IF NOT EXISTS itglue_writes (
  id                    UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  audit_id              UUID REFERENCES itglue_asset_audits(id) ON DELETE SET NULL,
  asset_type            TEXT NOT NULL CHECK (asset_type IN ('flexible_asset')),
  asset_id              BIGINT NOT NULL,
  field_name            TEXT NOT NULL,
  before_value          JSONB,
  after_value           JSONB NOT NULL,
  performed_by_user_id  TEXT REFERENCES "user"(id) ON DELETE SET NULL,
  performed_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  status                TEXT NOT NULL
                          CHECK (status IN ('pending','committed','failed','reverted')),
  itglue_response       JSONB,
  error_message         TEXT,
  source_evidence       JSONB
);
CREATE INDEX IF NOT EXISTS ix_itglue_writes_asset
  ON itglue_writes (asset_type, asset_id, performed_at DESC);
```
Adapt for `route53_audit_log`: swap `asset_type`/`asset_id` for `zone_id`/`record_name`/`record_type`, `itglue_response` for `aws_response` (or `change_id`), and D-07 requires `status IN ('pending','committed','failed')` plus `error_message` captured on failure — matches this shape exactly.

**`route53_record_history`** (new — D-06's `source` tag has no existing table precedent; compose from the `itglue_writes` before/after shape plus an explicit `source TEXT NOT NULL CHECK (source IN ('pulse_crud','sync_detected_drift'))` column):
```sql
CREATE TABLE IF NOT EXISTS route53_record_history (
  id             UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  zone_id        TEXT NOT NULL REFERENCES route53_zones(id) ON DELETE CASCADE,
  record_name    TEXT NOT NULL,
  record_type    TEXT NOT NULL,
  before_value   JSONB,
  after_value    JSONB,
  source         TEXT NOT NULL CHECK (source IN ('pulse_crud','sync_detected_drift')),
  changed_by_user_id TEXT REFERENCES "user"(id) ON DELETE SET NULL,
  changed_at     TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
```

**`integration_settings` seed row** (per D-10) — extend the existing seed list rather than a new migration touching 081:
```sql
-- migrations/102_route53_tables.sql (append)
INSERT INTO integration_settings (key, disabled) VALUES ('route53', false)
ON CONFLICT (key) DO NOTHING;
```
This mirrors `migrations/081_integration_settings.sql` lines 29-42's seed pattern exactly (`ON CONFLICT (key) DO NOTHING`).

---

### `app/api/route53/sync/route.ts` (route, fire-and-forget trigger)

**Analog:** `app/api/pax8/sync/route.ts` (full file, 65 lines)

**Disabled-check pattern is D-10 INVERSE — do not copy the disable-blocks-sync check.** PAX8 is the *only* integration where `disabled` blocks sync (per CLAUDE.md); Route 53 must NOT gate on `integration_settings.disabled` for POST — D-10 says the toggle is display-only for Route 53. Copy everything else:
```typescript
import { NextRequest, NextResponse } from 'next/server';
import { getPax8SyncService } from '@/lib/services/pax8-sync-service';
import postgresClient from '@/lib/services/postgres-client';

export async function POST(req: NextRequest) {
  const body = await req.json().catch(() => ({}));
  const triggeredBy = body.triggeredBy || 'manual';

  const svc = getPax8SyncService();
  if (svc.isSyncInProgress()) {
    return NextResponse.json({ error: 'Sync already in progress' }, { status: 409 });
  }

  // Fire and forget — return immediately, sync runs in background
  svc.fullSync(triggeredBy).catch(err =>
    console.error('[Pax8Sync] Background sync error:', err.message)
  );

  return NextResponse.json({ ok: true, message: 'PAX8 sync started' });
}

export async function GET() {
  try {
    const svc = getPax8SyncService();
    const inProgress = svc.isSyncInProgress();
    const counts = await postgresClient.query(`
      SELECT (SELECT COUNT(*) FROM pax8_companies WHERE is_deleted = false) AS companies, ...
    `);
    const history = await postgresClient.query(
      `SELECT id, sync_type, status, started_at, completed_at, records_added, records_updated, records_deleted, error_message, triggered_by
       FROM sync_history WHERE entity_type = 'pax8' ORDER BY started_at DESC LIMIT 10`
    );
    return NextResponse.json({ inProgress, counts: counts.rows[0], history: history.rows });
  } catch (err) {
    return NextResponse.json({ error: err instanceof Error ? err.message : 'Failed to get PAX8 sync status' }, { status: 500 });
  }
}
```
Add `requireAuth()` at the top of both handlers (PAX8's route has no auth gate — an existing gap, don't replicate it; Route 53's sync route should at minimum require an authenticated session since it's reachable by any logged-in user via the admin UI's page context, matching V4 access control note in RESEARCH.md).

---

### `app/api/route53/zones/[zoneId]/records/[recordId]/route.ts` (route, CRUD write-back — PATCH/DELETE)

**Analog:** `app/api/analyzer/itglue/applications/[id]/apply/route.ts` (full file, 202 lines) — this is the single most important pattern in this phase per RESEARCH.md.

**Auth + pending-row-before-external-call pattern** (lines 53-121):
```typescript
export async function POST(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> }
) {
  const { session, error } = await requirePermission('itglue', 'write');
  if (error) return error;

  const { id: assetId } = await params;
  const body = await request.json().catch(() => ({}));
  const parsed = ApplyAssetSuggestionRequest.safeParse(body);
  if (!parsed.success) {
    return NextResponse.json({ error: 'Invalid request body', details: parsed.error.issues }, { status: 400 });
  }

  // Read current state (before_value)
  const asset = await loadAssetRow(assetId);
  if (!asset) return NextResponse.json({ error: 'Asset not found' }, { status: 404 });

  // Insert pending row first so we never write to the external system without
  // an audit row in flight.
  const writeRow = await createPendingWrite({
    audit_id: auditId, asset_type: 'flexible_asset', asset_id: assetId,
    field_name: fieldName, before_value: beforeValue, after_value: suggestedValue,
    performed_by_user_id: userId, source_evidence: sourceEvidence ?? null,
  });

  try {
    const client = getITGlueClient();
    const updated = await client.updateFlexibleAsset(assetId, merged);
    await markWriteCommitted(writeRow.id, updated);
    // best-effort mirror refresh + generic audit_log row
    return NextResponse.json({ writeId: writeRow.id, status: 'committed', asset: updated });
  } catch (err) {
    const message = err instanceof Error ? err.message : String(err);
    await markWriteFailed(writeRow.id, message);
    return NextResponse.json(
      { writeId: writeRow.id, status: 'failed', error: 'IT Glue write failed', message },
      { status: 502 }
    );
  }
}
```
For Route 53's PATCH (record update): use `requireAdmin()` (D-04, not `requirePermission`) — read current recordset from the mirror as `before_value`, `INSERT route53_audit_log (status='pending', before_value, after_value=requested)`, call `ChangeResourceRecordSetsCommand` with `Action: 'UPSERT'`, then on success `markCommitted` + `INSERT route53_record_history (source='pulse_crud')` + refresh mirror row; on failure `markFailed` with `error.message` (D-07) and do NOT write `record_history` (nothing changed on AWS's side — RESEARCH.md Pattern 3).

**Pre-write guardrail pattern to reuse for D-01's write-type allowlist** (lines 86-94, credential-field blocklist — same shape, different check):
```typescript
const lowerField = fieldName.toLowerCase();
if (/(password|secret|key|token|credential)/.test(lowerField)) {
  return NextResponse.json({ error: 'Refusing to write to credential-shaped field' }, { status: 400 });
}
```
Route 53 equivalent: reject `Type: 'NS'` or `Type: 'SOA'` with 400 before constructing `ChangeResourceRecordSetsCommand` — same "belt over the prompt/UI's braces" defensive-check pattern, enforced server-side even though the UI shouldn't offer these types.

**Failure-response pattern** (lines 188-200):
```typescript
} catch (err) {
  const message = err instanceof Error ? err.message : String(err);
  await markWriteFailed(writeRow.id, message);
  return NextResponse.json(
    { writeId: writeRow.id, status: 'failed', error: 'IT Glue write failed', message },
    { status: 502 }
  );
}
```
Use `502` for AWS-side failures (external system rejected/errored), matching this exact convention (not the CLAUDE.md-listed 500/503 — 502 is itglue's precedent for "upstream integration failed").

---

### `lib/services/route53-write-persistence.ts` (helper — pending/committed/failed lifecycle)

**Analog:** `lib/services/analyzer/asset-audit/persistence.ts`

**Pending-write insert pattern** (lines 321-358):
```typescript
export async function createPendingWrite(input: {
  audit_id: string | null;
  asset_type: 'flexible_asset' | 'configuration';
  asset_id: number | string;
  field_name: string;
  before_value: unknown;
  after_value: unknown;
  performed_by_user_id: string | null;
  source_evidence: unknown;
}): Promise<{ id: string }> {
  const res = await postgresClient.query<{ id: string }>(
    `INSERT INTO itglue_writes
       (audit_id, asset_type, asset_id, field_name, before_value, after_value,
        performed_by_user_id, status, source_evidence)
     VALUES ($1, $2, $3, $4, $5::jsonb, $6::jsonb, $7, 'pending', $8::jsonb)
     RETURNING id::text AS id`,
    [/* ... */]
  );
  return res.rows[0];
}
```

**Commit/fail transition pattern** (lines 359-379):
```typescript
export async function markWriteCommitted(id: string, itglueResponse: unknown): Promise<void> {
  await postgresClient.query(
    `UPDATE itglue_writes SET status = 'committed', itglue_response = $2::jsonb WHERE id = $1`,
    [id, JSON.stringify(itglueResponse ?? null)]
  );
}

export async function markWriteFailed(id: string, errorMessage: string): Promise<void> {
  await postgresClient.query(
    `UPDATE itglue_writes SET status = 'failed', error_message = $2 WHERE id = $1`,
    [id, errorMessage]
  );
}
```
Route 53's `createPendingAuditLog()` / `markAuditCommitted()` / `markAuditFailed()` should follow this exact three-function shape against `route53_audit_log`.

---

### `lib/services/sync-scheduler.ts` (modified — extend `sync_type` union + `defaultSchedules` + dispatch)

**`sync_type` union** (line 25) — append `'route53-incremental' | 'route53-full'` to the existing pipe-delimited string union.

**`defaultSchedules` entry pattern** (lines 198-221, `veeam-incremental`/`veeam-full`/`veeam-rpo-check`):
```typescript
{
  id: 'veeam-incremental',
  name: 'Veeam Incremental Sync',
  description: 'Syncs Veeam backup data every 30 minutes',
  cron_expression: '*/30 * * * *',
  sync_type: 'veeam-incremental',
  is_enabled: false,
},
{
  id: 'veeam-full',
  name: 'Veeam Full Sync',
  description: 'Full Veeam backup data sync daily at 2:00 AM',
  cron_expression: '0 2 * * *',
  sync_type: 'veeam-full',
  is_enabled: false,
},
```
Route 53 per D-11 (incremental + daily full): add `route53-incremental` (e.g. `*/15 * * * *`) and `route53-full` (e.g. `0 3 * * *`, avoiding collision with `weekly-full`'s `0 3 * * 0` and `veeam-full`'s `0 2 * * *`), both `is_enabled: false` by default (matches every new-integration default in this file).

**Dispatch branch pattern — PAX8's config+disable-gated branch** (lines 478-493, the one *exception* pattern, per D-10 explicitly NOT to copy the blocking behavior):
```typescript
} else if (config.sync_type === 'pax8-daily') {
  const { isPax8Configured } = await import('@/lib/services/pax8-factory');
  if (!isPax8Configured()) {
    console.log('[SCHEDULER] Skipping pax8-daily — PAX8 not configured');
  } else {
    const disabledRes = await postgresClient.query<{ disabled: boolean }>(
      `SELECT disabled FROM integration_settings WHERE key = 'pax8'`
    );
    const isDisabled = disabledRes.rows[0]?.disabled === true;
    if (isDisabled) {
      console.log('[SCHEDULER] Skipping pax8-daily — PAX8 disabled via /admin/integrations');
    } else {
      const { getPax8SyncService } = await import('@/lib/services/pax8-sync-service');
      await getPax8SyncService().fullSync('scheduled');
    }
  }
}
```
**Route 53's branch must OMIT the `integration_settings.disabled` gate entirely** (D-10 — disable is display-only, scheduler keeps running):
```typescript
} else if (config.sync_type === 'route53-incremental') {
  const { isRoute53Configured } = await import('@/lib/services/route53-factory');
  if (!isRoute53Configured()) {
    console.log('[SCHEDULER] Skipping route53-incremental — Route 53 not configured');
  } else {
    const { getRoute53SyncService } = await import('@/lib/services/route53-sync-service');
    await getRoute53SyncService().incrementalSync('scheduled');
  }
} else if (config.sync_type === 'route53-full') {
  const { isRoute53Configured } = await import('@/lib/services/route53-factory');
  if (!isRoute53Configured()) {
    console.log('[SCHEDULER] Skipping route53-full — Route 53 not configured');
  } else {
    const { getRoute53SyncService } = await import('@/lib/services/route53-sync-service');
    await getRoute53SyncService().fullSync('scheduled');
  }
}
```
Config-only check pattern for `isXConfigured()` mirrors the `mimecast-sync` branch (lines 494-504) equally well — both use dynamic `import()` to avoid eager-loading the sync service module at scheduler-import time.

---

### `lib/services/integration-health.ts` (modified — add `checkRoute53()`)

**Live-check pattern with custom body** (analog: `checkDattoRmm()`, lines 145-191) vs. **generic `liveCheck()` helper pattern** (analog: `checkItglue()`, lines 193-209):
```typescript
async function checkItglue(): Promise<IntegrationHealth> {
  const apiKey = process.env.ITGLUE_API_KEY;
  const checkedAt = new Date().toISOString();
  if (!apiKey) {
    return { key: 'itglue', name: 'IT Glue', category: 'docs', status: 'not_configured', configured: false, checkedAt };
  }
  const live = await liveCheck({
    url: 'https://api.itglue.com/organizations?page[size]=1',
    headers: { 'x-api-key': apiKey },
  });
  return { key: 'itglue', name: 'IT Glue', category: 'docs', status: live.status, configured: true, latencyMs: live.latencyMs, error: live.error, checkedAt };
}
```
Route 53 needs a **custom** check function (not the generic `liveCheck()` fetch helper, since it's an AWS-SDK-signed call, not a plain HTTP fetch) that composes: (1) an `isRoute53Configured()` gate identical to `checkDattoRmm()`'s `if (!url || !key || !secret)` early return; (2) an auth probe via `ListHostedZonesCommand({ MaxItems: '1' })`; (3) D-12's NS-delegation check across all zones, using the `dns.Resolver()` snippet from RESEARCH.md's Code Examples section (dedicated resolver instance, `setServers(['1.1.1.1','8.8.8.8'])`, never the global `dns.setServers()`). A mismatch on any zone should degrade the overall `status` (e.g. to a new/reused non-`ok` status) — extend `IntegrationHealth`'s shape with an optional field (e.g. `nsDelegationMismatches?: string[]`) rather than overloading `error`.

**`checkConfigOnly()` fallback pattern** (lines 238-252) — NOT sufficient for Route 53 given D-12's mandatory live check, but useful during early-phase scaffolding before the full check is built:
```typescript
function checkConfigOnly(key: string, name: string, category: IntegrationHealth['category'], envVars: string[]): IntegrationHealth {
  const checkedAt = new Date().toISOString();
  const allSet = envVars.every((v) => !!process.env[v]);
  return { key, name, category, status: allSet ? 'unknown' : 'not_configured', configured: allSet, checkedAt };
}
```

**Registration point** (lines 325-352, inside `Promise.all([...])` in `checkIntegrationHealth()`): add `checkRoute53(),` alongside `checkAutotask()`, `checkDattoRmm()`, etc. (not wrapped in `Promise.resolve()` since it's already async, matching `checkAutotask()`/`checkDattoRmm()`'s bare-call style, not the `checkConfigOnly()` wrapped style).

**`IntegrationHealth.category` union** (line 36) — add `'network'` category reuse (already exists, used by Auvik/Zabbix) or a new value if DNS warrants its own bucket; RESEARCH.md doesn't mandate a new category, `'network'` fits.

---

### `app/admin/sync/page.tsx` (modified — extend `INTEGRATIONS` tile array)

**Tile shape** (lines 9-16, interface; line 29 PAX8 entry):
```typescript
interface IntegrationCard {
  id: string;
  category: string;
  product: string;
  description: string;
  href: string;
  logo: string;
  color: string;
}
// ...
{ id: 'pax8', category: 'Licensing', product: 'PAX8', description: 'Companies, subscriptions, products, and license billing', href: '/admin/sync/pax8', logo: '/logos/pax8.ico', color: 'blue' },
```
Add: `{ id: 'route53', category: 'DNS', product: 'AWS Route 53', description: 'Hosted zones, DNS records, change history, NS-delegation health', href: '/admin/sync/route53', logo: '/logos/route53.ico', color: 'orange' }` (confirm a `/logos/route53.ico` asset exists or is added; color should not collide with an adjacent tile — `orange` is already used by `datto-rmm`, consider `yellow` or check `COLOR_MAP` for available values before finalizing).

---

### `app/admin/sync/route53/page.tsx` (component, request-response)

**Analog:** `app/admin/sync/veeam/page.tsx` (647 lines — multi-tab detail page)

**Imports pattern** (lines 3-22):
```typescript
import { useState, useEffect } from 'react';
import Link from 'next/link';
import { Button } from '@/components/ui/button';
import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
import { StatusBadge } from '@/components/ui/status-badge';
import SyncScheduler from '@/components/admin/SyncScheduler';
import { useUserTimezone } from '@/lib/hooks/use-user-timezone';
```

**Data-fetch tab pattern** (lines 197-243, sync-history tab + agents tab):
```typescript
const [rows, setRows] = useState<any[]>([]);
const [loading, setLoading] = useState(true);
useEffect(() => {
  fetch('/api/sync/history?entityType=veeam&limit=50')
    .then(r => r.json())
    .then(d => setRows(d.rows ?? d))
    .finally(() => setLoading(false));
}, []);
```
Route 53's zones/records/history tabs follow this exact `useState`/`useEffect`/`fetch()` shape — no SWR, per CLAUDE.md. Use `components/admin/DataTable.tsx` for the zones/records list (RESEARCH.md's Reusable Assets) and `components/admin/DetailModal.tsx` for record before/after drill-down (formatted/raw tabs already established there).

**Manual-sync-trigger pattern** (lines 567-593):
```typescript
const [syncing, setSyncing] = useState(false);
const handleSync = async () => {
  setSyncing(true);
  try {
    await fetch('/api/veeam/sync', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({}) });
    // poll for completion
    const r = await fetch('/api/veeam/sync');
    // ...
  } finally {
    setSyncing(false);
  }
};
```
Route 53's "Sync Now" button follows this shape against `/api/route53/sync`.

---

## Shared Patterns

### Auth gating — reads vs. writes
**Source:** `lib/auth-utils.ts` lines 31-45 (`requireAuth`), 51-78 (`requirePermission`), 79-103 (`requireAdmin`)
```typescript
export async function requireAuth() {
  const session = await getSession();
  if (!session) {
    return { session: null, error: NextResponse.json({ error: "Unauthorized" }, { status: 401 }) };
  }
  return { session, error: null };
}

export async function requireAdmin() {
  const { session, error } = await requireAuth();
  if (error) return { session: null, error };
  const userRole = (session!.user as UserWithRole).role || "user";
  if (userRole !== "admin" && userRole !== "super-admin") {
    return { session: null, error: NextResponse.json({ error: "Forbidden - Admin access required" }, { status: 403 }) };
  }
  return { session, error: null };
}
```
**Apply to:** All `app/api/route53/*` write routes (`requireAdmin()`, per D-04) and read routes (`requireAuth()` at minimum, matching itglue/veeam's read-route convention per RESEARCH.md's ASVS V4 note).

### Failed-write audit logging (D-07)
**Source:** `app/api/analyzer/itglue/applications/[id]/apply/route.ts` lines 188-200 (catch block) + `lib/services/analyzer/asset-audit/persistence.ts` lines 372-379 (`markWriteFailed`)
```typescript
} catch (err) {
  const message = err instanceof Error ? err.message : String(err);
  await markWriteFailed(writeRow.id, message);
  return NextResponse.json({ writeId: writeRow.id, status: 'failed', error: '... write failed', message }, { status: 502 });
}
```
**Apply to:** Every `app/api/route53/zones/[zoneId]/records/*` POST/PATCH/DELETE route — the pending-row-before-external-call discipline is non-negotiable per RESEARCH.md ("never write to the external system without an audit row already in flight").

### Dedicated-schema-per-integration migrations
**Source:** `migrations/091_pax8_tables.sql` (whole file) — `raw_payload JSONB`, `synced_at`/`is_deleted`/`deleted_at` audit columns, `idx_<table>_is_deleted` index per table, soft (non-FK) refs where sync insert order isn't guaranteed, hard FK only for true header/line relationships.
**Apply to:** `route53_zones` / `route53_records` (mirror tables) — `route53_record_history` / `route53_audit_log` (ledger tables) should instead follow `migrations/075_itglue_audit.sql`'s `itglue_writes` shape (status CHECK constraint, `performed_by_user_id` FK to `"user"(id) ON DELETE SET NULL`, `performed_at`/`generated_at` timestamps).

### `integration_settings` display-only disable toggle (D-10)
**Source:** `migrations/081_integration_settings.sql` (seed pattern), `lib/services/integration-health.ts` `applyDisableOverlay()` (lines 310-319)
```sql
INSERT INTO integration_settings (key, disabled) VALUES ('route53', false) ON CONFLICT (key) DO NOTHING;
```
```typescript
async function applyDisableOverlay(items: IntegrationHealth[]): Promise<IntegrationHealth[]> {
  const [envSet, dbSet] = [getEnvDisabledKeys(), await getDbDisabledKeys()];
  if (envSet.size === 0 && dbSet.size === 0) return items;
  const disabled = new Set([...envSet, ...dbSet]);
  return items.map((item) => disabled.has(item.key) ? { ...item, status: 'disabled', error: null, configured: false } : item);
}
```
**Apply to:** `checkRoute53()`'s result flows through this existing overlay automatically once `key: 'route53'` is used — no new overlay code needed. **Do not** add a Route 53 branch to the sync-scheduler's dispatch that checks `integration_settings.disabled` (that's the PAX8-only exception, explicitly not to be replicated per D-10).

### Live DNS resolution via a dedicated `dns.Resolver()` instance (D-12)
**Source:** `lib/services/pipeline-steps/ping-flap-suppress.ts` line 6 (`import { promises as dns } from 'dns';` — existing codebase precedent for using Node's `dns` module) + RESEARCH.md's Code Examples section (full `checkNsDelegation()` implementation using `new Resolver()` + `setServers()` + `promisify()`)
```typescript
import { Resolver } from 'dns';
import { promisify } from 'util';

const resolver = new Resolver();
resolver.setServers(['1.1.1.1', '8.8.8.8']); // dedicated instance — does not affect global dns resolution
const resolveNs = promisify(resolver.resolveNs.bind(resolver));
```
**Apply to:** `checkRoute53()` in `lib/services/integration-health.ts` only. Never call the global `dns.setServers()` — that would affect all DNS resolution in the process, including internal service hostnames (RESEARCH.md Pitfall 5).

## No Analog Found

None. Every file in this phase has at least a role-match analog; the CRUD write-back pattern (the phase's highest-risk area) has an exact analog in the IT Glue write pipeline.

## Metadata

**Analog search scope:** `lib/services/*.ts` (veeam-*, datto-rmm-*, pax8-*), `lib/services/analyzer/asset-audit/`, `lib/services/pipeline-steps/`, `app/api/pax8/`, `app/api/analyzer/itglue/`, `app/admin/sync/`, `migrations/075_*`, `migrations/081_*`, `migrations/091_*`, `lib/auth-utils.ts`
**Files scanned:** 15 read in full or targeted excerpt
**Pattern extraction date:** 2026-08-05
