Production and staging repos

Summary#

Metric Vault is developed in two repositories that hold the same application code and deliberately different infrastructure. metricvaultai is production: it serves metricvaultai.com through the Cloudflare Pages project named metricvaultai. metricvaultai-seo is staging, and it deploys to metricvaultai-seo.pages.dev. Most feature work happens in staging first and is then ported across.

The model works because the split is precise. Six paths are supposed to be byte-identical, three must never be copied in either direction, and one script tells you which side of that line every difference falls on. Copying one of the three has caused a production outage before.

Purpose#

Two repositories exist to separate the risk of shipping code from the risk of changing infrastructure.

Production has no build step and no approval gate: a push to main is live within about a minute. A repository that is both the place experiments happen and the place customers are served offers no safe way to try something. Staging absorbs that. It has its own Pages project, its own bindings, its own database and its own deploy workflow, so a change can be exercised end to end without any possibility of touching live customer data.

The cost of that separation is drift. Two copies of the same 1.7 MB worker and 7.2 MB dashboard diverge quietly, and a port that overwrites the wrong file takes production down. Everything below exists to make drift visible and to make the dangerous files obvious.

Overview#

What each repository is#

Both are Cloudflare Pages projects in advanced mode with a hand-written _worker.js at the top of the published folder, and neither has a build step. The shape is described in System architecture.

The three files that must never be ported#

Copying any of these between the repositories replaces this project's infrastructure with the other project's.

What should stay in sync#

Everything that is the product rather than the plumbing:

_worker.js, dashboard.html, js/, css/, the top-level *.html pages, legal/, and free-tools/.

If one of those differs between the repositories, that is a real finding to investigate, not a normal state of the world.

What is expected to differ#

compare-repos.mjs classifies these as infrastructure and reports them separately rather than failing on them: wrangler.toml, .assetsignore, .gitignore, sitemap.xml, CLAUDE.md, README.md, plus everything under .github/ and cron-worker/. CLAUDE.md and README.md are per-repository onboarding documents, so each one describing its own repository is correct, not drift.

How it works#

Checking the drift before you port#

node tests/compare-repos.mjs ../metricvaultai-seo-main

With one argument the script compares the current working directory against the given directory. With two, it compares the two directories you name.

What it ignores. Directories .git, dist, node_modules, .wrangler, images and icons. Files .dev.vars, server.log and .DS_Store. Any file with a binary extension: png, jpg, jpeg, gif, ico, webp, woff, woff2, ttf, pdf, mp4, zip.

How it compares. Content is hashed with SHA-256 after stripping every carriage return and a single trailing newline, so CRLF against LF and a final-newline difference never read as a real change. That matters here, because dashboard.html and legal.html are CRLF and several public pages have mixed line endings.

What it prints. A header with both paths and the number of text files compared, then four counts: identical, differ, only in A and only in B. Then the section that matters, APP CODE that differs (these SHOULD match; investigate each), listing each file with its line count on both sides. Then a separate infra/config that differs (usually fine) list, then the files present on only one side, each tagged [infra: expected to differ] where that applies.

The semantic diff. Line-by-line equality is a weak signal on two files this large, so the script also extracts and compares feature sets: every /api route in _worker.js and every id="view-..." in dashboard.html. It reports the count on each side and names the routes or views present on one side only. This is the fastest way to answer "did the port actually bring the feature across".

The exit code. 1 if any non-infrastructure file differs, 0 otherwise. Infrastructure differences never fail the run.

It closes with the command to see the real changes in any one file:

git diff --no-index "<other-repo>/<file>" "<this-repo>/<file>"

Porting work across#

1. Run the drift check first, before you copy anything, so you know what was already different and do not attribute it to your port.
2. Copy only application code. _worker.js, dashboard.html, the specific files under js/ and css/, the pages you changed. Never the three infrastructure files.
3. Watch for new files. A ported feature that introduced a new directory needs that directory staged by the deploy workflow, or its HTML ships and its assets 404. This repository once staged a hardcoded 24-file allowlist and produced exactly that failure, which is why the workflow now copies every top-level *.html and stages by directory rather than by filename. See Deployment.
4. Re-run the generated copies. Porting login.html without re-running node tests/login-inline-sync.mjs --write leaves production serving the old inlined page. Porting a public page without node tests/site-chrome-sync.mjs --write leaves its navbar and footer stale. Both have no-argument drift checks that exit 1.
5. Re-run the drift check and confirm the app-code list is empty.
6. Run the gates for whatever you touched, then push. Every script is documented in Verification scripts.

Preview branches are not a substitute#

Within production, any branch listed in the deploy workflow's trigger gets its own Cloudflare Pages preview at <branch>.metricvaultai.pages.dev, with the same D1 and KV bindings, and never touches the live site. Today that is main and redesign.

That is useful for reviewing a change on a real URL. It is not a staging environment, because the bindings are the production ones: a preview branch writes to the production database. Anything that mutates data, changes a schema or exercises a background job belongs in the staging repository, not on a preview branch.

Where drift usually comes from#