From 117197fc4ed4ce0603f08e4480dd6b12e86c2357 Mon Sep 17 00:00:00 2001
From: "moxie-docs[bot]" <287554421+moxie-docs[bot]@users.noreply.github.com>
Date: Fri, 11 Sep 2026 05:04:17 +0000
Subject: [PATCH] docs: 2 files

---
 moxie-docs/frontend/frontend-package.md | 99 +++++++++++++++++++++++++
 moxie-docs/frontend/frontend.md         | 81 ++++++++++++++++++++
 2 files changed, 180 insertions(+)
 create mode 100644 moxie-docs/frontend/frontend-package.md
 create mode 100644 moxie-docs/frontend/frontend.md

diff --git a/moxie-docs/frontend/frontend-package.md b/moxie-docs/frontend/frontend-package.md
new file mode 100644
index 0000000..fb3cbfa
--- /dev/null
+++ b/moxie-docs/frontend/frontend-package.md
@@ -0,0 +1,99 @@
+# Frontend build, start-up, and environment contracts
+
+This area documents how the React frontend is started and built, what tooling and scripts are involved, and the runtime entry point and side effects. It exists to make maintainers productive quickly when running, building, or modifying the frontend and its bootstrapping code.
+
+## Architecture
+
+- Entry point: `frontend/src/index.js` creates the React root and renders the `App` component inside `React.StrictMode`, and initializes web vitals reporting via `reportWebVitals()`.
+- Tooling and scripts: `frontend/package.json` defines dependencies (React 18, react-scripts) and the `npm` scripts (`start`, `build`, `test`, `eject`) that drive local dev, CI, and production builds.
+- Developer guide: `frontend/README.md` is the Create React App (CRA) reference for how to run, build, test, eject, and tune the app.
+- Maintainer doc: `moxie-docs/frontend/build-and-env.md` is reserved for focused maintainer guidance specific to how this app starts/builds and environment usage.
+
+## frontend/package.json
+
+This file defines the app’s dependencies, build/test/dev scripts, and browserslist targets. It drives how the frontend is executed in dev and built for production.
+
+- Name/version/private:
+  - "name": "frontend"
+  - "version": "0.1.0"
+  - "private": true
+- Dependencies:
+  - React runtime: "react": "^18.3.1", "react-dom": "^18.3.1"
+  - CRA tooling: "react-scripts": "5.0.1"
+  - Testing: "@testing-library/react": "^13.4.0", "@testing-library/jest-dom": "^5.17.0", "@testing-library/user-event": "^13.5.0"
+  - Metrics: "web-vitals": "^2.1.4"
+- Scripts (entry points for day-to-day tasks):
+  - `npm start` → `react-scripts start`
+    - Runs the development server with live reload on the CRA defaults (typically http://localhost:3000).
+  - `npm run build` → `react-scripts build`
+    - Creates a production build in the `build` directory, with minified assets and hashed filenames.
+  - `npm test` → `react-scripts test`
+    - Launches the Jest-based test runner in watch mode.
+  - `npm run eject` → `react-scripts eject`
+    - One-way operation to copy CRA configs locally (webpack, Babel, ESLint); subsequent scripts use the copied configs.
+- ESLint configuration:
+  - Extends `react-app` and `react-app/jest` presets.
+- Browserslist targets:
+  - Production: `>0.2%`, `not dead`, `not op_mini all`
+  - Development: last 1 version of Chrome/Firefox/Safari
+
+Operational implications:
+- The build pipeline and dev server behavior are controlled by `react-scripts` 5.0.1. Any custom webpack/Babel config requires ejecting.
+- Test expectations and DOM assertions are aligned to Testing Library versions pinned above.
+
+## frontend/src/index.js
+
+This is the runtime entry point for the React application. It mounts the root component and wires in web vitals reporting.
+
+Key behavior and control flow:
+- Imports and dependencies:
+  - `import React from 'react'`
+  - `import ReactDOM from 'react-dom/client'` (React 18 root API)
+  - `import './index.css'` (global stylesheet; included by bundler)
+  - `import App from './App'` (top-level application component)
+  - `import reportWebVitals from './reportWebVitals'` (performance reporting hook)
+- Root creation and render:
+  - `const root = ReactDOM.createRoot(document.getElementById('root'));`
+  - `root.render(<React.StrictMode><App /></React.StrictMode>);`
+    - Ensures `App` is rendered within `StrictMode` for additional development checks.
+- Performance reporting:
+  - The file calls `reportWebVitals();` unconditionally. Inline comment documents optional usage: pass a function (e.g., `reportWebVitals(console.log)`) to log results or send to an analytics endpoint.
+
+Side effects and contracts:
+- Requires a DOM element with id `root` present in the host HTML (CRA provides this in `public/index.html`).
+- `reportWebVitals()` executes; by default it has no output unless the implementation forwards metrics.
+
+What’s not here:
+- There is no environment variable handling or API URL selection in this file. Any such logic would live in other modules/components.
+
+## frontend/README.md
+
+This is the standard Create React App README and serves as developer-facing guidance for running and maintaining the app.
+
+Key guidance it codifies (mirrors the actual scripts in `package.json`):
+- `npm start`: runs the dev server; view the app at http://localhost:3000. Auto-reload on changes; lint errors appear in console.
+- `npm test`: runs tests in interactive watch mode and links to CRA docs for running tests.
+- `npm run build`: generates an optimized production build in `build` with minification and hashed filenames; links to CRA deployment docs.
+- `npm run eject`: one-way operation to expose config files; subsequent scripts reference the copied configs.
+- Additional CRA references: code splitting, bundle analysis, PWA, advanced config, deployment, and troubleshooting.
+
+These instructions align with the concrete scripts and dependencies declared in `frontend/package.json`.
+
+## moxie-docs/frontend/build-and-env.md
+
+This path is reserved for focused maintainer documentation about how the frontend starts, builds, and uses environment variables in relation to the backend API. Keep content in this file grounded in:
+- The execution and build scripts defined in `frontend/package.json`.
+- The runtime bootstrapping behavior in `frontend/src/index.js` (React 18 root creation, `StrictMode`, and web vitals reporting).
+- Any environment variable usage that is implemented in the codebase (e.g., references to `process.env.*` in source files), including how those values affect build-time vs run-time behavior under `react-scripts`.
+
+If you add or modify environment variable dependencies, document:
+- The exact variable names expected by `react-scripts` (such as `REACT_APP_*`), where they are read, and their default/required values.
+- How the dev server (`npm start`) vs production build (`npm run build`) pick up these variables.
+- Any backend URL targeting logic and how it changes across environments.
+
+## Gotchas
+
+- Eject is irreversible: running `npm run eject` permanently replaces `react-scripts` with local config. Commit discipline and CI/CD updates will be required after ejecting.
+- React 18 root API: `ReactDOM.createRoot` is used; migrating to legacy APIs (or vice versa) requires coordinated changes across hydration/server rendering if introduced elsewhere.
+- Web vitals reporting: `reportWebVitals()` is invoked. If you start logging or sending metrics (by passing a function), verify PII and performance overhead considerations.
+- Browserslist impact: altering the `browserslist` in `frontend/package.json` changes transpilation/polyfills and can affect bundle size and compatibility.
\ No newline at end of file
diff --git a/moxie-docs/frontend/frontend.md b/moxie-docs/frontend/frontend.md
new file mode 100644
index 0000000..b4cea0f
--- /dev/null
+++ b/moxie-docs/frontend/frontend.md
@@ -0,0 +1,81 @@
+# Frontend environment variables: how they are defined and reach the code
+
+This area documents how environment variables are recognized by the Create React App (CRA)-based frontend and how they become available to runtime code. It exists to clarify which variables are picked up by the tooling, when they are injected, and where the current code consumes them.
+
+## Architecture
+
+- Tooling and runtime:
+  - `frontend/package.json` defines the app as a CRA project via `react-scripts` and exposes the standard CRA scripts (`start`, `build`, `test`, `eject`). CRA controls environment variable exposure and injection at build and dev-server time.
+  - `frontend/src/index.js` is the React entry point. It renders `<App />` and initializes web vitals via `reportWebVitals()`. In the current code, it does not read or reference any environment variables.
+  - `frontend/README.md` is the stock CRA README, which implies standard CRA environment behavior and lifecycle.
+- Data/control flow for env vars:
+  - At `npm start`/`npm run build` time, `react-scripts` reads environment variables from the shell and `.env*` files and statically inlines any prefixed variables that CRA exposes into the bundle.
+  - Runtime code can access those variables through `process.env.VAR_NAME` (evaluated at build time by CRA).
+
+## frontend/package.json
+
+Responsibility: Declares the CRA app and the scripts that govern when and how environment variables are read and injected.
+
+Key points from the file:
+- Dependencies include `react-scripts@5.0.1`, which is the mechanism that recognizes and injects environment variables during `start` and `build`.
+- Scripts:
+  - `start`: `react-scripts start`
+  - `build`: `react-scripts build`
+  - `test`: `react-scripts test`
+  - `eject`: `react-scripts eject`
+
+Environment variable behavior driven by `react-scripts`:
+- Variables are read from the shell and optional `.env` files at command invocation time. CRA supports multiple files such as `.env`, `.env.local`, `.env.development`, `.env.production`, and their `.local` variants; these are merged according to CRA rules during `start`/`build`.
+- Only variables with the `REACT_APP_` prefix are exposed to the client bundle. Unprefixed variables are not available in browser code.
+- `NODE_ENV` is set by the scripts (`development` for `start`, `production` for `build`) and can be used in code but should not be manually overridden.
+
+Common patterns enabled by this setup (available to the code if added):
+- API base URL: `REACT_APP_API_BASE_URL`
+- Feature flags: `REACT_APP_FEATURE_X_ENABLED`
+- Analytics keys: `REACT_APP_ANALYTICS_KEY`
+
+These will be accessible in code as `process.env.REACT_APP_API_BASE_URL`, etc., after being inlined by the build.
+
+## frontend/src/index.js
+
+Responsibility: The application entry point that mounts the React tree and initializes web vitals.
+
+Content overview and behavior:
+- Renders the app:
+  - Creates a root via `ReactDOM.createRoot(document.getElementById('root'))`.
+  - Renders:
+    ```js
+    <React.StrictMode>
+      <App />
+    </React.StrictMode>
+    ```
+- Performance reporting:
+  - Calls `reportWebVitals()` at the bottom of the file. Inline comment notes that you can pass a logger (e.g., `reportWebVitals(console.log)`) or send metrics to an analytics endpoint.
+
+Environment variables in this file:
+- No `process.env.*` usage exists in this file as currently implemented.
+- Because this is the composition root, it is a typical point to add environment-driven configuration for the app (e.g., pass `process.env.REACT_APP_*` values as props or via context). To do so safely, ensure variables are prefixed with `REACT_APP_` and read them synchronously at module init time so CRA can inline them.
+
+## frontend/README.md
+
+Responsibility: The stock CRA README that documents the lifecycle and commands used by the frontend. While it does not list specific environment variables, it implies the standard CRA environment model tied to `react-scripts`.
+
+Relevant aspects:
+- Describes `npm start`, `npm test`, and `npm run build`, which are the touchpoints where CRA reads and injects environment variables.
+- Links to CRA documentation where advanced configuration (including `.env` usage and variable exposure rules) is covered.
+
+## Using environment variables in this frontend
+
+- Prefixing requirement: Only variables starting with `REACT_APP_` are exposed to the browser bundle. Example: `REACT_APP_API_BASE_URL=https://api.example.com`.
+- Access in code: Use `process.env.REACT_APP_API_BASE_URL` (or another `REACT_APP_*` variable) in application code. CRA replaces these at build time.
+- Environment files: Place variables in `.env`, `.env.development`, `.env.production`, and optional `.local` variants at the repository root of the `frontend` app. For local development, `.env.local` is not committed and overrides others.
+- Build-time nature: Values are captured at build or dev-server startup. Changing the shell or `.env` after `npm start` requires restarting the dev server; after `npm run build` requires a rebuild.
+
+## Gotchas
+
+- Missing prefix: Unprefixed variables (e.g., `API_BASE_URL`) will not be available in browser code; use `REACT_APP_API_BASE_URL`.
+- Runtime vs build time: Environment variables are inlined at build time by CRA. They are not dynamically read at runtime from the host environment after the bundle is served.
+- Type coercion: All `process.env.REACT_APP_*` values are strings. Parse to numbers/booleans in code if needed.
+- Secrets: Anything exposed via `REACT_APP_*` will be shipped to the browser. Do not put secrets or private keys in these variables.
+- Dev server restart: If you change `.env*` files or shell variables, you must restart `react-scripts start` for changes to take effect.
+- `NODE_ENV` handling: Managed by `react-scripts`. Do not set `NODE_ENV` manually in `.env`; rely on the script being run (`start` vs `build`).
\ No newline at end of file