ADR-0008: DNS-Only Cloudflare Mode¶
Status: Accepted Date: 2026-03-24 Session: 23B
Context¶
Curaway uses Cloudflare for DNS management of its custom domain. Cloudflare offers two modes for DNS records:
- Proxied mode (orange cloud): Traffic flows through Cloudflare's edge network, enabling CDN caching, DDoS protection, WAF, and bot management.
- DNS-only mode (grey cloud): Cloudflare only resolves DNS; traffic goes directly to the origin server.
During Session 23B, the API started intermittently returning HTML instead of JSON. Investigation revealed that Cloudflare's proxy, in orange-cloud mode, was injecting HTML challenge pages (CAPTCHAs, "checking your browser" interstitials) in front of API requests. The Next.js frontend and mobile clients expected JSON responses and crashed when they received HTML.
Decision¶
Use DNS-only mode (grey cloud) for all Cloudflare DNS records pointing to Curaway's Railway-hosted services.
Rationale¶
- Root cause resolution. Cloudflare's bot detection and browser challenges are designed for human-facing web pages, not API endpoints. API clients (the Next.js frontend making
fetch()calls, future mobile apps) cannot solve CAPTCHAs or JavaScript challenges. DNS-only mode eliminates this entire class of issues. - Railway handles SSL. Railway provides automatic SSL certificate provisioning and termination. Cloudflare's SSL is redundant when using DNS-only mode, and removing the double-SSL hop simplifies the TLS chain.
- Predictable behavior. With DNS-only mode, what you deploy is what gets served. No intermediate layer can modify headers, inject scripts, or cache stale responses.
- Debugging simplicity. When an API issue occurs, there is one fewer layer to investigate. "Is this a Cloudflare issue or a Railway issue?" becomes just "Is this a Railway issue?"
Alternatives Considered¶
| Alternative | Pros | Cons | Verdict |
|---|---|---|---|
| Configure Cloudflare page rules | Keep DDoS protection while exempting API paths from challenges | Complex to maintain, fragile (new endpoints need new rules), still risks edge cases | Rejected |
| Cloudflare API Shield | Purpose-built for API traffic behind Cloudflare proxy | Enterprise plan feature, expensive, overkill for current scale | Rejected |
| Switch DNS provider entirely | Clean break from Cloudflare | Unnecessary; Cloudflare DNS-only mode works fine and is fast | Rejected |
| Separate domains | Proxy mode for marketing site, DNS-only for API | Added complexity, CORS configuration, certificate management for two domains | Deferred |
Consequences¶
- Positive: API responses are always JSON. No more HTML challenge pages breaking clients.
- Positive: Simpler debugging. One fewer layer between client and server.
- Positive: Slightly lower latency (traffic goes directly to Railway instead of through Cloudflare's edge).
- Negative: No Cloudflare DDoS protection. Railway's infrastructure must handle any volumetric attacks.
- Negative: No Cloudflare CDN caching for static assets served by the API (if any).
- Negative: No Cloudflare analytics on API traffic.
- Accepted risk: At Curaway's current scale, DDoS attacks are unlikely. If they become a concern, Cloudflare proxy can be re-enabled with proper API Shield configuration or a separate domain for the API.