diff --git a/.planning/phases/24-aws-route-53-dns-sync-track-changes-crud-operations-full-aud/24-PATTERNS.md b/.planning/phases/24-aws-route-53-dns-sync-track-changes-crud-operations-full-aud/24-PATTERNS.md new file mode 100644 index 0000000..0b76c70 --- /dev/null +++ b/.planning/phases/24-aws-route-53-dns-sync-track-changes-crud-operations-full-aud/24-PATTERNS.md @@ -0,0 +1,736 @@ +# 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 { + return this.executeSync('full', triggeredBy); + } + + async incrementalSync(triggeredBy: string = 'system'): Promise { + return this.executeSync('incremental', triggeredBy); + } + + private async executeSync(syncType: 'full' | 'incremental', triggeredBy: string): Promise { + 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 }> = [ + { 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 { + 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 { + 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 { + 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([]); +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__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 { + 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