Skip to content

ADR — Production hostname is docs.adventive.dev

  • Date: 2026-04-27
  • Status: Accepted
  • Project: engineering-docs-site

Decision

The engineering documentation site will be served at https://docs.adventive.dev.

Context

Three candidates were considered:

Candidate Pros Cons
engineering.adventive.com Memorable, on the primary brand domain Implies broader scope than just engineering docs
engineering.adventive.internal Internal-only signal Requires the resolver to know .internal; less convenient for shared bookmarks
docs.adventive.dev (chosen) Generic doc surface, .dev TLD signals engineering audience and forces HTTPS, allows future product/customer doc surfaces to share the host None material

adventive.dev is already owned by Adventive and the zone is active in Cloudflare, so DNS, TLS, and Pages custom-hostname setup are immediate.

The .dev TLD is on the HSTS preload list — every connection is HTTPS by default, no opportunity for accidental plaintext. This complements the Cloudflare Access gate.

Consequences

Positive:

  • Frees engineering.adventive.com for any future engineering-team-facing surface that isn't documentation (status page, internal tools).
  • docs.adventive.dev is ergonomic for any future Adventive doc surfaces (product docs, customer-facing API docs, partner docs) — they can subpath off the same host or take sibling subdomains.
  • HSTS preload gives a default-secure transport posture.

Negative / accepted trade-offs:

  • Two brand domains in active use (adventive.com for primary surfaces, adventive.dev for engineering). Acceptable — the audiences are distinct.

Implementation

DNS in Cloudflare:

docs.adventive.dev    CNAME    <project>.pages.dev

(Cloudflare Pages creates the CNAME automatically when the custom hostname is added in the Pages project.)

TLS: handled by Cloudflare Universal SSL.

Access: a single self-hosted application protects docs.adventive.dev/*. See 2026-04-27-idp-jumpcloud.md for identity binding.

Operational note

If we later add a public, ungated section (e.g. a public release-notes page), it gets a separate Access app with its own policy bound to a more permissive ruleset — the main site stays fully gated.