# kaiju-no-9/mlab-speedtest architecture

> Architecture diagram of the GitHub repository kaiju-no-9/mlab-speedtest, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kaiju-no-9/mlab-speedtest
- Repository: https://github.com/kaiju-no-9/mlab-speedtest

## Overview

##### What this project is (type + purpose)
This repo is a **static, client-side AngularJS (1.x) web application** that powers **https://speed.measurementlab.net** (“mlab-speedtest”). There is **no backend service in this repo**; the “system” is primarily:
- A browser SPA + static assets
- A build step (Gulp) that prepares localization artifacts
- A deployment pipeline (GitHub Actions) that publishes to **Firebase Hosting**

Key top-level items and what they imply:

##### Runtime (what runs in production)
- `app/` — the entire deployed site root for Firebase Hosting
- `app/index.html` + `app/app.js` — AngularJS app entrypoints
- `app/services/gaugeService.js` — client-side service module (core UI logic)
- `app/measure/measure.html`, `app/measure/measure.js` — a feature/module page
- `app/assets/` — CSS/JS/images/fonts used by the SPA
- `app/assets/translations/*.js` — generated/checked-in translation JS consumed at runtime
- `app/<lang>/index.html` — per-language entry HTML wrappers (routing-by-path / localized bootstrap)
- `app/404.html` — SPA/static hosting fallback behavior

##### Build-time (what transforms sources before deploy)
- `gulpfile.js` — build automation; README says it “integrate[s] language localizations prior to deployment”
- `translations/source/application.pot` — translation template
- `translations/languages/*.po` — language catalogs
- `package.json` — Node/Gulp dependencies and scripts

##### Deploy-time (how it gets published)
- `firebase.json`, `.firebaserc` — Firebase Hosting configuration, site target(s)
- `.github/workflows/firebase-hosting-*.yml` — CI/CD to Firebase Hosting (PR sandbox + prod on merge)

##### README cues to include explicitly
- Angular.js app; deployed on Firebase Hosting
- Gulp is used specifically for **localization integration** (e.g., `gulp inject`, `gulp copy_libs`)
- Two environments:
- PR-triggered sandbox: `mlab-sandbox.web.app`
- main-merge production: `speed.measurementlab.net`
- Local preview via simple static server ⇒ confirms it’s static hosting + client-side logic

##### Firebase Hosting → Browser: returns HTML/CSS/JS/fonts/images
3. **Browser loads AngularJS SPA**: `index.html` bootstraps Angular; includes `assets/js/*` and chosen `assets/translations/<lang>.js`

##### Runtime behavior
4. **AngularJS SPA → External Measurement Endpoints**: XHR/fetch/WebSocket (whatever code uses) to run speed measurements
##### External endpoints → SPA: returns measurement data
6. **SPA → UI rendering**: updates gauge/visuals (tie to `gaugeService.js` and measure module)

##### Localization build flow
7. **Transifex (optional) → repo**: translators produce `.po` → downloaded into `translations/...`
8. **Gulp inject/build → app/assets/translations/*.js and per-language index updates**: show as “build outputs”
9. **GitHub Actions → Firebase Hosting**: deploys built/static content based on branch/PR triggers

##### Architecture patterns/design principles present
- **Static-site + SPA architecture** (no server-side rendering in this repo)
- **Build-time localization compilation/injection** (PO/POT → JS translation bundles)
- **Environment-based deployment** (Sandbox vs Production via CI triggers)
- **Separation of concerns inside app/**
- `services/` for business/UI services
- `measure/` as a feature module/page
- `assets/` for static resources

##### Technologies/frameworks that matter
- **AngularJS 1.x**
- **Gulp + Node (>=10.15.1)** build tooling
- **Firebase Hosting** (static hosting + routing rules)
- **GitHub Actions** (CI/CD)
- **gettext-style translations** (`.po`, `.pot`) and generated JS bundles
- (Optional) **Transifex** (localization management upstream)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Client / Runtime Layer
    %% =========================
    subgraph "Client / Runtime (Browser)"
        U["User Browser"]:::external

        subgraph "AngularJS SPA (runtime in browser)"
            IDX["HTML Bootstrap (index.html)"]:::runtimeDoc
            APP["App Core (AngularJS 1.x)"]:::runtime
            MEASURE["Measure Feature Module"]:::runtime
            GAUGE["Gauge/UI Logic Service"]:::runtime
            HELPERS["Static JS Helpers"]:::runtime
            I18NRT["Localization Runtime"]:::runtimeDoc
            ASSETS["Static Assets (CSS/Images/Fonts)"]:::runtime
        end

        IDX -->|"bootstraps"| APP
        APP -->|"routes_to"| MEASURE
        MEASURE -->|"uses"| GAUGE
        APP -->|"loads"| HELPERS
        APP -->|"loads"| I18NRT
        APP -->|"uses"| ASSETS
    end

    %% =========================
    %% Hosting / Delivery Layer
    %% =========================
    subgraph "Hosting / Delivery"
        DOMAINPROD["Production Domain\nspeed.measurementlab.net"]:::infra
        DOMAINSBX["Sandbox Domain\nmlab-sandbox.web.app"]:::infra
        FBHOST["Firebase Hosting"]:::infra
        FBCONFIG["Hosting Config\n(firebase.json / .firebaserc)"]:::infraDoc
        FBFALLBACK["SPA Fallback (404.html)"]:::infraDoc
    end

    U -->|"HTTP_GET /index.html_or_/<lang>/index.html"| FBHOST
    DOMAINPROD -->|"routes_to"| FBHOST
    DOMAINSBX -->|"routes_to"| FBHOST
    FBCONFIG -->|"configures"| FBHOST
    FBHOST -->|"serves_static_assets"| IDX
    FBHOST -->|"serves_static_assets"| ASSETS
    FBHOST -->|"serves_static_assets"| I18NRT
    FBHOST -->|"fallback_to"| FBFALLBACK

    %% =========================
    %% External Dependencies
    %% =========================
    subgraph "External Systems (not in this repo)"
        MLAB["M-Lab / Measurement Endpoints\n(Speed test servers/APIs)"]:::externalDashed
        TX["Transifex Localization Lab (optional upstream)"]:::externalDashed
    end

    APP -->|"run_speed_test_requests"| MLAB
    MLAB -->|"measurement_results"| APP

    %% =========================
    %% Build + Content Pipeline Layer
    %% =========================
    subgraph "Build + CI/CD + Localization Pipeline"
        subgraph "Localization Sources"
            POT["Translation Template (.pot)"]:::buildDoc
            PO["Language Catalogs (.po)"]:::buildDoc
        end

        subgraph "Build Tooling (Node + Gulp)"
            PKG["Node Manifest (package.json)"]:::buildDoc
            GULP["Gulp Build (gulpfile.js)\nTasks: copy_libs, inject"]:::build
            GENI18N["Generated Translation JS\n(app/assets/translations/*.js)"]:::buildDoc
            LANGPAGES["Per-language Bootstrap Pages\n(app/<lang>/index.html)"]:::buildDoc
        end

        subgraph "CI/CD (GitHub Actions)"
            GHPR["Workflow: PR → Deploy Sandbox"]:::ci
            GHMERGE["Workflow: Merge → Deploy Production"]:::ci
        end
    end

    TX -.->|"export_translations"| PO
    POT -->|"basis_for"| PO
    PO -->|"input_to"| GULP
    POT -->|"input_to"| GULP
    PKG -->|"scripts_deps_for"| GULP
    GULP -->|"generates"| GENI18N
    GULP -->|"updates"| LANGPAGES

    GHPR -->|"build_and_deploy"| FBHOST
    GHMERGE -->|"build_and_deploy"| FBHOST
    GULP -->|"artifact_for_deploy"| FBHOST
    GENI18N -->|"served_as"| I18NRT
    LANGPAGES -->|"served_as"| IDX

    %% =========================
    %% Click Events (from component_mapping)
    %% =========================
    click IDX "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/app/index.html"
    click APP "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/app/app.js"
    click MEASURE "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/app/measure/measure.js"
    click GAUGE "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/app/services/gaugeService.js"
    click HELPERS "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/app/assets/js/main.js"
    click HELPERS "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/app/assets/js/util.js"
    click ASSETS "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/app/assets/css/main.css"
    click ASSETS "https://github.com/kaiju-no-9/mlab-speedtest/tree/main/app/assets/fonts/"
    click ASSETS "https://github.com/kaiju-no-9/mlab-speedtest/tree/main/app/assets/images/"
    click ASSETS "https://github.com/kaiju-no-9/mlab-speedtest/tree/main/app/assets/css/images/"
    click I18NRT "https://github.com/kaiju-no-9/mlab-speedtest/tree/main/app/assets/translations/"
    click LANGPAGES "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/app/az/index.html"
    click LANGPAGES "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/app/de/index.html"
    click LANGPAGES "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/app/el/index.html"
    click LANGPAGES "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/app/es/index.html"
    click LANGPAGES "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/app/fa/index.html"
    click LANGPAGES "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/app/fr/index.html"
    click LANGPAGES "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/app/hi/index.html"
    click LANGPAGES "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/app/id/index.html"
    click LANGPAGES "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/app/nl/index.html"
    click LANGPAGES "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/app/ru/index.html"
    click LANGPAGES "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/app/zh/index.html"
    click FBFALLBACK "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/app/404.html"
    click PO "https://github.com/kaiju-no-9/mlab-speedtest/tree/main/translations/languages/"
    click POT "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/translations/source/application.pot"
    click GULP "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/gulpfile.js"
    click PKG "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/package.json"
    click FBCONFIG "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/firebase.json"
    click FBCONFIG "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/.firebaserc"
    click GHPR "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/.github/workflows/firebase-hosting-pull-request.yml"
    click GHMERGE "https://github.com/kaiju-no-9/mlab-speedtest/blob/main/.github/workflows/firebase-hosting-merge.yml"

    %% =========================
    %% Styles
    %% =========================
    classDef runtime fill:#1f77b4,stroke:#0b3558,color:#ffffff,stroke-width:1.2px
    classDef runtimeDoc fill:#4aa3df,stroke:#0b3558,color:#ffffff,stroke-width:1.2px
    classDef infra fill:#2ca02c,stroke:#145214,color:#ffffff,stroke-width:1.2px
    classDef infraDoc fill:#66c266,stroke:#145214,color:#ffffff,stroke-width:1.2px
    classDef build fill:#ff7f0e,stroke:#7a3b00,color:#ffffff,stroke-width:1.2px
    classDef buildDoc fill:#ffae6b,stroke:#7a3b00,color:#1b1b1b,stroke-width:1.2px
    classDef ci fill:#f39c12,stroke:#7a3b00,color:#ffffff,stroke-width:1.2px
    classDef external fill:#7f8c8d,stroke:#4b5556,color:#ffffff,stroke-width:1.2px
    classDef externalDashed fill:#7f8c8d,stroke:#4b5556,color:#ffffff,stroke-width:1.2px,stroke-dasharray:5 4
```
