Crest Suite

Multi-tenant hospitality SaaS for Nepal's F&B industry. One React app on one Supabase project; inventory, HR and POS are modules toggled per client, Crest Customization (sizes, extras and "No …" choices on a dish, build-your-own dishes walked step by step, and combos sold at one price) is a paid add-on to POS, and Crest Suite Pro is the owner layer sold on top.

Repo: C:\crest-suite · E-drive backup: E:\CREST SUITE MANAGEMENT\

This file is a map, not a summary. Everything below points somewhere; nothing here restates what it points at. A line that describes rather than points is a line that goes stale without anyone noticing — that is how this file reached 1.8 million characters (see S666). Add new material to the file that owns the subject, and add a pointer here only if there is nowhere else.

---

Quick Start

npm start           # Dev server → http://localhost:3000
npm run build       # Production build (this is what Vercel runs)
npm run build:verify  # Same build, for checking a change locally: clears the stale
                      # ESLint cache first and treats warnings as errors. Use this
                      # while `npm start` is running — the two share
                      # node_modules/.cache, and a dev server writing stale entries
                      # back is what produces build errors that are not in the code.
npm test            # Jest suite
npm run check:docs  # Rules-glob, rules-stub and CLAUDE.md-size checks. Also run by
                    # build:verify, so a rule that silently stopped loading fails a
                    # pre-push check rather than waiting for the next /doctor pass.

Env vars required:

REACT_APP_SUPABASE_URL
REACT_APP_SUPABASE_ANON_KEY
REACT_APP_USDA_API_KEY
REACT_APP_VAPID_PUBLIC_KEY
REACT_APP_SITE_ORIGIN

.env.example says what each one is for. REACT_APP_SITE_ORIGIN is the only one whose absence is silent in dev and visible on paper: it is the production domain the printed Subscription Agreement quotes as the evidence of what a signed contract incorporated by reference, so unset it prints [SET REACT_APP_SITE_ORIGIN]/legal/terms rather than a plausible wrong domain, and legalReadiness() refuses to call the documents publishable.

REACT_APP_SUPABASE_SERVICE_ROLE_KEY must never be set here or in Vercel — admin operations go through the admin-user-ops Supabase Edge Function instead (see S311).

---

Repo layout

Path	What lives there
src/modules/	The product, one directory per area: ims/, hr/, pos/, admin/, dashboard/, ownerReport/
src/pages/	Routes belonging to no single module — login, signup, pricing, help, settings, periods
src/shared/	Cross-module code: the scoped data-access layer, paged reads, error text, hooks
src/components/	Reusable UI, and the route guards every protected route stacks
src/context/	Auth, settings and theme providers. Singular context — the plural is a glob that has already rotted once
src/utils/	Standalone helpers: BS calendar, expression evaluator, subscription state, timeouts
src/data/	pricingPlans.js — the plans, their feature lists, and the SHIPPED prices. What a screen prints is resolvePricing() over the admin's Settings > Plan Pricing figures, reached as useSettings().pricing
src/legal/	The published Terms and Privacy Policy as markdown, their content hashes, and the registry the acceptance flow stamps. Edit a .md and re-run node scripts/hash-legal.mjs; a test fails if you forget
supabase/	Migrations and Edge Functions
scripts/	Build, audit and docs-check scripts, all reachable from package.json — except check-design-layers.mjs, run by hand after a theme change
public/	PWA shell and service worker, plus the second manifest for the staff app

---

Map

Read this	For
CLAUDE.md	Commands, stack, and the rules that must be known before you think to ask: the gate model, tenant isolation, the privilege invariants, the Supabase and BS-date traps, plus a pointer table into .claude/rules/. Loaded on every request of every session, so it holds nothing module-specific.
.claude/rules/	The same kind of rule, scoped by a paths: glob so it loads only when a matching file is open. Check npm run check:docs still passes after moving a file.
.claude/skills/new-feature-checklist/	The steps between "it works" and "it shipped". Invoke it before any new page, report or module feature.
DESIGN.md	The design system as it actually exists in the code: tokens, scales, components, and the named rules that are already enforced.
PRODUCT.md	Who buys this and why — users, positioning, brand personality, anti-references.
IMS_TODO.md	The S756 IMS re-analysis: the owner's 28 decisions and the fix list by stage, with what is still open.
POS_TODO.md	POS open items. Shipping something listed there closes the entry in the same commit.

There is no ARCHITECTURE.md and there should not be. CLAUDE.md plus .claude/rules/ already is that document, and a fourth copy of the gate model would drift from the three that exist.

---

Conventions worth knowing before the first commit

• Line endings. .gitattributes normalises the tree to LF on commit, which is not the same as the working tree being LF, and it is not. Measured 2026-09-09: MenuPricing.js is pure LF and MenuRepricing.js, its sibling in the same directory, is pure CRLF; several .claude/rules/*.md are mixed within one file. Git never reports this, because it normalises on the way in. So a script that searches for a string containing \n silently matches nothing in half the repo — assert your match count, and try \r\n before \n per replacement block rather than per file. Do not "fix" a file by normalising it: that turns a 12-line diff into a whole-file rewrite. Separately, do not write files with PowerShell's Set-Content -Encoding utf8 — it emits a BOM — or read them with Get-Content, which reads ANSI and mangles every em dash. Use [System.IO.File]::ReadAllText / WriteAllText, or a shell that is not PowerShell.
• The service worker caches aggressively. Any JS or CSS change that existing users must actually receive needs CACHE_NAME bumped in public/service-worker.js and APP_VERSION in src/shared/appVersion.js moved to match — appVersion.test.js fails when they disagree. They had drifted nine bumps apart before S689 noticed, so the test is doing real work. CLAUDE.md explains why a plain deploy is not enough.
• A deploy breaks the tabs that are already open, and that is handled rather than avoided. Every page is React.lazy and xlsx is imported inside the click handler, so the app fetches its own code by hashed filename; Vercel replaces those files and the worker's activate deletes the cached copies on the same event. src/shared/chunkReload.js recognises that failure and reloads once — never more than once a minute, never while offline. Do not widen its patterns to catch ordinary errors: a real crash misread as a stale deploy is hidden by the mechanism meant to recover from it.
• The service worker precaches the app SHELL only — / plus the one js/css pair named in the build's asset-manifest.json. A route whose own chunk has not been fetched since the last deploy still cannot render offline, and the error boundary says so in those words. No Supabase response is ever cached; anything that must survive a lost connection needs its own IndexedDB store, which is what Stock Count and POS order-taking have and nothing else does.
• Every session gets a changelog entry, written into the newest range file. The convention, including when to start a new range, is in .