Shipflash logoDocs

Waitlist

Waitlist owns public signup, confirmation, admin review, export, conversion, audit, and waitlist mode behavior.

On this page

Where to look

AreaPaths
Public routesrc/app/(public)/waitlist/page.tsx
Admin routesrc/app/(dashboard)/admin/waitlist/page.tsx
APIsrc/app/api/waitlist/signup, confirm, export
Serversrc/features/waitlist/server/signup, services, actions, conversion, audit.ts, settings.ts, signup-list-query.ts
UIsrc/features/waitlist/ui/signup-form.tsx, src/features/waitlist/ui/admin
Sharedsrc/features/waitlist/shared/mode.ts, status.ts, double-opt-in-state.ts, list-types.ts
Databasewaitlist_signups, analytics_events

Code-backed waitlist map

Public signup and confirmation

Public routes and API handlers delegate signup, confirmation, validation, persistence, notification, and analytics work to waitlist services.

  • src/app/(public)/waitlist/page.tsx
  • src/app/api/waitlist/signup/route.ts
  • src/app/api/waitlist/confirm/route.ts
  • src/features/waitlist/server/signup/services/submit.ts
  • src/features/waitlist/server/signup/services/confirm.ts

Admin operations

Admin pages and actions own review, status changes, bulk actions, resend work, export, and conversion tracking.

  • src/app/(dashboard)/admin/waitlist/page.tsx
  • src/features/waitlist/server/actions/bulk.ts
  • src/features/waitlist/server/services/bulk-status.ts
  • src/features/waitlist/server/services/export.ts
  • src/features/waitlist/server/conversion/service.ts

Modes, status, and settings

Shared mode, status, double opt-in, settings, and admin helpers keep launch behavior explicit.

  • src/features/waitlist/shared/mode.ts
  • src/features/waitlist/shared/status.ts
  • src/features/waitlist/shared/double-opt-in-state.ts
  • src/features/waitlist/server/settings.ts
  • src/features/waitlist/shared/admin/submissions-helpers.ts

Waitlist signup flow

  1. 1

    Read launch mode and validate payload

    Signup services use waitlist settings and payload schemas before accepting public submissions.

    • src/features/waitlist/server/settings.ts
    • src/features/waitlist/server/signup/schemas/payload.ts
  2. 2

    Persist signup state

    Signup persistence owns waitlist_signups writes and supports double opt-in state when enabled.

    • src/features/waitlist/server/signup/persistence/signups.ts
    • src/features/waitlist/server/signup/services/double-opt-in.ts
  3. 3

    Notify and track events

    Signup services queue notifications and analytics events after a valid public submission.

    • src/features/waitlist/server/signup/services/notifications.ts
    • src/features/waitlist/server/signup/services/events.ts
  4. 4

    Operate from admin views

    Admin services handle filtering, bulk status changes, exports, resend, conversion, and audit records.

    • src/features/waitlist/server/signup-list-query.ts
    • src/features/waitlist/server/actions/bulk.ts
    • src/features/waitlist/server/audit.ts

Waitlist rate limit key

Source: src/features/waitlist/server/signup/actions/submit-route.ts

Public waitlist signup uses session and IP rate-limit keys before accepting submissions.

ts
async function enforceWaitlistSignupRateLimit(params: {
  clientIp: string | null;
  sessionId: string | null;
  requestId: string;
  start: number;
}): Promise<WaitlistSignupServiceResult | null> {
  const ratePolicy = getRateLimitPolicy("waitlist_signup");
  const rateKey = buildRateLimitKey({
    prefix: ratePolicy.prefix,
    ip: params.clientIp,
    identifier: params.sessionId ?? "public",
  });
  const rateLimit = await checkRateLimit({
    key: rateKey,
    limit: ratePolicy.limit,
    windowSeconds: ratePolicy.windowSeconds,
  });

  if (rateLimit.allowed) {
    return null;
  }

Waitlist rules

  • Validate public signup payloads.
  • Rate-limit public writes.
  • Keep exports admin-only.
  • Track confirmed, pending, spam, qualified, contacted, archived, and converted states clearly.
  • Keep conversion logic explicit so launch metrics stay understandable.