Decision: Internal-only docs site hostname

Date: 2026-04-29 Status: OPEN — awaiting Kristerpher's call on Option A vs B (see Section 4) Decision by: Kristerpher Drafted by: raxx-pm-bot (PM), BLR section: placeholder (see Section 5)

1. Current state

The internal-only operator/admin documentation site currently lives at:

https://raxx-mockups.pages.dev/internal-docs/

Protected by Cloudflare Access (same trust boundary as repo access). Built by scripts/build-internal-docs.py, deployed via .github/workflows/deploy-internal-docs.yml to the raxx-mockups Cloudflare Pages project. The gallery of design mockups co-deploys into the same project under dist/.

This URL is a pages.dev subdomain, not a raxx.app branded URL. It works but: (a) it's not memorable, (b) the project name raxx-mockups implies only mockups live there, and (c) pages.dev links in runbooks break if the project is renamed.

2. Inventory of internal-only surfaces (next 6-12 months)

Based on open issues and project memory — not guesses.

Key observations:

1. console.raxx.app is already the umbrella for operator-facing tooling — it has its own domain, its own Heroku deployment, its own auth (passkey + TOTP + RBAC). It is NOT a CF Pages site. The internal docs and mockups gallery are CF Pages and are structurally separate from console.

2. The internal status page is already planned as a sub-page of the console (/dashboard route under #146) — not a separate subdomain.

3. No new operator-internal CF Pages surfaces are planned in the next 6-12 months beyond docs + mockups. The only other raxx.app subdomain additions coming are demo.raxx.app (public) and docs.raxx.app (public).

4. The investor data room, Drive ledger, and metrics dashboards are NOT moving to raxx.app — they live in vendor systems.

3. Trade-off analysis

Option A — internal.raxx.app/docs (umbrella subdomain)

How it works: Single CNAME internal.raxx.app → raxx-mockups CF Pages project. Both docs and mockups live as paths (/docs, /mockups). Future internal CF Pages surfaces could be added as additional paths.

Pros: - One memorable hostname for all internal CF Pages content. - Clean namespace: internal.* is self-documenting — anything there is operator-only, CF Access gated. - Easier to link in runbooks: "go to internal.raxx.app" rather than "go to internal-docs.raxx.app and also mockups.raxx.app." - If a third internal CF Pages surface is needed in the future, it fits cleanly without a new DNS entry.

Cons: - Requires path routing within the CF Pages dist/ output — the docs builder and the mockups gallery must co-exist in subdirectories, not both at /. - Build script changes needed: scripts/build-internal-docs.py currently outputs to dist/internal-docs/. The mockups gallery outputs to dist/. If /docs is the canonical path, the builder may need to adjust its output root, or a _redirects rule handles it. - Marginally more implementation work than Option B (one extra routing card). - Implies a broader surface that "will grow" — but the inventory above shows it probably won't (status, admin, metrics are all going to console or vendor dashboards, not CF Pages).

Verdict: Option A is cleaner as a long-term namespace but requires a path-routing card. The inventory does NOT strongly support the "broader umbrella" thesis — there are only 2 planned CF Pages surfaces (docs + mockups), and console is a completely separate infrastructure tier.

Option B — internal-docs.raxx.app (narrowly scoped subdomain)

How it works: CNAME internal-docs.raxx.app → raxx-mockups CF Pages project. The docs site stays at the root of that subdomain. The mockups gallery gets its own subdomain (mockups.raxx.app?) or stays at raxx-mockups.pages.dev/.

Pros: - Zero path-routing complexity — the docs site owns its subdomain root, no build script output structure changes. - Narrowly scoped: the hostname name matches what it does. No over-promise of a future umbrella that may not materialize. - Implementation is strictly #572 (CNAME + CF Access) — no #573. - The mockups gallery question can be deferred: it can stay at raxx-mockups.pages.dev/ until someone cares enough to move it.

Cons: - Leaves the mockups gallery on an unbranded pages.dev URL. If/when it gets its own subdomain, that's another DNS entry + CF Access app update. - Two separate hostnames to remember if operators reference both docs and mockups regularly. - If a third internal CF Pages surface does appear, it gets yet another subdomain (internal-status.raxx.app?) — proliferation.

Verdict: Option B is simpler to ship and more honest about the actual inventory. The mockups gallery is low-traffic (design review, not daily ops), so leaving it at pages.dev is a reasonable deferral.

4. PM recommendation

Option B — internal-docs.raxx.app — for this sprint.

Rationale:

• The inventory does not support an umbrella. The two surfaces that would live under internal.raxx.app are docs and mockups. Console is already its own domain. Status, admin, and support tooling live in console. Metrics live in vendor dashboards. The "broader umbrella over time" argument doesn't have evidence.
• Option A's path-routing implementation is not hard, but it's additional surface area on top of what should be a straightforward CNAME + CF Access update. Getting internal docs on a branded URL is the immediate goal; don't couple it to a routing refactor.
• If the pattern reverses — if two or three more internal CF Pages surfaces appear in the next cycle — the hostname can always be re-pointed and the _redirects approach used then. DNS is not permanent.
• internal-docs.raxx.app is unambiguous: any operator who reads it knows what it is without context.

If Kristerpher chooses Option A: #573 (path routing) is ready and should be activated after the hostname decision is recorded. Option A is a valid choice; the build script changes are bounded and well-understood.

Open question for Kristerpher: Do you want the mockups gallery to eventually live at mockups.raxx.app or internal.raxx.app/mockups, or is it fine at raxx-mockups.pages.dev indefinitely? This doesn't block the docs hostname decision but affects whether Option A's "umbrella" value argument holds.

5. BLR section (legal/compliance angle)

Status: PLACEHOLDER — BLR agent has not yet written to this file.

The BLR agent is running in parallel. Their branch is docs/internal-docs-hostname-legal. At time of this writing, that branch predates the docs/decisions/ directory and does not yet contain a version of this document.

Questions flagged for BLR input (do not decide these unilaterally):

1. Data classification: Does the internal docs site host any content that carries a legal obligation on access logging (e.g., attorney-privileged materials in docs/legal/, DPIA documents from #502, security vulnerability details)? If so, CF Access access logs may be required — not just CF Access authentication.

2. Attorney-client privilege: docs/legal/research/ may contain attorney-client privileged communications (Matthew Crosby engagement, IP research). Hosting these on a CF Pages site — even behind CF Access — means they exist in Cloudflare's infrastructure. BLR should confirm whether this is acceptable under the current engagement scope or whether legal docs should be excluded from the internal docs build.

3. GDPR Art. 35 / DPIA: The trace architecture DPIA (#502) will be part of docs/security/. If the internal docs site is accessible to support staff, that might affect the access-scoping commitments in the DPIA. BLR should confirm whether docs access for support roles needs to be tiered (support sees ops runbooks but not DPIA drafts, for example).

4. X-Robots-Tag / indexing: The current internal docs site sends X-Robots-Tag: noindex, nofollow. This is a convention, not an enforceable legal control. CF Access is the actual control. BLR should confirm whether noindex is sufficient or whether additional controls are needed for particularly sensitive content.

6. Implementation cards filed

• #572 — Card 1: Attach internal-docs hostname to CF Pages + CF Access app config. Covers CNAME (using CLOUDFLARE_EDIT_DNS vault token), CF Access policy update to cover new hostname, redirect from old pages.dev URL, and build script / workflow URL updates. Valid for both Option A and Option B.

• #573 — Card 2: Wire umbrella path routing for internal.raxx.app (Option A only). Conditional on Option A being chosen; should be closed as not-needed if Option B is selected.

Both cards are linked to epic #146 (raxx-console — operator admin console), which is the closest existing epic for internal operator tooling. If a dedicated "internal surfaces" epic is warranted, it should be filed as a new epic — flag for Kristerpher.