Non Production Environment Taxonomy

Non-Production Environment Taxonomy & Client Preview Ingress Architecture

1. Executive Summary & Architectural Overview

SiteSwarm divides non-production cloud execution into a strictly defined 3-Tier Non-Production Taxonomy:

Tier A: Ephemeral PR Previews (preview GitHub Environment)
Tier B: Internal Staging (staging GitHub Environment)
Tier C: Long-Lived Client Previews (preview / client-preview GitHub Environment)

This taxonomy resolves the fundamental tension between corporate Zero Trust security and sales velocity / prospect evaluation:

Internal staging and PR engineering environments remain strictly shielded behind the corporate Cloudflare Zero Trust (Access) identity wall to prevent unauthorized data exposure, bot probing, and credential leakage.
Prospective clients evaluating custom prototypes (apps/proto-*) or client applications cannot be forced through corporate Single Sign-On (Google Workspace or GitHub IdP).
Therefore, Long-Lived Client Previews provide an edge routing and access architecture that unblocks the public storefront for external prospects while maintaining a fail-closed perimeter over administrative (/admin*), CMS (/_emdash/admin*), and mutation API surfaces, and automating X-Robots-Tag: noindex, nofollow headers to block search engine indexing.

flowchart TD
    subgraph NonProduction["SiteSwarm 3-Tier Non-Production Fleet"]
        PRPreview["1. Ephemeral PR Preview\n(*-preview-pr-<N>.<domain>)\nEngineering QA | Auto-Teardown on Merge"]
        Staging["2. Internal Staging\n(*-staging.<domain>)\nNightly Debounce | 100% Zero Trust Gated"]
        ClientPreview["3. Long-Lived Client Preview\n(*-preview.<domain> / *.preview.jacobmiller22.com)\nSales & Prospects | Persistent across PRs"]
    end

    subgraph AccessPerimeter["Cloudflare Edge & Zero Trust Gateway"]
        ZeroTrustIdP["Cloudflare Zero Trust Access\n(corporate SSO / IdP Wall)"]
        PublicEdge["Edge Storefront Ingress\n(Direct Worker Compute)"]
    end

    PRPreview --> ZeroTrustIdP
    Staging --> ZeroTrustIdP
    ClientPreview -->|"/admin* & Mutations"| ZeroTrustIdP
    ClientPreview -->|"Public Storefront (/, /about, /menu)"| PublicEdge

    PublicEdge --> EdgeWorker["Client Preview Worker Isolate\n(Auto-injects X-Robots-Tag: noindex, nofollow)"]

2. 3-Tier Non-Production Environment Comparison Matrix

Architectural Dimension	1. Ephemeral PR Previews	2. Internal Staging	3. Long-Lived Client Previews
Primary Audience	Internal Engineers, AI Agents, Blacksmith CI	Core Engineering, Product QA, Automated Playwright Runs	Prospective Clients, Sales Leads, External Stakeholders
Trigger Mechanism	PR `preview-deploy` label or dispatch	Schedule (`0 /12 * *`) or manual dispatch	PR `client-preview` label or dispatch (`client-preview-deploy.yml`)
Persistence & Lifecycle	Ephemeral: Automatically destroyed on PR merge/close	Persistent: Deployed on schedule; continuously mirrors `main`	Long-Lived: Persists across PR merges and sales review cycles
Ingress Hostname Pattern	`<app>-preview-pr-<N>.<workers-domain>` & `<app>-preview-pr-<N>.<platform-domain>`	`<app>-staging.<platform-domain>`	`<app>-preview.<platform-domain>` & `<app>.preview.jacobmiller22.com`
SSL / TLS Certificate	Cloudflare Universal SSL (single-level hyphenated subdomain)	Cloudflare Universal SSL (single-level hyphenated subdomain)	Cloudflare Universal SSL (single-level or dedicated preview zone)
Zero Trust Perimeter	Internal Access application; restricted to engineering staff	100% of paths gated: HTTP 302 to Cloudflare Access login	Hybrid Perimeter: Public storefront unblocked; `/admin*` strictly gated
Administrative Access	Staff Gate / Cloudflare Access	Staff Gate / Cloudflare Access	Gated (HTTP 302 to Cloudflare Access login or HTTP 401 challenge)
Search Engine Protection	`X-Robots-Tag: noindex, nofollow` header	Strict Zero Trust login wall	Automated `X-Robots-Tag: noindex, nofollow` header injection
Inquiry Intake / POS Relay	Emulated / discarded; `send_email` bindings dropped	Staging D1 database; mocked payment relays	In-memory sandbox or demo inquiry routing; no real email delivery

3. Ingress Hostname, Routing & Universal SSL Compliance

Under the platform DNS architecture defined in CLOUDFLARE_FOR_PLATFORMS_AND_DOMAIN_INGRESS.md, standard Universal SSL covers the zone apex (<platform-domain>) and a single wildcard level (*.<platform-domain>). Nested multi-level subdomains (such as preview.bakery.jacobmiller22.com) fail TLS validation on standard plans without paid Advanced Certificate Manager add-ons.

To ensure 100% free TLS coverage and instant custom hostname routing:

Single-Level Hyphenated Subdomains on Platform Zone:
- Client preview hostnames use <slug>-preview.<platform-domain> (e.g. bakery-preview.jacobmiller22.com, software-agency-preview.jacobmiller22.com).
- Covered natively by Cloudflare’s wildcard record *-preview pointing to fallback.<platform-domain>.
Dedicated Preview Zone Subdomains:
- When hosted on a dedicated prospect domain (preview.jacobmiller22.com), the single label <slug>.preview.jacobmiller22.com resolves under that zone’s root or wildcard record.

Dual-Route Binding:

Each preview deployment binds both routes in wrangler.json:

"routes": [
  { "pattern": "<app>-preview.jacobmiller22.com", "custom_domain": true },
  { "pattern": "<app>.preview.jacobmiller22.com", "custom_domain": true }
]

4. Hybrid Security Perimeter: Public Storefront vs. Protected Admin & Mutations

The defining characteristic of Long-Lived Client Previews is the Hybrid Security Perimeter:

4.1 Storefront Unblocked for External Prospects

Paths such as /, /about, /contact, /services, /menu, and static assets (/_astro/*, /assets/*, /favicon.*) execute directly in the Worker without challenging the visitor for corporate Zero Trust credentials.
Prospects experience the site with the exact performance, responsive layout, and visual fidelity of a live production site.
Interactive prospect demonstrations (e.g., interactive catering quote estimators or cost calculators) operate cleanly in client-side JavaScript.

4.2 Fail-Closed Administrative & Mutation Perimeter

All administrative routes (/admin, /admin/*, /_emdash/admin, /_emdash/admin/*) and mutation API endpoints (POST /api/admin/*, PUT /api/*, DELETE /api/*) enforce fail-closed security:
- If a valid Cf-Access-Jwt-Assertion header is present (indicating an authenticated employee accessing through Cloudflare Access), the request proceeds to administrative handlers.
- If unauthenticated, HTML requests receive an HTTP 302 redirect to the corporate Cloudflare Access login portal (https://<team>.cloudflareaccess.com/cdn-cgi/access/login?...).
- API and JSON requests receive an HTTP 401 Unauthorized challenge with structured error code ZERO_TRUST_CREDENTIALS_REQUIRED.
Failure-Mode Invariant: Manipulating query parameters (e.g. ?env=preview), request headers, or path segments cannot bypass this perimeter.

5. Automated Search Engine Crawler Indexing Mitigation

Prototypes and client previews must never be indexed by search engine crawlers (Googlebot, Bingbot, YandexBot) to prevent:

Brand confusion or negative SEO ranking signals for the prospective client.
Duplicate content penalties against the client’s existing production domain.
Leaking unreleased prospect mockups or pricing concepts into public search results.

SiteSwarm enforces crawler protection at two distinct layers:

Automated X-Robots-Tag Header Injection:
- Every HTTP response originating from a client preview isolate (evaluated via packages/governance/src/security/client-preview.ts middleware or edge wrappers) automatically carries:
```
X-Robots-Tag: noindex, nofollow
X-SiteSwarm-Environment: client-preview
```
- Because HTTP response headers take absolute precedence over HTML meta tags according to Google and Bing crawler specifications, this protects non-HTML responses (PDFs, JSON, SVGs, images) as well as HTML documents.
Canonical <meta name="robots" content="noindex, nofollow"> Tag:
- Core layouts in client applications integrate the @siteswarm/seo capability, rendering the fallback robots meta tag on preview domains.

6. Deployment Pipeline & Persistence Governance

Unlike Ephemeral PR Previews (which are destroyed whenever a Pull Request closes via .github/workflows/preview-teardown.yml), Long-Lived Client Previews:

Are deployed via .github/workflows/client-preview-deploy.yml into the preview GitHub Environment.
Are named deterministically as <app>-client-preview (e.g. green-leaf-bakery-client-preview).
Persist independently of PR lifecycle hooks, allowing sales engineers to share links with prospective clients over days or weeks.
Can be decommissioned on demand via workflow dispatch input decommission: true.