Site generation watcher workflow

Evidence reviewed 2026-08-04: the production app is healthy and its internal queue route rejects unauthenticated requests; all three handoff routes and the admin preview queue are present in the current repository. Render has a live, unsuspended Preview Notifications Cron Job every 15 minutes, but no deployed site-generation Cron Job. The generation runner remains a model-agnostic, local-only implementation pending a verified live generation path.

Core (built, DB-verified)Verification gateNotificationBlack box -- deferred, modular

Application / internal API perspective (build now)

Prior stage

Claim approved

Business status becomes Claimed.

business_claimed (10)
→
Core

Immediately queued

Same transaction as claim approval sets the current stage to the queue signal.

awaiting_site_generation (11)
→
Core

Queue API endpoint

Wraps getBusinessesAwaitingSiteGeneration() -- authenticated, internal-only.

→
Normal completion

One-time complete endpoint

Wraps recordSiteGenerated(businessId, siteUrl). It accepts only Awaiting Site Generation records without a saved generated URL.

ready_for_preview (12)
→
Narrow recovery

Verified regeneration completion

Only for Awaiting Site Generation plus an existing URL after a newly verified regeneration. Requires authentication, explicit reason, row lock and audit transition.

ready_for_preview (12)
→
Core

Notify API endpoint

Wraps getBusinessesReadyForPreviewNotification() + prepare/send -- idempotent, callable anytime.

→
Notification

Preview-ready email sent

Already built and live-tested this session -- arrives in Inbox with the generated site link.

Render Cron Job perspective (build now, except the black box)

Partial

Render Cron service status

Preview Notifications Cron is cloud-hosted and scheduled. A site-generation Cron Job is not currently deployed.

→
Core

Calls the Queue API

Gets the list of businesses awaiting generation.

→
Black box

Generation module (shared/reused)

Deliberately deferred. Model-agnostic. Same module is reused later to apply owner-requested changes -- not a fresh-generation-only tool.

→
Core

Calls the Complete API

Passes businessId + the resulting siteUrl once the black box succeeds.

→
Core

Calls the Notify API

The separately deployed Preview Notifications Cron calls this route every 15 minutes; a generation cron remains pending.

Explicit admin-controlled preview delivery (recommended)

Eligibility

Ready for Preview queue

Admin screen lists only records at ready_for_preview with a live generated URL, contact email, and no prior preview-ready delivery.

→
Optional admin action

Send site preview links

Admin can review eligible businesses, select one or more, and explicitly send outside the scheduled Cron cycle. This supplements—not replaces—the Cron path.

→
Audit

Prepare and send

Application creates delivery records, checks allowlist/approval, sends each selected URL through Gmail, and records the provider outcome.

→
Outcome

Delivery result visible

Admin sees sent / skipped / failed per business. Sent rows become ineligible, preventing duplicates.