## Project **Bigscreen Website — Page Setup & Publishing Flow (Milestone v1.0)** 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/` URL via a CLI + Claude Code skill — without Jenkins, without Builder.io, without breaking what's already online.** ### 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. ## Technology Stack ## Languages - JavaScript (ES2015+ / JSX) — React frontend in `src/`, cloud-browser bundler in `cloud-browser-static/` - Sass (`.sass` indented syntax + CSS Modules) — Styles in `src/styles/` and co-located `*.module.sass` - Python 3 — Shopify/Klaviyo admin tooling in `ipynb_shopify/api.py` and `*.ipynb` notebooks - HTML — `public/index.html`, `public/beyondIndex.html`, `cloud-browser-static/src/index.html` ## Runtime - Node.js — minimum 18.17.1 (declared in `cloud-browser-static/README.md`) - Build hint in repo history: "Fixme website build errors in Node 22" - Browser runtime targets defined in `package.json` `browserslist`: - Yarn (classic) — `yarn.lock` present at root and in `cloud-browser-static/` - `.yarnrc.yml`: `nodeLinker: node-modules` - Lockfile: present (root `yarn.lock` ~619 KB, `cloud-browser-static/yarn.lock`) ## Frameworks - `react` ^17.0.1 + `react-dom` ^17.0.1 — UI framework (rendered with legacy `ReactDOM.render` in `src/index.js`) - `react-router` / `react-router-dom` ^6.0.2 — Client-side routing (`` wrapping `` in `src/index.js`) - `react-scripts` 5.0.1 — Create React App tooling (webpack/babel/jest under the hood) - `@builder.io/react` ^3.0.6 + `@builder.io/widgets` ^1.2.24 — Visual CMS rendering most marketing pages via `src/components/BuilderIoPage/index.js` - `sass` ^1.99.0 — Sass compilation through CRA - `@testing-library/react` ^11.1.0 — Component testing (`src/App.test.js`) - `@testing-library/jest-dom` ^5.11.4 — Custom DOM matchers, wired in `src/setupTests.js` - `@testing-library/user-event` ^12.1.10 — User interaction simulation - Jest — Provided transitively by `react-scripts`; invoked via `yarn test` - `react-scripts` 5.0.1 — `start`, `build`, `test`, `eject` scripts (`package.json`) - Babel — `.babelrc` adds `@babel/plugin-proposal-optional-chaining` - `http-proxy-middleware` ^2.0.1 (devDep) — Available for dev proxy - `live-server` ^1.2.2 (devDep) - `watchpack` ^1.7.5 (devDep, version-pinned alongside CRA) - Dev proxy: `package.json` `"proxy": "http://localhost:3001"` forwards API requests during `yarn start` - `esbuild` ^0.21.5 — JS bundling (replaces webpack in `cloud-browser-static/build.js`) - `webpack` ^5.92.1 + `webpack-obfuscator` ^3.5.1 + `terser-webpack-plugin` ^5.3.10 — Legacy / alternative path - `cheerio` ^1.0.0-rc.12 — HTML rewriting in `build.js` - `html-minifier-terser` (referenced) / `html-minifier` ^4.0.0 - `postcss` ^8.4.38 + `postcss-url` ^10.1.3 — CSS asset rewriting - `javascript-obfuscator` ^4.1.1, `uglify-js` ^3.18.0, `terser` ^5.31.1 — Output obfuscation/minification - `nodemon` ^3.1.4 — `yarn watch` rebuild loop ## Key Dependencies - `@stripe/react-stripe-js` ^1.6.0 + `@stripe/stripe-js` 1.21.2 — Card capture / tokenization in `src/screens/Purchase/Payment/CardForm/index.js` - `superagent` ^8.0.9 — HTTP client used throughout `src/api.js` to call Bigscreen APIs - `@hyperbeam/web` ^0.0.37 (devDep) — Cloud browser embedding in `src/screens/SocialBrowser.js` - `lodash` ^4.17.21 — Utility functions, imported pervasively - `react-ga` ^3.3.0 — Google Analytics integration (`ReactGA.initialize('UA-154139246-1')` in `src/App.js` and `src/BeyondApp.js`) - `classnames` ^2.2.6 — `cn(...)` utility used by virtually every component - `react-cookies` ^0.1.1 — Cookie access alongside the custom cookie helpers in `src/api.js` - `date-fns` ^2.29.3 + `date-fns-tz` ^2.0.0 — Date formatting (orders, tickets) - `react-slick` ^0.28.1 — Carousels (Features, Programs, Platforms, etc.) - `react-player` ^2.9.0 — Video embeds (`src/components/VideoEmbed`) - `react-parallax-tilt` ^1.5.23, `react-animate-on-scroll` ^2.1.5 — Visual effects - `react-outside-click-handler` ^1.3.0 — Dropdown / modal dismissal - `react-infinite-scroll-component` ^6.1.0 — Movie library scroll (`src/screens/MovieLibrary`) - `react-countdown` ^2.3.2 — Countdown UI - `body-scroll-lock` ^3.1.5 — Modal/overlay scroll management - `fuse.js` ^6.4.6 — Fuzzy search (Movie search) - `use-dark-mode` ^2.3.1 — Dark mode toggle - `reactcss` ^1.2.3 — Inline style utility - `history` ^5.3.0 — Browser history (`createBrowserHistory` in `src/components/Header/index.js`) - `prop-types` ^15.8.1 — Prop validation - `@npmcli/fs` ^2.1.0 — Listed as a dependency at root (low-level fs helper, atypical for a CRA frontend) - `dependenciesMeta.isolated-vm@4.6.0.built: false` — Yarn metadata suppressing native build of a transitive `isolated-vm` ## Configuration - `.env` file (gitignored) loaded at build-time by CRA; documented in `README.md` step 2 - Required CRA env vars (compiled into bundle, read in `src/config.js` and `src/api.js`): - `cloud-browser-static/src/api/config.js` ships **hardcoded** dev values for `apiServerUrl`, `cloudApiServerUrl`, `apiKey`, `rdcServerHost` - `src/index.js` hardcodes `BUILDER_IO_API_KEY = '64dd5478e25746bf9db3b6c0319905f6'` - `src/screens/Purchase/Payment/CardForm/index.js` hardcodes Stripe publishable keys (`STRIPE_LIVE_PUBLIC_KEY`, `STRIPE_TEST_PUBLIC_KEY`), selected at runtime by `window.location.hostname` - `src/App.js` and `src/BeyondApp.js` hardcode `ReactGA.initialize('UA-154139246-1')` - `public/index.html` embeds Reddit Pixel, Twitter conversion pixel (`twq('config','ond1m')`), Meta Pixel (`fbq('init','9362178413841771')`), Google AdSense (`ca-pub-1838810760934258`) - `package.json` — root build config (CRA scripts, ESLint preset `react-app`, browserslist) - `.babelrc` — `@babel/plugin-proposal-optional-chaining` - `cloud-browser-static/build.js` — custom esbuild + cheerio inliner producing a single self-contained HTML - `cloud-browser-static/package.json` — nodemon watch config (`src/`, ext `js,html,css`) - `.gitignore` — excludes `node_modules`, `build/`, `.env*`, `cloud-browser-static/dist`, `cloud-browser-static/node_modules` - `.gitattributes` — present - `start` script in `README.md` uses `SKIP_PREFLIGHT_CHECK=true yarn start` to bypass CRA dep checks ## Platform Requirements - Node 18.17.1 or newer (see `cloud-browser-static/README.md`); known build issue on Node 22 referenced in recent commit - Yarn classic - Local `.env` file copied from `Server_Keys/local/webapps/website` per `README.md` - Dev server at `http://localhost:3000`, API proxy expected at `http://localhost:3001` - Python 3 + `dotenv`, `requests`, `ShopifyAPI` (per inline `%pip install` cells) for the Shopify notebooks - Hosting target: serves CRA static build (`build/` artifact via `react-scripts build`) - `cloud-browser-static` `dist/` is intended for upload to an S3 bucket fronted by CloudFront (per `cloud-browser-static/README.md`) - No CI configuration files (`.github/workflows`, `.circleci`, etc.) detected in repo ## Conventions ## Naming Patterns - React components live in named folders with an `index.js` (PascalCase folder name). Example: `src/components/Header/index.js`, `src/components/Card/index.js`, `src/screens/Home/index.js`. - Component-local stylesheets co-locate with the component as `ComponentName.module.sass` (PascalCase). Example: `src/components/Header/Header.module.sass`. - Standalone single-file components and pages use PascalCase `.js` (no folder). Examples: `src/components/Icon.js`, `src/components/Image.js`, `src/components/ScrollParallax.js`, `src/scans/ScanStartPage.js`, `src/bigOrders/BigOrders.js`. - Utility modules use lowercase, single-word filenames in `src/utils/`. Examples: `src/utils/formatters.js`, `src/utils/errorget.js`, `src/utils/countryformat.js`, `src/utils/languagecodeformat.js`. - Mock data and trainers use lowercase. Example: `src/mocks/trainers.js`. - Top-level app entry files use PascalCase: `src/App.js`, `src/BeyondApp.js`. Lowercase entry/config files: `src/index.js`, `src/api.js`, `src/config.js`. - Test files use `.test.js` suffix and live next to the file they test (Create React App default). Example: `src/App.test.js`. - camelCase for regular functions and arrow functions. Examples: `getAccount`, `fetchRdcUrl`, `onLogout`, `loadBigOrders`, `safariCheck`, `iosCheck`. - Event handlers prefix with `on`: `onLogout`, `onChangeIpd`, `onRescan`, `onCancel`. - Async setup functions inside `useEffect` are typically named `load*` or `fetch*`: `loadScans`, `loadBigOrders`, `fetchRdcUrl`. - camelCase for locals, props and `useState` pairs: `const [account, setAccount] = useState()`, `const [visibleNav, setVisibleNav] = useState(false)`, `const [loginBtnText, setLoginBtnText] = useState('Login')`. - React state setters always prefixed with `set`: `setScans`, `setBigOrders`, `setLoading`, `setRdcUrl`. - Refs use camelCase ending in `Ref` or descriptive nouns: `rootEl`, `retryTag`. - Constants at module scope use camelCase (not SCREAMING_SNAKE_CASE) in most files. Examples: `navLinks`, `socials`, `formatters`, `downloads` in `src/components/Header/index.js` and `src/screens/Home/Hero/index.js`. - A few class-level constants in `src/api.js` use SCREAMING_SNAKE_CASE: `REFRESH_TOKEN_KEY`, `ACCESS_TOKEN_KEY`, `USE_COOKIES_FOR_TOKENS`. - React components are PascalCase function components: `Header`, `Page`, `Hero`, `BigOrders`, `ScanStartPage`, `Redirect`. - Classes use PascalCase: `BigApi`, `BigApiError`. - Enum-like objects use PascalCase keys: `AuthenticationErrorCode.RefreshTokenNeedsRenewal`, `BigApiAuthenticationGuard.AuthenticationRequired` (`src/api.js`). - All env reads are prefixed `REACT_APP_` (CRA convention): `REACT_APP_API_SERVER_URL`, `REACT_APP_CLOUD_API_URL`, `REACT_APP_API_KEY`, `REACT_APP_RDC_SERVER_HOST` (`src/config.js`, `src/api.js`). ## Code Style - No Prettier config and no `.editorconfig` detected. Formatting is by convention, not enforced. - Indentation is mixed: 2 spaces is dominant in component files (`src/components/Header/index.js`, `src/App.js`), but 4 spaces appears in `src/api.js`, `src/bigOrders/BigOrders.js`, `src/scans/ScanStartPage.js`, and the `src/utils/*.js` helpers. Match the surrounding file's indentation when editing. - Quotes are mixed within and across files; double quotes are most common for JSX attributes and JS string literals, but single quotes appear frequently for short literals (`'login'`, `'/'`, `'classnames'`). No enforcement; do not reformat existing strings. - Trailing semicolons are generally used. JSX attributes use double quotes. - ESLint is configured via `package.json` `eslintConfig` only, extending `react-app` and `react-app/jest` (the Create React App defaults). No custom rules. - No `.eslintrc.*`, `.prettierrc.*`, `biome.json`, or standalone `eslint.config.*` file. - `.babelrc` adds only `@babel/plugin-proposal-optional-chaining`. Everything else is CRA defaults via `react-scripts@5.0.1`. - The application source is primarily ES modules: `import` / `export default` / `export class` (used throughout `src/components`, `src/screens`, `src/App.js`, `src/api.js`). - Utility modules in `src/utils/` use CommonJS-style `exports.foo = ...` (e.g., `src/utils/formatters.js`, `src/utils/errorget.js`, `src/utils/countryformat.js`). New utilities should follow this same `exports.fnName = ...` pattern to stay consistent with the existing files, OR migrate the whole `utils/` tree at once. ## Import Organization - All internal imports use **relative paths** (`./`, `../`, `../../`). No path aliases (`@/`, `~/`) are configured; CRA's `jsconfig.json` / `tsconfig.json` is not present. - The `.js` extension is sometimes included (`../api.js`, `./api.js`, `./SocialBrowser.js`, `./screens/Api/ApiPages.js`) and sometimes omitted (`"../Overlay"`, `"./Header"`). Either works; prefer omitting for component folders that have an `index.js`. - `import cn from "classnames"` — used everywhere for conditional className composition. - `import * as _ from "lodash"` — used in `src/api.js`, `src/components/BuilderIoPage/index.js`, `src/bigOrders/BigOrders.js`. - `import * as superagent from "superagent"` in `src/api.js`. ## Error Handling - All HTTP methods are wrapped in `try` / `catch`. Errors are converted with `BigApiError.getApiError(err, defaultMessage)` and re-thrown so callers see a `BigApiError` with `code`, `status`, `errors`, and `message` populated from `err.response.body`. - `BigApiError` extends `Error` and carries structured fields (`code`, `status`, `errors`). Use it for all API failures. - Some auth helpers swallow errors and return `null`/`false` (`fetchLocalAccountProfile`, `isAuthenticated`, `logout`) — by design, so the UI can degrade to logged-out state. - On failure, set the local state to an empty/undefined value and log to console. There is no global toast / error-boundary system. - `src/utils/errorget.js` exports `superagentError(error, response, defaultMsg)` for extracting human-readable messages from superagent failure bodies. Use it when surfacing errors to users. - Re-throw raw superagent errors at the UI layer. Always funnel through `BigApi.*` (which wraps with `BigApiError`) or `superagentError(...)`. - Throw error strings inside callers (`throw "..."`). Throw `BigApiError` or `Error` instances. ## Logging - `console.log(...)` is used liberally for debugging during async flows and to dump response bodies — e.g. `console.log("Setting account to: ", res.body)` (`src/App.js:99`), `console.log(res.body)` (`src/bigOrders/BigOrders.js:23,38`). - `console.error(e)` for caught exceptions in component effects (e.g., `src/App.js:102`, `src/components/Header/index.js:119`). - `console.warn(...)` for missing-token soft failures in `src/api.js` (`fetchLocalAccountProfile`, `isAuthenticated`). - `// console.log('...'); //debug` style commented-out debug lines are common — keep them when editing nearby code, do not delete on sight. ## Comments - Section dividers in routing/rendering blocks use `//--- LABEL ---//` style (`src/App.js`). - Multi-line block comments explain WHY for non-obvious workarounds, often with `HACK HACK HACK` headers — see `src/api.js:245-256` (Safari token caching) and `// HACK` notes in `BigApi.loginWithToken2`. - `TODO` and `FIXME` markers appear as single-line `//` comments. Examples: `src/App.js:274 (// TODO)`, `src/api.js:125 (TODO: handle different browser storage mechanisms)`, `src/api.js:251 (TODO: the token2 login MUST BE READONLY.)`. - Large blocks of commented-out imports/routes are intentionally preserved (see top of `src/App.js`) — they document deferred features. Do not remove them as cleanup. - Used sparingly. `src/api.js` has occasional JSDoc-lite blocks (file header at line 4-8, `loginWithToken2` at line 219-223). No project-wide JSDoc policy. - `src/api.js:4-8` warns: "don't edit the .js version of this file directly. Edit the .ts version and then run `tsc` to generate the .js version" — **the `.ts` source for `api.js` is not in the repo**. Treat the file as hand-maintained until a `.ts` source appears. ## Function Design - All components are function components using hooks (`useState`, `useEffect`, `useRef`, `useNavigate`, `useParams`, `useSearchParams`, `useLocation`). No class components. - Props are destructured in the signature: `const Header = ({ account }) => { ... }`, `const Page = ({ showInfoState, account, children }) => { ... }`. - State that needs to be passed down as a tuple uses the "state pair" pattern: `const showInfoState = useState();` then `` and inside the child `const [showInfo, setShowInfo] = showInfoState;` (`src/App.js:89-90`, `src/screens/Home/Hero/index.js:14-15`). - Async effect work is wrapped in a named inner function and immediately invoked: - `prop-types` is in `package.json` dependencies but **no component declares `PropTypes`**. Prop validation is not enforced. Do not add PropTypes to existing components unless you're prepared to add them everywhere. ## Module Design - Components use `export default Component` at the bottom of the file. - API code uses named exports for classes/enums (`export class BigApi`, `export class BigApiError`, `export var BigApiAuthenticationGuard`) and a default export for config (`export default CloudConfig` in `src/config.js`). - Utility modules use CommonJS `exports.fnName = ...` (see `src/utils/formatters.js`, `src/utils/errorget.js`, `src/utils/countryformat.js`). - `src/screens/Api/ApiPages.js` is imported as a namespace: `import * as ApiPages from './screens/Api/ApiPages.js'`, then ``. Use this pattern when you want to group several small page components under one file. - Each component folder has an `index.js` that exports the component as default. Imports rely on the folder name (`import Header from "../Header"`). Do not put multiple unrelated components in one `index.js`. - `*.module.sass` for component-scoped CSS Modules, imported as `import styles from "./Component.module.sass"` and applied via `className={styles.foo}` or `cn(styles.foo, "global-class")`. - Global styles are imported once from `src/components/Page/index.js` via `import "../../styles/app.sass"`. Builder.io and Standalone layouts intentionally skip this import. - Shared/global SASS lives in `src/styles/` (`app.sass`, `common.sass`, `helpers.sass`, `reset.sass`, and `src/styles/blocks/`). - All `.module.sass` files start with `@import ../../styles/helpers` (or deeper `../../../styles/helpers` from `src/screens/*/Subcomponent/`). ## React Conventions - React Router v6 is used throughout (`Routes` / `Route` / `useNavigate` / `useSearchParams` / `useParams` / `useLocation`). `Route` uses `element={...}` not `component={...}`. Some legacy `exact` props remain (no-op in v6) — keep them on existing routes to match style; new routes can omit `exact`. - `classnames` is always imported as `cn`. Conditional classes: `cn(styles.foo, { [styles.active]: isActive })`. - Inline event handlers in JSX are common (`onClick={() => setX(!x)}`). Extract to named functions when they do more than one thing. - Strict Mode is enabled at the root (`src/index.js`). ## Architecture ## System Overview ```text ``` ## Component Responsibilities | Component | Responsibility | File | |-----------|----------------|------| | Entry bootstrap | Initialize Builder.io key, mount `` inside `` | `src/index.js` | | Path dispatcher | Evaluate regex filters and pick one of six layout branches | `src/App.js` | | API client | All HTTP I/O, token cookies, access-token renewal, error wrapping | `src/api.js` | | Config | Bind `REACT_APP_*` env vars to a single config object | `src/config.js` | | React layout | Renders Header + children + Footer for "marketing/react" branch | `src/components/Page/index.js` | | Builder layout | Locale fetch + scroll reset for Builder.io branch | `src/components/BeyondBackend/index.js` | | Builder renderer | Maps URL path to a Builder.io model + injects API helpers | `src/components/BuilderIoPage/index.js` | | Standalone layout | Minimal header (logo only) for scan/et-client flows | `src/components/Standalone/index.js` | | BigOrder layout | Minimal header for `/account/order/*` and token2 login | `src/bigOrders/BigOrderLayout.js` | | Marketing screens | Section composition for `/software` home page | `src/screens/Home/*` | | Auth screens | Login / signup / forgot / reset / verify modes | `src/screens/Access/*` | | API-token screens | Token-based redirect handlers (email verify, reset, login) | `src/screens/Api/ApiPages.js` | | Long copy constants | Embedded ToS / Privacy / Ticket HTML strings | `src/long_constants/*.js` | | Beyond Cloud Browser | Separate hyperbeam-based bundle, built independently | `cloud-browser-static/src/*` | | Shopify ops notebooks | Out-of-band Jupyter scripts for checkout + Klaviyo | `ipynb_shopify/*` | ## Pattern Overview - Single shared HTTP client (`BigApi` static class) used by every screen - No global state library (no Redux/Zustand/Context) — `account` is fetched once in `App.js` and prop-drilled - Layout selection is URL-pattern based, not nested-route based; only one `` block renders at a time - Builder.io CMS owns most marketing pages; React owns auth, purchase, scans, big orders, account, and remote-desktop - Styling is SASS modules per component (`*.module.sass`) plus global SASS partials under `src/styles/` ## Layers - Purpose: Mount React into DOM, configure third-party SDKs - Location: `src/index.js`, `public/index.html` - Contains: ReactDOM render call, Builder.io `init`, marketing pixels (Reddit, Twitter, Meta, AdSense), dark-mode pre-paint script - Depends on: `App`, `react-router-dom`, `@builder.io/react` - Used by: Browser - Purpose: Decide which layout + `` block to render for the current pathname - Location: `src/App.js` (production), `src/BeyondApp.js` (alternate/unused entry) - Contains: `getComposedRegex`, six filter regexes, conditional returns - Depends on: All layout components, all top-level screens, `BigApi` - Used by: Bootstrap layer - Purpose: Provide chrome (header/footer/styles) appropriate to each branch - Location: `src/components/Page/`, `src/components/BeyondBackend/`, `src/components/Standalone/`, `src/bigOrders/BigOrderLayout.js` - Contains: Layout wrappers that inject CSS, set `body.style`, call `clearAllBodyScrollLocks` - Depends on: `body-scroll-lock`, Header/Footer components, `BigApi` (for locale) - Used by: Dispatcher - Purpose: Top-level routable pages - Location: `src/screens/*`, `src/scans/*`, `src/bigOrders/*` - Contains: Page-level components that orchestrate sub-components and API calls - Depends on: Component layer, `BigApi`, `src/utils/*` - Used by: Layout - Purpose: Reusable UI building blocks - Location: `src/components/*` - Contains: Header, Footer, Modal, Overlay, Card, VideoOverlay, Icon, SimpleLoader, etc. - Depends on: SASS modules, `classnames`, third-party UI libs (react-slick, react-player, react-parallax-tilt) - Used by: Screens and other components - Purpose: Encapsulate all HTTP, token management, and error normalization - Location: `src/api.js`, `src/config.js` - Contains: `BigApi` static class, `BigApiError`, `BigApiAuthenticationGuard` enum - Depends on: `superagent`, `lodash`, `process.env.REACT_APP_*` - Used by: Every screen and most layout components - Purpose: Global SASS and per-component SASS modules - Location: `src/styles/`, `src/components/**/*.module.sass`, `public/css/` - Contains: Reset, helpers, common, blocks (button/title/section/etc.), plus `public/css/beyond-*.css` for Builder.io / standalone branches - Used by: All visual components ## Data Flow ### Primary Request Path (marketing page render) ### Authentication Path (token login v2) ### Authenticated API Call Path - No global store. Per-component `useState` and prop-drilling. - `account` is fetched in `App.js` and passed down to every branch. - `localeState` is also a `useState` tuple created in `App.js` and passed into `BeyondBackend` and `BuilderIoPage`. - Tokens persist in cookies (default) via `BigApi.setCookie` / `getCookie`; `BigApi.USE_COOKIES_FOR_TOKENS = true` toggles between cookie and localStorage backends (`src/api.js:100-164`). - Dark mode is bootstrapped from `localStorage.darkMode` by an inline script in `public/index.html` (`public/index.html:90-131`); `use-dark-mode` hook is available but not heavily used. ## Key Abstractions - Purpose: Single facade for all backend HTTP, token lifecycle, and error normalization - Examples: `src/api.js:71-540` - Pattern: Static methods on a class; configuration loaded from `process.env` at class definition time; auth guarded by `BigApiAuthenticationGuard` enum (`SkipAuthentication` / `AuthenticationOptional` / `AuthenticationRequired`) - Purpose: Carry HTTP `status`, error `code`, and `errors[]` array alongside the message - Examples: `src/api.js:29-70` - Pattern: Static `getApiError(err, defaultMessage)` factory converts superagent errors into `BigApiError` instances - Purpose: Provide branch-specific chrome and side effects (`window.scrollTo`, `clearAllBodyScrollLocks`) - Examples: `src/components/Page/index.js`, `src/components/Standalone/index.js`, `src/bigOrders/BigOrderLayout.js`, `src/components/BeyondBackend/index.js` - Pattern: Receive `children` plus shared props (`account`, `localeState`); wrap with header/CSS links - Purpose: Compose multiple URL regexes into a single dispatch test - Examples: `src/App.js:114-160`, `src/components/BuilderIoPage/index.js:15-29` - Pattern: `getComposedRegex(...regexes) => new RegExp(regexes.map(r => r.source).join("|"))` - Purpose: Locally scoped class names - Examples: every `src/components//.module.sass`, every `src/screens//.module.sass` - Pattern: `import styles from "./Name.module.sass";
` ## Entry Points - Location: `src/index.js` - Triggers: `react-scripts start` / `react-scripts build` resolves it as the CRA entry - Responsibilities: Initialize Builder.io API key, wrap `App` in ``, mount into `#root` - Location: `src/BeyondApp.js` - Triggers: Not currently referenced by `src/index.js`; appears to be a stripped-down Builder.io-only variant - Responsibilities: Same as `App` but only renders the Builder.io branch - Note: Imports `./src/api.js` (broken path — would not resolve) - Location: `cloud-browser-static/src/browser.js`, built via `cloud-browser-static/build.js` - Triggers: `yarn build` inside `cloud-browser-static/` - Responsibilities: Standalone hyperbeam-powered cloud browser; output is consumed by the main app at `/browser/:activityId` route - Location: `ipynb_shopify/api.py`, `ipynb_shopify/*.ipynb` - Triggers: Manual Jupyter execution - Responsibilities: Out-of-band Shopify checkout customization + Klaviyo function deployment; not part of the web build ## Architectural Constraints - **Threading:** Single-threaded browser JS; no web workers used. - **Global state:** `BigApi` is a static class — its `config` and token cookies are process-wide singletons. `builder.init(BUILDER_IO_API_KEY)` is called once at module load in `src/index.js`. `ReactGA.initialize('UA-154139246-1')` is called at module load in `src/App.js` and `src/BeyondApp.js`. - **Hardcoded keys:** `BUILDER_IO_API_KEY` (`src/index.js:8`), `ReactGA` UA ID (`src/App.js:61`), Builder.io API key, Meta Pixel ID, Twitter pixel, Reddit pixel, AdSense client ID (all in `public/index.html`) are committed in source. Backend API key is env-var driven (`REACT_APP_API_KEY`). - **Dev proxy:** `package.json:41` sets `"proxy": "http://localhost:3001"` for CRA dev server. - **Node compatibility:** README + commit `7f83139 "Fixme website build errors in Node 22"` indicate Node 22 fixes; CRA 5.0.1 in use. `SKIP_PREFLIGHT_CHECK=true` required by the dev start command. - **No TypeScript build:** `src/api.js` is hand-edited but the comment at line 7 says "don't edit the .js version directly. Edit the .ts version and then run `tsc`" — no `.ts` source is present in the repo, so this instruction is stale. - **Circular imports:** None observed at a glance. `App.js` imports leaf screens; screens import `api.js`; no screen imports `App.js`. - **Strict mode:** `` is enabled (`src/index.js:14`). - **Router version mismatch risk:** Uses `react-router-dom@^6.0.2` but mixes `exact path=` (a v5 prop that v6 ignores). All routes still match correctly because v6 matches exactly by default, but the `exact` prop is dead code. ## Anti-Patterns ### Hard-coded Builder.io API key ### Path-regex dispatcher returns different `` blocks ### `BigApi` as a static class ### Dead-code comments at scale ### Inline alternate entry `src/BeyondApp.js` ### Builder.io filter list duplicates routing knowledge ## Error Handling - `try/catch` around every `BigApi.*` call in screens - `e instanceof BigApiError` check to switch on `e.errors[0].msg` vs `e.message` (`src/screens/Api/ApiPages.js:81-90`) - `console.error(e)` as default fallback; many screens swallow errors silently - HTTP 401 with `AccessTokenNeedsRenewal` code triggers automatic `renewAccessToken` via nonce header (`src/api.js:348-360`) ## Cross-Cutting Concerns ## Project Skills No project skills found. Add skills to any of: `.claude/skills/`, `.agents/skills/`, `.cursor/skills/`, `.github/skills/`, or `.codex/skills/` with a `SKILL.md` index file. ## GSD Workflow Enforcement Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync. Use these entry points: - `/gsd-quick` for small fixes, doc updates, and ad-hoc tasks - `/gsd-debug` for investigation and bug fixing - `/gsd-execute-phase` for planned phase work Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it. ## Developer Profile > Profile not yet configured. Run `/gsd-profile-user` to generate your developer profile. > This section is managed by `generate-claude-profile` -- do not edit manually.