ADR-0004: Custom domains via Cloudflare for SaaS, dashboard on the core domain

• Date: 2026-09-18
• Status: Proposed (seed — awaiting the owner's approval)
• Deciders: the owner, Claude (seed)
• Tags: infra domain

Context

The original requirement: public pages on the merchant's domain, and the control panel on the project's domain. Thousands of domains need automatic SSL, fast routing, and security isolation from the dashboard.

Decision

The planned apps/storefront (a Cloudflare Worker) serves Custom Hostnames through Cloudflare for SaaS plus the wildcard *.mahalli.sa; apps/saas serves app.mahalli.sa only.

• An edge cache (KV) maps hostname → { tenantId, siteId }; the source of truth is the domains table in Postgres.
• Verification by CNAME / TXT, domain status shown in the dashboard, SSL managed by Cloudflare.
• Two different origins → independent cookies, authentication, and CSP.

Consequences

• Positive — zero-touch setup for the merchant, automatic SSL, security isolation of the dashboard.
• Negative — a per-hostname cost for custom domains (covered by the Growth plan and above).
• Revenue impact (SAR / month, confidence) — the custom domain is the lever for upgrading to Growth (+150 SAR per upgraded merchant, medium confidence).

Rejected alternatives

• A generic reverse proxy (Nginx / Caddy) on a VPS: manual certificate management that does not scale.
• Merchant sites on a subdomain only: loses the original requirement and the trust it brings.

References

• docs/00-vision.md, docs/02-architecture.md