System architecture

Summary#

metricvaultai.com is a Cloudflare Pages project in advanced mode. A single hand-written _worker.js sits at the top of the published folder, so every request that is not excluded by _routes.json hits that worker first. The worker either answers the request itself (all of /api/*, plus a handful of HTML and redirect routes) or hands it back to the static files through the env.ASSETS binding.

There is no build step. No package.json, no npm install, no bundler, nothing compiled. The deploy workflow copies files into dist/ and calls wrangler pages deploy. The file you edit is the file that ships.

All persistent state lives in one D1 database bound as MONITOR_DB. Identity comes from Supabase Auth. Data comes from DataForSEO and a set of LLM providers. Background work is driven by a second, separate Cloudflare Worker because Pages cannot run cron.

Purpose#

The shape of this system is a response to three constraints.

Cost and latency. The product is a thin orchestration layer over expensive third-party APIs. Running it at the edge as a Worker means the orchestration itself is close to free and close to the user, and the money goes to the providers rather than to idle servers. The shared cache in front of those providers exists for the same reason.

One deployable unit. A single worker plus a static asset set means there is exactly one thing to deploy, one place a request can be handled, and one file to read when a route misbehaves. The cost is a 1.7 MB source file, which is a real cost, but it is a cost paid by developers rather than by users.

No toolchain to rot. Removing the build step removes an entire class of failure: dependency drift, lockfile conflicts, a bundler version that stops supporting a syntax, a CI cache that goes stale. It also means anyone can open a file, change one line, and know exactly what production will run.

Architecture#

                    ┌──────────────────────────────┐
   browser  ───────▶│  Cloudflare edge             │
                    │  _routes.json decides:       │
                    │   15 excluded paths → static │
                    │   everything else  → worker  │
                    └──────────────┬───────────────┘
                                   │
                    ┌──────────────▼───────────────┐
                    │  _worker.js                  │
                    │  export default { fetch }    │
                    │    → mvTrackedFetch          │
                    │       → mvRouteRequest       │
                    └──┬────────────┬──────────┬───┘
                       │            │          │
            /api/* ────┘            │          └──── everything else
                                    │                 env.ASSETS.fetch()
      ┌───────────┬──────────┬──────┴─────┬─────────────┐
      │           │          │            │             │
   MONITOR_DB  Supabase   DataForSEO   LLM providers  BLOG_MEDIA
     (D1)      (auth +     (SEO data)  (OpenAI,       (R2)
               2 tables)               Anthropic,
                                       Gemini,
                                       Perplexity,
                                       Workers AI)

   metricvault-cron (separate Worker, */15 * * * *)
        └── POST /api/cron/run  with x-mv-internal-secret
   .github/workflows/cron.yml (hourly backup)
        └── same endpoint

Cloudflare Pages advanced mode#

Pages has two modes. In the normal mode you write route files under functions/ and Cloudflare assembles a worker for you. In advanced mode you place a file literally named _worker.js at the root of the published output directory, and Cloudflare uses that file verbatim as the entire worker. Nothing is generated, nothing is merged, and the functions/ convention is ignored.

Three consequences follow, and each has caused a production incident at least once:

1. env.ASSETS is provided automatically. Advanced mode binds the static asset set to env.ASSETS without any [assets] block in wrangler.toml. That is the only way to serve a static file once the worker is in front of everything.
2. wrangler.toml must stay in Pages format. It carries pages_build_output_dir = "dist". The file previously used the Workers format while the workflow deployed with wrangler pages deploy, so the D1 and KV bindings were never applied and the live site failed with MONITOR_DB not bound. Wrangler may need a redeploy. The header comment in wrangler.toml records that outage.
3. The deploy must not pass a positional directory. The workflow runs wrangler pages deploy --project-name=metricvaultai --branch=... with no directory argument, so wrangler reads pages_build_output_dir from wrangler.toml and applies the bindings declared there. Passing dist/ positionally skips the bindings entirely.

The env.ASSETS fallback#

Every request that reaches the worker and matches none of the /api or special routes falls through to a chain at the end of mvRouteRequest (_worker.js:2331-2438):

1. const assetResponse = await env.ASSETS.fetch(request).
2. If the status is 200 and the body is non-empty, HTML responses are re-emitted with an explicit charset=utf-8 and everything else is returned as-is.
3. Otherwise the worker classifies the path. isAssetPath is /\.[a-z0-9]{2,5}$/i (anything with a file extension). isDocumentRoute is everything else plus the explicit set /, /dashboard, /login, /admin, /privacy, /terms.
4. For a document route with no extension, the clean URL is remapped to its .html file (/dashboard to /dashboard.html, and so on) and re-fetched through env.ASSETS.
5. If ASSETS still returns 404, the path has no extension and the method is GET, the worker fetches /404 then /404.html and returns that body with status 404, Content-Type: text/html; charset=utf-8 and Cache-Control: no-store.

Assets with a file extension deliberately keep their bare 404. An earlier version fell back for every 404, which served an old deployment's index.html in place of a missing /sw.js, and the wrong MIME type broke service-worker registration with a SecurityError.

No build step#

There is no package.json at the repository root. The "build" is a shell block in .github/workflows/deploy.yml that copies a named file list, then every top-level *.html, then the directories icons free-tools reports legal js css images into dist/, and writes an empty dist/.assetsignore.

The list is staged by directory, never by filename, because an earlier hardcoded 24-file allowlist shipped ported HTML without its assets and produced 404s in production. Full detail is in Deployment.

Components#

Bindings#

QUICKVIEW_CACHE is declared in wrangler.toml and read by nothing. The feature it was created for uses a D1 table instead, and the reason is written in the code at _worker.js:15880-15881: KV bindings on this Pages project reset on every deploy, so MONITOR_DB is used because it is reliably bound. The same note appears for platform_config at _worker.js:18662. Treat any documentation that mentions "the KV cache" as stale.

External systems#

The second deploy#

cron-worker/ is a standalone Cloudflare Worker, not part of the Pages project. It has no storage bindings. Its only job is to fire every 15 minutes and POST to https://metricvaultai.com/api/cron/run with an x-mv-internal-secret header. It is deployed separately with cd cron-worker && wrangler deploy, and its secret is set with wrangler secret put MV_INTERNAL_SECRET. See Background jobs and scheduling.

Data flow#

A typical metered tool run:

1. The browser posts to /api/premium-ai with a JSON body. dashboard.html patches window.fetch so every same-origin /api/ request also carries Authorization: Bearer <supabase access token>, but almost no handler reads it yet.
2. _routes.json does not exclude /api/*, so the request reaches the worker.
3. mvTrackedFetch looks up a route descriptor, buffers the JSON body if it is under 24,000 bytes, and calls the router.
4. mvRouteRequest matches /api/premium-ai and calls mvSaveAroundPremiumAI, the shared-cache wrapper.
5. The wrapper checks mv_seo_cache in D1. On a fresh hit it still runs the quota gate and still charges the credit, then returns the stored body with X-MV-Cache: hit.
6. On a miss, handlePremiumAI runs the kill-switch check, the recommendation gate where applicable, enforceAiQuota, then incrementUsage, then the provider calls (DataForSEO through callDataForSEOCached, then the LLM).
7. The response is written through to mv_seo_cache, saved to tool_results for the Library, and returned.
8. mvBumpMetrics records runs, duration, cache hit or miss and estimated provider cost into metrics_hourly. A failure additionally records a grouped fingerprint in error_issues.
9. mvTrackedFetch writes an activity_log row inside ctx.waitUntil, so it never delays the response.

The step-by-step version with every gate and its exact error body is in Request lifecycle.

Failure modes#

Two structural behaviors are worth internalising because they are not symmetrical:

• The quota gate fails closed. Any database error in enforceAiQuota returns 503 with code: "quota_check_failed" rather than letting the call through unmetered.
• The configuration layer fails open. mvConfigAll returns an empty map on error so that "no config means every default applies, tools stay on". During a D1 outage that also means suspended accounts are momentarily not suspended and every cache override disappears.

The complete open-versus-closed matrix is in Authentication and authorization flow.