Developer Guide
Architecture, code organization, data model, deployment, testing, and conventions.
22 articles · Written for: Developers
Architecture
Developer guide
The internal engineering manual for Metric Vault - architecture, the worker, the data model, the frontend, deployment and the conventions that keep two developers out of each other's way.
System architecture
Metric Vault is a Cloudflare Pages project in advanced mode - one hand-written _worker.js answers /api/*, everything else falls through to env.ASSETS, and there is no build step.
Repository structure
Every top-level file and directory in the production repository, what it is for, whether it ships, and which ones must never be edited directly.
Frontend
Frontend architecture
How dashboard.html is put together - the three-column shell, the 106-view router, the renderer dispatch chain, and every file in js/ and css/ with what it owns.
The design system
The six binding laws from the Design Constitution, the token vocabulary in css/tokens.css, and the design-lint ratchet that fails a build when any debt count rises.
Building a result renderer
How to add a renderer that draws a tool result from the shared .mvr-* vocabulary, register it in the dispatch chain, and get the recommendations panel for free.
Localization system
Four separate translation systems share one generated dictionary; this is what each one covers, the four-command pipeline, and exactly what the extractor does and does not pick up.
Centralized nav and footer
One navbar and one footer live in partials/ and are stamped into 21 public pages by a sync script; editing the chrome inside a page does nothing.
Backend
The worker (_worker.js)
How the single 28,000-line worker is organized - the flat ordered router, where each family of routes sits, the response helpers, CORS, and how errors surface.
Request lifecycle
A request traced from the Cloudflare edge to the response - route inclusion, the tracking wrapper, identity, plan and quota gates, the cache layers, the provider call and the telemetry writes.
Authentication and authorization flow
The five identity mechanisms in the worker, how each is verified, and an exact account of which gates fail open, which fail closed, and why each choice was made.
Caching architecture
Two independent cache layers sit in front of the paid providers, plus seven feature caches, each with its own key format, TTL and control surface.
Background jobs and scheduling
Cloudflare Pages never calls scheduled(), so background work is driven by an external clock that POSTs to a secured endpoint, and every job self-throttles in the database.
Data Model
Data model
Every one of the 60 D1 tables with its columns and indexes, plus the Supabase tables, the unused KV namespace, the R2 bucket and the edge cache.
Schema migrations
There is no migration system. Every feature creates its own tables at request time with ensure*Schema, and this page covers how that works, what it buys and where it bites.
Build, Deploy & Test
Local development
How to run Metric Vault on your machine with wrangler pages dev, the dist/ copy trap that wastes more time than anything else here, and what cannot be tested locally.
Environment variables and secrets
Every environment variable and secret the worker reads - what it is for, where it must be set, what breaks without it, and whether the gate fails open or closed.
Deployment
How a commit becomes the live site - the staging step, the wrangler command and why it takes no positional directory, the separate cron-worker deploy, and how to roll back.
Verification scripts
Every script in tests/ - the exact command, what it checks, what a failure means, and which ones you must run before you commit.
Conventions
Code conventions and file ownership
The two-developer file split, the branch strategy, the shared files that change two pages at once, the CRLF traps, and the checklist to run before every commit.
Production and staging repos
Why Metric Vault lives in two repositories, which files must stay identical, which three must never be copied, and how compare-repos.mjs measures the drift.
Adding a new tool
Every file that must change to ship a new tool - the worker handler, its credit cost and section, the dashboard view and renderer, translations, tests and documentation.