# Bigscreen Website — Page Setup & Publishing Flow (Milestone v1.0)

## What This Is

The marketing surface at `www.bigscreenvr.com` — currently a Create-React-App SPA whose `App.js` regex dispatcher routes between six layout branches, with most marketing pages served by Builder.io. This milestone introduces a dynamic page-publishing pipeline so a non-engineer marketer (Max) can upload, route, and update standalone webpages to live URLs without touching Jenkins or Builder.io. First target: deploy the finished `bigscreen10` microsite to `https://www.bigscreenvr.com/10years`.

## Core Value

**Max can publish and update a webpage to a live `bigscreenvr.com/<path>` URL via a CLI + Claude Code skill — without Jenkins, without Builder.io, without breaking what's already online.**

## Requirements

### Validated

<!-- Inferred from existing codebase. These are locked. -->

- ✓ React SPA serves marketing surface from `src/App.js` regex dispatcher — existing
- ✓ Builder.io CMS serves most marketing pages via `non-shopify` model — existing
- ✓ Shopify storefront at `store.bigscreenvr.com` operates on separate backend — existing
- ✓ Jenkins is the only path to deploy React SPA changes today — existing
- ✓ Arda admin portal exists in `cloud` repo with OAuth — existing
- ✓ `bigscreen10` microsite is fully built static HTML/CSS/JS — existing (lives in adjacent repo)

### Active

<!-- Hypotheses for v1.0 milestone. -->

- [ ] Mono `static-pages` repo holds source for all non-Builder, non-React static pages
- [ ] Each page declares a deployment manifest (URL path, build hook?, wrapper preference, etc.) at its directory root
- [ ] CLI tool (installable, with Claude Code skill companion) authenticates via Arda OAuth and publishes pages
- [ ] Page registry is live — readable by the React SPA at runtime (no Jenkins redeploy required to surface a new URL)
- [ ] React SPA gets a dynamic routing layer that consults the live registry; replaces the regex dispatcher for new pages and remains capable of routing to Builder.io / static / React-owned screens
- [ ] `/10years` (bigscreen10) deployed via the new pipeline, wrapped in the site-wide nav header + footer
- [ ] A test mutation to `/10years` deploys end-to-end via the new pipeline (no Jenkins, no Builder.io)
- [ ] CLAUDE.md (or equivalent) instructions exist for an LLM agent to perform deployments on Max's behalf
- [ ] Both flat URLs (`/10years`) and namespace subtrees (`/10years/*`) are supported by the routing model

### Out of Scope

- Migrating existing Builder.io pages — Builder.io stays as-is for what it already serves. The new infra is designed to be capable of routing to Builder.io later but no migration in this milestone.
- GUI/web UI for Max — Max uses LLM agents (Claude Code) + CLI. A dedicated admin GUI is unnecessary if the foundation is laid.
- Shopify storefront integration — out of scope; Shopify pipeline untouched.
- Performance optimization of the existing SPA — orthogonal cleanup tracked separately.
- Replacing Jenkins for React SPA deployment — Jenkins remains the high-security path for SPA code changes.

## Context

**Brownfield project.** The codebase has been mapped (`.planning/codebase/*`, commit `90df966`). Stack: CRA 5.0.1, React 18, react-router-dom 6, Builder.io, SASS modules. Node 22 build compatibility recently fixed.

**Existing routing pain points** (from `.planning/codebase/ARCHITECTURE.md`):
- `src/App.js:114-160` regex dispatcher hardcodes every known Builder.io URL — adding a page requires a code edit + Jenkins deploy (see commits `37d2020`, `bd4b0a6`). This anti-pattern is what the milestone solves.
- `builderIoFilter` enumerates page paths instead of letting Builder.io 404 drive fallback.

**Adjacent projects to investigate during research phase:**
- `cloud` — Arda source + deeper web backend. Has nodemon configs for `api`, `admin-api`, `arda`, `cloud-api`, `ws-server`. `cloud/website/src` may indicate hosting/origin model.
- `bigstack` — LLM toolkit for navigating the `cloud` repo.
- `bigscreen10` — first deployment target; today has its own VPS + nginx + GitHub Actions deploy that this milestone supersedes.

**Hosting assumption:** Likely CloudFront + S3 for the SPA bundle. Requires verification via `cloud` / `bigstack` during research.

**Site-wide chrome:** Nav header + footer are owned by the React SPA today. The new pipeline preserves this — `/10years` and future pages render *inside* React's layout, not as standalone pages outside it.

## Constraints

- **Tech stack:** Must remain compatible with current CRA 5 + React 18 + react-router-dom 6 SPA. No framework swap in this milestone.
- **Security:** Jenkins remains gatekeeper for SPA code. Marketing must NOT gain Jenkins access. Publish auth flows through Arda OAuth (role TBD — possibly new `site-editor` role).
- **Backward compatibility:** Existing Builder.io routes and React-owned screens (auth, scans, big orders, account, browser) must continue to work unchanged.
- **Live registry:** New page URLs must surface without an SPA rebuild. SPA fetches the registry at runtime from an authoritative endpoint.
- **LLM-driven UX:** Max collaborates with LLM agents — GUI not required, but the CLI + manifest format must be clearly documentable in a Claude Code skill / CLAUDE.md.
- **Atomic milestone success:** Both (1) deploy `/10years` content and (2) perform a test mutation to it — neither involving Jenkins or Builder.io.

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| Mono `static-pages` repo (one repo, many pages) over per-page repos | Centralizes deploy tooling; one CI pipeline; easier for Max to navigate alongside LLM agent | — Pending |
| CLI tool + Claude Code skill (not Arda GUI) | Max works with LLMs anyway; CLI is composable, scriptable, LLM-friendly; defers GUI cost | — Pending |
| Arda OAuth (not new auth system) | Reuse existing identity; Arda already manages admin auth in `cloud` repo | — Pending |
| Optional build hook (not pure-static, not mandatory build) | `bigscreen10` is pre-built static; future pages may want a build step; manifest-declared keeps flexibility | — Pending |
| Git is the version of record (no separate S3 version pointers) | Simpler model; rollback = revert + redeploy; matches Max's git mental model | — Pending |
| React SPA keeps routing ownership; gets dynamic registry instead of regex | Preserves site-wide nav/footer wrap; replaces regex anti-pattern; capable of subsuming Builder.io routing later | — Pending |
| `/10years` renders wrapped in nav/footer | Consistent site chrome; treats microsite as a route within bigscreenvr, not a standalone domain | — Pending |
| Both flat (`/10years`) and namespace (`/10years/*`) URLs supported | First target is flat; framework anticipates multi-page microsites | — Pending |

## Open Investigation (Research Phase)

These need answers from `cloud` / `bigstack` / live infra before planning:

- Confirm CloudFront + S3 hosting; locate the distribution + bucket; identify CDN behavior rules.
- Identify which API in `cloud` should own the page registry endpoint (Arda Admin API vs `cloud-api` vs new service).
- Determine how static page content reaches the browser: iframe vs HTML inject vs another mechanism. Iframe is CSS-safe but breaks site-wide nav cohesion; inject shares document but risks CSS collisions.
- Static asset hosting path: under `/<page>/...` on the SPA origin? Or a separate static-pages S3 bucket with CDN behavior carving out specific paths?
- Decide whether a dedicated `site-editor` Arda role is needed or admin role suffices.
- Audit `cloud/website/src` to understand whether the cloud team has existing scaffolding that should inform this design.

## Evolution

This document evolves at phase transitions and milestone boundaries.

**After each phase transition** (via `/gsd-transition`):
1. Requirements invalidated? → Move to Out of Scope with reason
2. Requirements validated? → Move to Validated with phase reference
3. New requirements emerged? → Add to Active
4. Decisions to log? → Add to Key Decisions
5. "What This Is" still accurate? → Update if drifted

**After each milestone** (via `/gsd:complete-milestone`):
1. Full review of all sections
2. Core Value check — still the right priority?
3. Audit Out of Scope — reasons still valid?
4. Update Context with current state

---
*Last updated: 2026-05-21 after initialization*