# Codebase Structure

**Analysis Date:** 2026-05-21

## Directory Layout

```
website/
├── .babelrc                       # Single Babel plugin: optional-chaining
├── .gitignore                     # Standard CRA + .env + .yarn + cloud-browser dist
├── .yarnrc.yml                    # Yarn config (Berry)
├── README.md                      # Build/start instructions (mentions Server_Keys/.env)
├── package.json                   # CRA 5.0.1, React 17, react-router 6, Builder.io, Stripe
├── yarn.lock                      # Yarn lockfile (~620KB)
│
├── public/                        # CRA static assets, served at site root
│   ├── index.html                 # SPA shell, third-party pixels, dark-mode pre-paint
│   ├── beyondIndex.html           # Alternate HTML shell (used by Beyond branch?)
│   ├── site.webmanifest           # PWA manifest
│   ├── robots.txt
│   ├── favicon.ico, favicon_OLD.ico, *.png  # Icons
│   ├── css/                       # Pre-built CSS consumed by Builder.io / Standalone branches
│   │   ├── beyond-react.css
│   │   ├── beyond-copy.css
│   │   ├── fonts.css
│   │   └── fonts/                 # Web fonts (brand-icons, outline-icons, etc.)
│   ├── fonts/                     # Walsheim, FontAwesome, SFProDisplay, Haas Grotesk
│   └── images/                    # Logos, backdrops, marketing imagery
│
├── src/                           # React application source
│   ├── index.js                   # ReactDOM.render entry
│   ├── App.js                     # Path-regex dispatcher (production root)
│   ├── BeyondApp.js               # Unused alternate root
│   ├── App.test.js                # Single stub test (failing — looks for "learn react")
│   ├── setupTests.js              # Imports @testing-library/jest-dom
│   ├── api.js                     # BigApi static client (compiled from absent .ts)
│   ├── config.js                  # Maps REACT_APP_* env vars to CloudConfig object
│   │
│   ├── components/                # Reusable UI components (one folder per component)
│   │   ├── Page/                  # Marketing layout (Header + children + Footer)
│   │   ├── BeyondBackend/         # Locale-fetching wrapper for Builder.io branch
│   │   ├── BuilderIoPage/         # Builder.io <BuilderComponent> renderer
│   │   ├── Standalone/            # Minimal-chrome layout (scans, et-client)
│   │   ├── Header/                # Top navigation + dropdown menu
│   │   ├── Footer/                # Site footer + legal overlays
│   │   ├── Modal/, Overlay/, SimpleLoader/, VideoOverlay/, VideoEmbed/
│   │   ├── Card/, CardScroller/, ProductPoster/, RoomCard/
│   │   ├── Icon.js                # Single-file icon component (~21KB, no folder)
│   │   ├── Image.js               # Single-file image wrapper
│   │   ├── ScrollParallax.js      # Single-file scroll-effect helper
│   │   └── (Advantages, Community, Dropdown, Features, HowTo, Intro, ModalTrainer,
│   │        Platforms, Programs, Review, ScrollButton, Search, Subscription,
│   │        Testimonials, Theme, ValueProps, Workouts)/
│   │
│   ├── screens/                   # Top-level routable pages
│   │   ├── Home/                  # `/software` — Hero, Coworking, Beyond, Features,
│   │   │                          #  Gaming, Social, Rooms (+ disabled About, Team, Quality)
│   │   ├── Access/                # `/account/login|signup|forgot|reset` + Login/SignUp/Forgot/Reset/VerifyEmail/FailedToken/EtClient subfolders
│   │   ├── Account/               # `/account/home` + AccountHeader, Ticket
│   │   ├── Api/                   # ApiPages.js: token-redirect handlers (EmailVerifier, EmailUpdater, TokenLogin, TokenLogin2, ResetPasswordToken, PurchaseToken, RedirectForgot)
│   │   ├── Purchase/              # `/purchase/:bigMediaId/:url` + Details/Payment/Help/Perks
│   │   ├── Desktop/               # `/remotedesktop` + DesktopHeader, LibraryCloser
│   │   ├── OutcomeReport/         # Generic success/failure splash (email_verify*, email_update*)
│   │   ├── InfoPage/              # Privacy/ToS/Ticket info page (currently disabled in App.js)
│   │   ├── SocialBrowser.js       # `/browser/:activityId` — single-file
│   │   ├── Article/, Class01/, Class01Details/, Class02/, Class02Details/,
│   │   │   Download/, Features/, Lifestyle/, MovieLibrary/, Pricing/  # Built but not routed
│   │   └── styles.sass            # (within Api/ only)
│   │
│   ├── scans/                     # `/scans*`, `/scan/:tpy_token/process`
│   │   ├── ScanStartPage.js
│   │   ├── ScanProcessingPage.js
│   │   └── Scans.module.sass
│   │
│   ├── bigOrders/                 # `/account/order/*`, `/account/orders`, `/token2/login/:token`
│   │   ├── BigOrderLayout.js
│   │   ├── BigOrders.js
│   │   ├── BigOrderInfoPage.js
│   │   ├── BigOrderSetIpdPage.js
│   │   ├── BigOrderLineItem.js    # Empty file (0 bytes)
│   │   └── BigOrders.module.sass
│   │
│   ├── utils/                     # Pure helpers
│   │   ├── countryformat.js
│   │   ├── errorget.js            # superagentError extractor
│   │   ├── formatters.js          # Intl.NumberFormat per currency
│   │   └── languagecodeformat.js
│   │
│   ├── mocks/
│   │   └── trainers.js            # Static trainer data
│   │
│   ├── long_constants/            # Multi-thousand-line legal copy
│   │   ├── PrivacyPolicy.js       # ~21KB string
│   │   ├── TermsOfService.js      # ~33KB string
│   │   └── TicketPolicy.js        # ~8KB string
│   │
│   ├── styles/                    # Global SASS
│   │   ├── app.sass               # Top-level @imports
│   │   ├── reset.sass, helpers.sass, common.sass
│   │   └── blocks/                # section, container, button, title, stage, play,
│   │                              #  slick, status, animations, navfade
│   │
│   ├── fonts/                     # Font files imported from JS/SASS
│   └── images/                    # Imagery imported from JS (avatars, backdrops, logos)
│
├── cloud-browser-static/          # Separate webpack/esbuild bundle for /browser route
│   ├── build.js
│   ├── package.json               # Own dependencies (hyperbeam, webpack, esbuild, terser)
│   ├── src/
│   │   ├── browser.js
│   │   ├── index.html
│   │   └── api/
│   │       ├── api.js
│   │       └── config.js
│   ├── yarn.lock
│   └── README.md
│
└── ipynb_shopify/                 # Out-of-band Shopify/Klaviyo scripts
    ├── 001.checkoutCustomization.ipynb
    ├── 002.klaviyoFunctions.ipynb
    └── api.py
```

## Directory Purposes

**`public/`:**
- Purpose: CRA static-asset root; copied verbatim into `build/` and served at URL root
- Contains: `index.html` SPA shell, manifest, robots, favicons, fonts, images, pre-built CSS
- Key files: `public/index.html`, `public/site.webmanifest`, `public/css/beyond-react.css`

**`src/`:**
- Purpose: Application source compiled by `react-scripts`
- Contains: Entry, root component, components, screens, helpers, styles
- Key files: `src/index.js`, `src/App.js`, `src/api.js`, `src/config.js`

**`src/components/`:**
- Purpose: Reusable UI building blocks
- Contains: One folder per component, each with `index.js` and `<Name>.module.sass`
- Key files: `src/components/Page/index.js`, `src/components/Header/index.js`, `src/components/Footer/index.js`, `src/components/Icon.js`

**`src/screens/`:**
- Purpose: Top-level routable pages and their child sections
- Contains: One folder per screen; complex screens have sub-folders (e.g. `Home/Hero/`, `Purchase/Payment/CardForm/`)
- Key files: `src/screens/Home/index.js`, `src/screens/Access/index.js`, `src/screens/Api/ApiPages.js`, `src/screens/Purchase/index.js`

**`src/scans/`:**
- Purpose: Standalone Beyond-headset scan flow (separate top-level folder rather than under `screens/` because it ships with its own layout branch)
- Contains: 2 page components + 1 SASS file
- Key files: `src/scans/ScanStartPage.js`, `src/scans/ScanProcessingPage.js`

**`src/bigOrders/`:**
- Purpose: Token2-login + bulk-order management flow (sibling to `scans/`)
- Contains: 4 page components + layout + SASS
- Key files: `src/bigOrders/BigOrderLayout.js`, `src/bigOrders/BigOrders.js`

**`src/utils/`:**
- Purpose: Pure helper functions (no React, no I/O)
- Contains: Currency, country, language-code formatters; superagent error extractor
- Key files: `src/utils/formatters.js`, `src/utils/errorget.js`

**`src/long_constants/`:**
- Purpose: Massive HTML/JSX string literals for legal copy (privacy, ToS, ticket policy)
- Contains: 3 `.js` files that `export default` a long JSX/HTML string
- Generated: No
- Committed: Yes

**`src/styles/`:**
- Purpose: Global SASS — reset, helpers, common, and reusable "block" styles
- Contains: 4 root partials + 10 block partials in `blocks/`
- Key files: `src/styles/app.sass` (the import roll-up)

**`src/mocks/`:**
- Purpose: Static seed data for components when API is unavailable
- Contains: `trainers.js` only

**`cloud-browser-static/`:**
- Purpose: Independent build that produces the Beyond cloud-browser bundle consumed at `/browser/:activityId`
- Contains: Own `package.json`, own webpack/esbuild config (`build.js`), own `src/`
- Generated: `dist/` is gitignored
- Committed: Source yes, output no

**`ipynb_shopify/`:**
- Purpose: Operational Jupyter notebooks for Shopify checkout customization and Klaviyo Functions
- Contains: 2 notebooks + 1 Python helper
- Generated: No
- Committed: Yes (not part of website build)

**`.claude/`:**
- Purpose: Claude Code session metadata
- Contains: `LIVE_AGENT_IDS.json`
- Generated: Yes
- Committed: No (untracked per `git status`)

**`.planning/codebase/`:**
- Purpose: GSD codebase-map output
- Contains: `ARCHITECTURE.md`, `STRUCTURE.md` (this file)
- Generated: Yes (by `/gsd:map-codebase`)

## Key File Locations

**Entry Points:**
- `src/index.js`: ReactDOM mount, Builder.io init, `<BrowserRouter>` setup
- `public/index.html`: HTML shell + marketing pixels + dark-mode pre-paint
- `src/App.js`: Path-regex dispatcher (real app root)
- `src/BeyondApp.js`: Unused alternate root — do not edit, do not extend; flag for removal
- `cloud-browser-static/build.js`: Build entry for cloud-browser bundle

**Configuration:**
- `package.json`: Dependencies, `proxy` setting, browserslist, eslintConfig (extends `react-app`)
- `src/config.js`: Maps `REACT_APP_API_SERVER_URL`, `REACT_APP_CLOUD_API_URL`, `REACT_APP_API_KEY`, `REACT_APP_RDC_SERVER_HOST` env vars
- `.babelrc`: One plugin (`@babel/plugin-proposal-optional-chaining`)
- `.yarnrc.yml`: Yarn Berry config
- `.gitignore`: Standard CRA + `.env` + `.yarn` + `cloud-browser-static/dist`
- `.env` (not committed): Source of `REACT_APP_*` values per README

**Core Logic:**
- `src/api.js`: `BigApi`, `BigApiError`, `BigApiAuthenticationGuard` — every HTTP call
- `src/App.js`: All top-level routing + layout selection
- `src/components/BuilderIoPage/index.js`: All Builder.io integration logic

**Testing:**
- `src/App.test.js`: Single sample test (looks for "learn react" text — currently broken)
- `src/setupTests.js`: Imports `@testing-library/jest-dom`
- No other test files exist in `src/`.

**Build / Run:**
- `package.json` scripts: `yarn start` / `yarn build` / `yarn test` / `yarn eject` (all delegate to `react-scripts`)
- README requires `SKIP_PREFLIGHT_CHECK=true yarn start` for dev

## Naming Conventions

**Files:**
- React component file: `index.js` inside a `PascalCase/` folder. Example: `src/components/Header/index.js`.
- Single-file React components: `PascalCase.js` directly in `components/`. Example: `src/components/Icon.js`, `src/components/Image.js`, `src/components/ScrollParallax.js`.
- Non-component modules: `camelCase.js`. Example: `src/utils/formatters.js`, `src/utils/errorget.js`.
- SASS modules: `PascalCase.module.sass` co-located with the component. Example: `src/components/Page/Page.module.sass`.
- Shared SASS partials: `lowercase.sass` under `src/styles/`. Example: `src/styles/helpers.sass`.
- Tests: `Name.test.js` co-located. Example: `src/App.test.js`.

**Directories:**
- Component / screen folders: `PascalCase`. Example: `src/screens/MovieLibrary/`, `src/components/VideoOverlay/`.
- Top-level domain folders: `camelCase`. Example: `src/bigOrders/`, `src/long_constants/` (the latter is `snake_case`, an outlier).
- Multi-level component composition uses nested PascalCase folders. Example: `src/screens/Purchase/Payment/CardForm/`.

**React components:**
- `PascalCase` function components, default exported.
- Hooks consumed: `useState`, `useEffect`, `useNavigate`, `useParams`, `useLocation`, `useSearchParams`.
- Props destructured in the function signature: `const Foo = ({ account, children }) => { ... }`.

**API / classes:**
- Static client class is `BigApi`; methods are `camelCase`. Enums are `PascalCase` (e.g. `BigApiAuthenticationGuard`).
- Error subclass is `BigApiError`.

## Where to Add New Code

**New marketing page (rendered by Builder.io):**
- Add the URL pattern to the `builderIoFilter` regex array in `src/App.js:115-137`.
- Add the page content inside Builder.io (CMS), not in this repo.

**New React-owned page:**
1. Create `src/screens/<Name>/index.js` and `src/screens/<Name>/<Name>.module.sass`.
2. Import in `src/App.js` near the other screen imports.
3. Add a `<Route>` inside the appropriate branch (almost always the final `<Page>` branch — `src/App.js:252-321`).
4. If the page belongs in a different layout, add a regex to the corresponding filter (`scanFilter`, `orderFilter`, `etClientFilter`, etc.) and add the `<Route>` in that branch's `<Routes>`.

**New section/feature inside the home page:**
- Add as a subfolder of `src/screens/Home/<Name>/` with `index.js` + `<Name>.module.sass`.
- Import and place in `src/screens/Home/index.js`.

**New reusable component:**
- Create `src/components/<Name>/index.js` and `src/components/<Name>/<Name>.module.sass`.
- Trivial helpers without styling may be a single `src/components/<Name>.js` (mirror `Icon.js`, `Image.js`).

**New API call:**
- Add a static method to `BigApi` in `src/api.js`.
- Use `await BigApi.checkAccessTokenStatus()` before authenticated requests.
- Always wrap superagent errors with `throw BigApiError.getApiError(err)`.
- Add the corresponding `REACT_APP_*` env var to `src/config.js` if a new host is involved.

**New utility / pure helper:**
- Add to `src/utils/<verbNoun>.js` (e.g. `formatters.js`).
- Export via `exports.fn = ...` (CommonJS-style is used in existing utils) or ES `export const`.

**New global SASS block:**
- Add `src/styles/blocks/<name>.sass` and append `@import ./blocks/<name>` to `src/styles/app.sass`.

**New static asset:**
- Image used by JS: `src/images/<name>.<ext>` and `import img from "../../images/<name>.png"`.
- Image referenced from HTML/CSS: `public/images/<name>.<ext>` and reference via `/images/<name>.png`.
- Font: `public/fonts/<name>.<woff2|woff|ttf>`, declare in `public/css/fonts.css`.

**New token-redirect handler:**
- Add as a named export in `src/screens/Api/ApiPages.js`.
- Route from `src/App.js` (typically in the `<Page>` branch).

## Special Directories

**`public/`:**
- Purpose: CRA convention — files here are copied verbatim and served at root
- Generated: No
- Committed: Yes (all assets, including legacy `favicon_OLD.ico`)

**`build/`:**
- Purpose: CRA production output of `yarn build`
- Generated: Yes
- Committed: No (gitignored)

**`node_modules/`, `.pnp/`, `.yarn/`:**
- Purpose: Yarn dependency caches
- Generated: Yes
- Committed: No (gitignored)

**`cloud-browser-static/dist/`:**
- Purpose: Output of the sub-project's webpack build
- Generated: Yes
- Committed: No (gitignored)

**`.planning/`:**
- Purpose: GSD planning / codebase-map artifacts
- Generated: Yes (by `/gsd:*` commands)
- Committed: Project-defined (not currently in `.gitignore`)

**`.claude/`:**
- Purpose: Claude Code agent state
- Generated: Yes
- Committed: No (untracked)

---

*Structure analysis: 2026-05-21*