Domain Registration Flow: Architecture & Pseudo-Code

Domain Registration Architecture & Flow

This document outlines the architectural flow and pseudo-code for allowing users to register custom domains directly during the signup process. This integration relies on Namecheap (Registrar), Cloudflare (DNS & Protection), and Resend (Outbound Email).

High-Level Workflow

1. Availability Check: User searches for a domain. System checks availability via Namecheap.
2. Purchase: User pays for the domain.
3. Provisioning (Async Worker):
   • Register domain with Namecheap.
   • Create Zone in Cloudflare.
   • Update Nameservers at Namecheap to point to Cloudflare.
   • Configure DNS records in Cloudflare (SPF, DKIM, DMARC, MX).
   • Register domain with Resend for sending.

Detailed Steps & API Requirements

1. Domain Availability

Provider: Namecheap Endpoint: domains.check

• Input: Domain string.
• Output: Boolean (available/taken), Price.
• Note: Cache results briefly to prevent API spam.

2. Domain Registration

Provider: Namecheap Endpoint: domains.create

• Input: Domain, Years (1), Registrant Info (We can use our privacy proxy details or user's details if required by ICANN, usually privacy protection is preferred).
• Action: Unlocks the domain for management.

3. DNS Setup (Cloudflare)

Provider: Cloudflare Endpoint: zones.create

• Action: Create a new zone for the user's domain in our Cloudflare account (or partial setup if using 'Cloudflare for SaaS' - but full zone setup gives more control).
• Result: Cloudflare assigns nameservers (e.g., amy.ns.cloudflare.com).

4. Nameserver Update

Provider: Namecheap Endpoint: domains.dns.setCustom

• Action: Update the domain's nameservers to the ones provided by Cloudflare.
• Latency: Propagation can take minutes to hours.

5. DNS Records Configuration

Provider: Cloudflare Endpoint: zones.dns_records.create We need to add the following records:

• MailGuard MX: route1.mx.mailguard.cc (Priority 10)
• Resend SPF: v=spf1 include:resend.com ~all (TXT @)
• Resend DKIM: resend._domainkey (TXT, provided by Resend)
• DMARC: v=DMARC1; p=none; (TXT _dmarc) - Start with p=none for safety.

6. Sending Configuration

Provider: Resend Endpoint: domains.create

• Action: Register the domain in Resend to get DKIM tokens.
• Verification: After adding DNS records to Cloudflare, call domains.verify on Resend.

Pseudo Code Logic

// Types based on hypothetical API responses
interface DomainAvailability {
  domain: string;
  available: boolean;
  price: number;
}

interface ProvisionResult {
  success: boolean;
  domainId: string;
  cloudflareZoneId: string;
  resendDomainId: string;
}

async function handleDomainPurchase(user: User, domainName: string): Promise<void> {
  // 1. Check Availability one last time
  const check = await Namecheap.checkAvailability(domainName);
  if (!check.available) throw new Error("Domain no longer available");

  // 2. Process Payment (Stripe)
  await PaymentService.charge(user, check.price);

  // 3. Trigger Async Provisioning Worker
  await Queue.add("provision-domain", { userId: user.id, domain: domainName });
}

// Background Worker Code
async function provisionDomainWorker(job: { userId: string, domain: string }) {
  const { domain, userId } = job;

  try {
    // A. Register Domain
    // We use our organization info for initial reg (or user's if strictly required)
    // Detailed contact info mapping required here
    await Namecheap.registerDomain({
      domain,
      years: 1,
      contactInfo: DEFAULT_CONTACT_INFO 
    });

    // B. Setup Cloudflare Zone
    const cfZone = await Cloudflare.createZone({ name: domain });
    const nameServers = cfZone.name_servers; // e.g. ['ns1.cloudflare.com', 'ns2...']

    // C. Point Domain to Cloudflare
    await Namecheap.setNameservers({
      domain,
      nameservers: nameServers
    });

    // D. Configure Resend (to get SPF/DKIM keys)
    const resendDomain = await Resend.domains.create({ name: domain });
    
    // E. Add DNS Records to Cloudflare
    const records = [
      // MailGuard MX
      { type: 'MX', name: '@', content: 'route1.mx.mailguard.cc', priority: 10 },
      // DMARC
      { type: 'TXT', name: '_dmarc', content: 'v=DMARC1; p=none;' },
      // Resend SPF (from resendDomain response usually, or static include)
      { type: 'TXT', name: '@', content: 'v=spf1 include:resend.com ~all' },
      // Resend DKIM (Iterate over records returned by Resend)
    ];

    // Add Resend specific records
    resendDomain.records.forEach(r => {
      records.push({
        type: r.type, // TXT, MX, etc.
        name: r.name,
        content: r.value,
        priority: r.priority
      });
    });

    // Execute Cloudflare updates
    for (const record of records) {
      await Cloudflare.createDNSRecord(cfZone.id, record);
    }

    // F. Verify Resend
    // Might need a delay or retry mechanism here as DNS propagates
    await Utility.sleep(10000); // Wait 10s
    await Resend.domains.verify(resendDomain.id);

    // G. Store in Database
    await DB.insert(domains).values({
      userId,
      domain,
      status: 'active',
      provider: 'namecheap',
      dnsProvider: 'cloudflare',
      mailProvider: 'resend'
    });

    // Notify User
    await NotificationService.send(userId, "Domain setup complete!");

  } catch (error) {
    console.error("Domain provision failed", error);
    // Handle partial failures manually or with compensation logic (reverts)
    // Critical: Alert admin on failure as money has changed hands
  }
}

Failure Handling & Edge Cases

• Registration Failure: If Namecheap fails after payment (rare but possible), immediate refund or admin alert is required.
• Propagation Delays: Cloudflare DNS updates are fast, but Namecheap NS updates can take time. The Resend verification step might fail initially. The worker should support retries with exponential backoff for the verification step.
• User Information: ICANN validation requires valid user contact info. We must collect this during signup (Address, Phone, Email) or use a "Privacy Guard" service if Namecheap supports it seamlessly for the registrant.