Frontend architecture

Summary#

The customer application is a single HTML document. dashboard.html is 7,223,279 bytes and 64,435 lines, uses CRLF line endings, and contains 106 view containers, every one of them present in the DOM from first paint and shown or hidden by a client-side router. There is no framework, no bundler and no build step: the scripts in js/ are classic scripts, the stylesheets in css/ are plain CSS, and load order is source order.

That single-document design is the reason several things look unusual. Global window.* assignment is the module system. A <link> placed 31,000 lines into the body is how one stylesheet is made to beat another. And the twenty-four files in js/ were each lifted out of an inline <script> and re-linked at the exact position they occupied, so that parse and execution order survived the extraction.

Purpose#

The frontend serves one goal: a customer should be able to move between seventy tools without a page load, without losing state, and without the app feeling like seventy products. Everything below follows from that, plus the hard constraint that there is nothing to compile.

Keeping all 106 views in one document means switching tools costs a hidden attribute rather than a network round trip. The price is a very large file and a load order that must be respected. Extracting behavior into js/ reduces that file and makes the pieces independently reviewable, which is why the extraction rules are strict about not changing when anything runs.

The visual half of "one product, not seventy" is a separate topic with its own enforcement; see The design system.

Architecture#

  dashboard.html
    ├── #authOverlay              client-side gate, hidden once Supabase resolves
    └── .app  (CSS grid: 92px | 248px | 1fr)
         ├── aside.rail           12 section icons + hover flyout
         ├── aside.side           tool list for the active section, account block
         └── div.main             the only scroll container
              ├── header.topbar   back, favorites, notifications, search,
              │                   credits, country, range, theme, user menu
              ├── nav.mv-crumbs   Dashboard > Section > Tool
              └── 106 × div.view  exactly one visible at a time
                   ├── the tool's own inputs  ([data-in], button[data-run])
                   ├── div.mv-results[data-res]   the result container
                   └── div.mvte                   the tool explainer

The router#

A single IIFE owns navigation. It is plain history API work, no library.

goTo(v, push) lights up the rail, re-renders the section panel, marks the nav item active, sets the panel heading, renders breadcrumbs, hides every other .view, resets .main scroll to the top, then pushes or replaces history. Views with no section, reached only from in-app buttons, leave the sidebar alone but still record a route so a reload lands back on them.

Per-view lazy initialisation#

Views that need setup do it once, the first time they become visible. A MutationObserver per .view watches for the hidden attribute being removed and calls window.mvOnViewOpen(v), which runs that screen's init behind a mvIOnce guard. Screens wired this way include kmanager, cmanager, cmonitor, rank, team, scheduled, integrations, auto, myreports, history, account and dashboard.

The tool contract#

Every tool view shares three elements, and the delegated handlers depend on exactly these:

runToolButton(btn) is the generic runner. It refuses with Enter a value first. when the input is empty and Please sign in to run this tool. when there is no session, writes Analyzing… this can take a few seconds for live data. into the result container, scrolls it into view, then calls window.callTool or window.callPremiumAI depending on data-kind. On success it stashes the payload on view.__mvLastData, records a recent target, and hands off to window.mvRenderOld. A quota rejection renders Monthly limit reached — upgrade to continue. and anything else renders the escaped error or Something went wrong.

Renderer dispatch#

window.mvRenderOld(res, data, type, query) is the one entry point from a tool run to a rendered result. It adds class="mvx" to the result container and stamps data-theme on it, then walks a fixed chain and stops at the first match:

1. BES, a map of about forty tool types to a named premium renderer, called as W[name](res, data, opts) where opts is one of {idPrefix, query}, {idPrefix}, {query}, {brand}, or omitted.
2. AIINTEL (prompt_research, ai_competitor_research, brand_performance, ai_questions, prompt_tracking, media_monitoring) to mvRenderAiIntelPremium(type, res, data).
3. BATCH6 (ad_clarity, pla_research) to mvRenderBatch6Extras.
4. INLINE, twelve tools mapped to mv_inline_* functions.
5. mvRenderAny(res, data, {}), the generic JSON renderer.
6. A last-resort card reading No legacy renderer for <type>.

After every successful path a shared verified() step runs mvAttachVerifiedHeader and then mvGuideAttach, so the verified-source header and the Get Recommendations panel land on every tool without each renderer remembering to add them. How to write one of these correctly is Building a result renderer.

Result states#

Four states share one vocabulary across all tools: .mv-loading (with a spinner), .mv-error (red tinted), .mv-note (used for quota) and .mvr-empty. Several other components treat a container holding only one of those as "no result yet", which is how the export gate and the exec-summary tab bar avoid firing on a spinner.

Components#

Every file in js/#

Twenty-four scripts plus a vendored SDK. The convention, stated in js/README.md, is classic scripts only: no ES modules, no bundling, no top-level const or let, no side-effect IIFEs, and each file linked at the exact position of the <script> block it replaced.

Three more scripts live at the repository root rather than in js/: chat-widget.js (the assistant, one engine on three surfaces), pwa-install.js (the install banner) and blog-embed.js (the third-party embed). chatbot.js is a deliberate no-op stub, explained in Repository structure. mobile.css used to sit beside them, orphaned; it was removed along with index-legacy.html, the only page that still linked it.

Every file in css/#

Twenty-four stylesheets. Same convention: plain <link> tags, no preprocessor, each linked at the original position of the <style> block it replaced so the cascade is unchanged.

Data flow#

Load order in dashboard.html#

Cascade order is source order, and several rules depend on it. The positions below are exact.

js/mv-i18n-dict.<lang>.js never appears as a static tag. Both translation runtimes inject it lazily.

Theme#

The storage key is localStorage('mv-theme') with values dark and light, and the attribute is data-theme on <html>. Light is the default: tokens.css declares light in :root and puts dark behind [data-theme="dark"].

The dashboard is the one genuine exception to light-first. css/app.css re-declares :root with the dark palette and loads after tokens.css, so it wins, and light is restored by a [data-theme="light"] block plus roughly ninety-five component-level rules. That is safe only because the dashboard's boot script always writes an explicit data-theme. The toggle's label shows the target state: it reads Light while dark and Dark while light.

tests/theme-lint.mjs checks three things per page: that it loads css/tokens.css, that its boot script is inline in <head> before the first stylesheet, and that it declares no competing color variables. It covers nineteen pages and currently passes all nineteen.

Charts and canvas#

Canvas cannot read CSS custom properties, so every color reaching Chart.js goes through resolveColor(), which resolves var(--x) via getComputedStyle with a fallback. A color that skips it renders invisible or black. isDark() reads data-theme from <html> then <body> and defaults to dark when neither is set.

Failure modes#

Gates to run before committing frontend work#

node tests/design-lint.mjs                # no tracked count may rise
node tests/chkblk.mjs dashboard.html      # 0 broken inline script blocks
node tests/guard.mjs dashboard.html       # no </script> inside a template literal
node tests/site-chrome-sync.mjs           # public chrome drift check
node tests/theme-lint.mjs                 # every page on the shared theme system
node tests/i18n-wire.mjs --check          # every page wired for translation

Add node tests/login-inline-sync.mjs if login.html changed, and run the full translation pipeline if any user-visible string changed. Every script is described in Verification scripts.