Developer guide

Summary#

This category is the engineering manual for the codebase that serves metricvaultai.com. It documents how a request travels from the Cloudflare edge to a rendered result, where every byte of state lives, how the frontend is put together, how a deploy happens, and the file-ownership rules that let two developers work on the same repository without destroying each other's changes.

It is internal. Every page here contains file paths, line references and code identifiers, and none of it is written for a customer to read. If you need the customer-facing explanation of a feature, start at Getting started with Metric Vault instead.

Overview#

Four facts shape almost every decision in this codebase. Read them before you open anything else.

There is no build step. No package.json, no bundler, no transpiler, no node_modules. The files you edit are the files that ship. Every script in js/ is a classic script, every stylesheet in css/ is plain CSS, and the deploy workflow is a cp loop. This constraint is why several things look unusual: the verification tools in tests/ depend on nothing but Node's standard library, each js/mv-i18n-dict.<lang>.js is a 2.8-3.8 MB generated file rather than a compiled artefact, and load order in dashboard.html is load-bearing.

One hand-written worker answers everything. _worker.js is a single 1.7 MB file containing a flat, ordered chain of if statements. It answers /api/* itself and hands everything else back to the static site through env.ASSETS. There is no framework and no route table. First match wins, so ordering matters. See The worker (_worker.js).

Almost all state is in one D1 database. The binding is MONITOR_DB, and it holds 59 tables covering billing, usage, the Library, caches, telemetry, integrations and the blog. There is no migration system: each feature creates its own tables lazily at request time. See Data model and Schema migrations.

Cron does not exist on Pages. Cloudflare Pages never calls scheduled(). Background work is driven by an external scheduler that POSTs to a secured endpoint. See Background jobs and scheduling.

Architecture#

• System architecture - Cloudflare Pages advanced mode, the single worker, the env.ASSETS fallback, the external systems and how they fail.
• Repository structure - every top-level file and directory, what it is for, and whether it ships.

Backend#

• The worker (_worker.js) - router structure, dispatch order, handler conventions, CORS and error handling.
• Request lifecycle - a request end to end: tracking wrapper, identity, plan gate, quota, cache, provider call, response, telemetry.
• Authentication and authorization flow - the five authentication mechanisms and exactly which gates fail open and which fail closed.
• Caching architecture - the two independent cache layers, key formats, TTL resolution and the admin overrides.
• Background jobs and scheduling - why scheduled() never fires, the cron-worker, the GitHub Actions backup, and job idempotency.

Data#

• Data model - every D1 table with its columns, plus the Supabase tables, the KV namespace and the R2 bucket.
• Schema migrations - the lazy ensure*Schema pattern, what it buys, and the five ways it bites.

Frontend#

• Frontend architecture - dashboard.html, the view system, the renderers and every file in js/.
• The design system - the six constitution rules, the token vocabulary, the .mvr-* Result Shell and the design-lint ratchet.
• Building a result renderer - the renderers-return-data contract and how to add a renderer correctly.
• Localization system - all four translation systems, the extract/generate/verify pipeline, and what the scanner will never see.
• Centralized nav and footer - the centralized navbar and footer, the sync script and the .mv-* namespacing rationale.

Build, deploy and test#

• Environment variables and secrets - every environment variable: purpose, where it is set, what breaks without it.
• Local development - wrangler pages dev, the dist/ copy trap, and what cannot run locally at all.
• Deployment - the deploy workflow step by step, the required secrets, the separate cron-worker deploy and how to roll back.
• Verification scripts - every script in tests/, what it checks, and which ones gate a commit.

Conventions#

• Code conventions and file ownership - the two-developer file split, branch strategy, the CRLF files and the shared-file rules.
• Production and staging repos - the production and staging repositories, compare-repos, and the three files that must never be ported.
• Adding a new tool - every file that has to change when a new tool is added.

Where to look when something is wrong#