How gigaag/wme-place-harmonizer-row-edition works
This repository is a Tampermonkey userscript that runs inside Waze Map Editor (WME) and augments the place-editing workflow with analysis, issue reporting, proposal generation, and optional manual application of supported fixes.
1) System context
The repo is one half of a two-repository system:
• This repository contains the executable userscript, UI, runtime logic, and WME integration.
• A companion data repository, wme-place-harmonizer-row-data, provides manifests, configuration, chains, locale files, and other reference data that this script loads at runtime.
So the architecture is not “app + backend” in the usual sense. It is:
• a browser userscript runtime,
• talking to WME through its SDK,
• loading remote data from the companion repository,
• persisting a small amount of local state in browser storage.
2) Top-level runtime flow
The main runtime path is:
1. Tampermonkey loads the generated userscript.
2. src/main.ts and src/app/start.ts bootstrap the app.
3. src/bootstrap/init.ts and src/bootstrap/guards.ts wait for the right WME and SDK conditions before the script activates.
4. Runtime config, locale data, and policy data are loaded from the companion repository through the config and i18n layers.
5. The app binds to WME selection and visible-venue events via src/integration/sdk/*.
6. Selected venues are analyzed, matched against chains and standards, and checked against rules.
7. Issues and proposals are pushed into:
- the WME feature editor integration,
- the script sidebar,
- the visible-venue highlighter.
8. If the user chooses a supported proposal, the script writes the selected change back to WME through the venue updater integration.
9. Local settings, cache, and whitelist decisions are stored in browser storage.
A key architectural rule, repeated in the README, is that the script does not make automatic edits. It surfaces recommendations and only applies changes when the user explicitly selects them.
3) Main subsystems
A. Bootstrap and application lifecycle
Files:
• src/main.ts
• src/app/start.ts
• src/bootstrap/init.ts
• src/bootstrap/guards.ts
• src/app/app-state.ts
• src/app/analysis-state.ts
This layer owns startup sequencing and app lifecycle state.
Its job is to:
• wait until WME and the SDK are ready,
• establish global app state,
• track analysis state for the current venue or scan,
• coordinate the rest of the subsystems.
This is the entry boundary between Tampermonkey/WME page lifecycle and the harmonizer logic.
B. WME integration layer
Files under src/integration/sdk/
This is the main adapter layer to WME. It isolates browser/WME-specific concerns from the business logic.
Important pieces include:
• venue selection and mapping:
- venue-selection.ts
- venue-mapper.ts
- venue-country.ts
- visible-venues.ts
• data updates back into WME:
- venue-updater.ts
- venue-save-scan.ts
• feature editor and sidebar integration:
- feature-editor.ts
- sidebar.ts
- external-provider-editor.ts
- external-provider-suggestions.ts
• scan automation:
- map-auto-scan.ts
• provider validation support:
- external-provider-validation*.ts
• WME SDK boundary:
- wme.ts
Conceptually, this layer translates between:
• WME’s venue objects, map state, and editor panels,
• and the script’s own normalized internal place model.
C. Analysis, matching, and proposal generation
Files:
• src/matching/*
• src/rules/*
• src/proposals/generate-proposals.ts
• src/app/analysis-state.ts
• src/types/*
This is the core “harmonizer” engine.
It includes:
• normalization of chain names and related values,
• matching venues to configured chains,
• evaluation of place data against standards and rules,
• proposal creation for supported corrections.
Notable rule areas visible in the tree:
• place evaluation:
- evaluate-place.ts
• formatting checks:
- phone-format.ts
- url-format.ts
The output of this layer is a structured set of:
• issues,
• severities,
• suggested values,
• and proposals that may be manually applied.
The src/types/ directory acts as the shared contract boundary for these results, defining things like:
• places,
• matches,
• proposals,
• issues,
• policies,
• manifests,
• settings,
• whitelist entries.
D. Configuration and runtime data loading
Files:
• src/config/*
• src/network/fetch-json.ts
• src/types/config.ts
• src/types/manifest.ts
• src/types/policy.ts
• src/types/chains.ts
This subsystem loads and merges runtime data from the companion data repository.
It handles:
• manifest loading,
• config loading,
• chain loading,
• merging of config overlays,
• runtime chain selection,
• country-specific overrides,
• effective policy resolution.
Important pieces:
• manifest-loader.ts
• config-loader.ts
• chain-loader.ts
• config-merger.ts
• chain-merger.ts
• runtime-config.ts
• runtime-chains.ts
• effective-policy.ts
• source.ts, config-source.ts
Architecturally, this is the data-input boundary. The script depends on published JSON-like reference data rather than hardcoding all standards into the userscript.
The README notes that:
• production builds read data from the data repo’s main branch and manifest/stable.json,
• beta and development builds read from the data repo’s dev branch and manifest/dev.json.
So the data channel is part of the runtime architecture, not just the build process.
E. Localization and internationalization
Files:
• src/i18n/locale-loader.ts
• src/i18n/locale-utils.ts
• src/i18n/runtime.ts
• src/types/i18n.ts
This subsystem loads locale resources and resolves the active UI locale.
The README states the precedence:
1. WME SDK locale,
2. data-side default locale,
3. English fallback.
That means localization is driven by runtime environment first, not by a hardcoded browser locale.
F. Settings, cache, and whitelist
Files:
• src/settings/*
• src/cache/cache-manager.ts
• src/whitelist/manager.ts
• src/constants/storage.ts
• src/constants/cache.ts
This is the local persistence layer.
It covers:
• user or build-specific settings,
• cached runtime data,
• local whitelist entries that suppress selected issues.
The README highlights that storage keys differ by release channel:
• development builds use WMEPH-ROW:dev:*
• beta builds use WMEPH-ROW:beta:*
• production builds use WMEPH-ROW:*
So the release channel affects persisted client-side state, which matters for diagramming the runtime boundaries.
G. UI presentation layer
Files:
• src/ui/feature-editor/*
• src/ui/sidebar/*
• src/highlighter/highlighter-manager.ts
This layer renders the analysis output into WME-facing UI surfaces.
It has two primary presentation paths:
• the WME feature editor panel,
• the script sidebar.
The feature editor side is more interactive and appears to handle:
• grouped issues,
• actions,
• rendering,
• external provider data.
The sidebar side provides a more concise status view and script-tab content.
The highlighter manager is separate from the panels and visually marks venues on the map based on scan or severity state.
H. Logging and diagnostics
Files:
• src/logging/logger.ts
• src/constants/build.ts
• src/constants/app.ts
This is a supporting subsystem for runtime observability and build/runtime metadata.
It likely records:
• load failures,
• fallback decisions,
• data source selection,
• analysis and validation errors.
The README specifically mentions graceful fallback when country-specific config or chain overlays fail to load.
4) Main data flows
Flow 1: selected venue analysis
Input:
• a currently selected WME venue
Path:
• WME SDK integration captures selection,
• venue is mapped into internal place types,
• config/chains/locale/policy data are loaded,
• matching and rules evaluate the venue,
• proposals are generated,
• UI panels render issues and suggestions.
Output:
• feature editor issues and actions,
• sidebar summary,
• optional whitelist suppression effects,
• possible manual updates back to WME.
Flow 2: visible-venue scan and highlighting
Input:
• current map viewport / visible venues
Path:
• SDK layer enumerates visible venues,
• app scans them,
• analysis state records status,
• highlighter manager colors them on the map,
• scan results can also be surfaced in the sidebar or feature editor.
This is a separate operational mode from single-selection analysis, but it uses the same evaluation engine.
Flow 3: user-applied fix
Input:
• a chosen proposal from the UI
Path:
• proposal is validated as supported,
• venue updater writes the change into WME,
• save/scan hooks may refresh state,
• UI updates to reflect the new analysis result.
Important constraint:
• only supported proposal types are applied.
Flow 4: runtime data loading and fallback
Input:
• manifest/config/chains/locales fetched from remote data repo
Path:
• fetch JSON,
• load manifest,
• merge runtime overlays,
• resolve country-specific config and effective policy,
• if overlays fail, fall back to global data and log the reason.
This flow is important because the system is highly data-driven and depends on external published reference data.
5) Important boundaries
Boundary: browser userscript vs WME page
This repo is not a standalone application. It is injected into the WME page by Tampermonkey and must coexist with the host application lifecycle.
Boundary: script logic vs WME SDK
The src/integration/sdk layer is the main adapter between internal models and WME-specific objects/events/UI.
Boundary: script logic vs external data repo
Configuration, standards, chains, manifests, and locale files live outside this repo and are fetched at runtime.
Boundary: analysis engine vs UI
The analysis and proposal engine produces structured results; the UI layers only render and collect user actions.
Boundary: supported vs unsupported edits
The system deliberately restricts itself to supported proposal types. It is a recommendation and assisted-edit tool, not an autonomous fixer.
Boundary: global vs country-specific behavior
Country overlays and policy resolution are optional. If they are unavailable, the script falls back to global defaults.
6) Build, packaging, and release architecture
Files:
• scripts/build-userscript.mjs
• .github/workflows/ci.yml
• package.json
• build/release docs in docs/*
The repository produces Tampermonkey-distributable .user.js artifacts, not a traditional deployable server bundle.
Release channels are separated:
• dev
• beta
• stable / production
CI verifies the branch and republishes artifacts to the appropriate distribution channel described in the README:
• beta-dist
• stable-dist
This matters architecturally because runtime behavior, storage keys, and remote data channel selection vary by release tier.
7) Test structure
The tests are organized around the subsystems rather than around a UI end-to-end flow.
Notable coverage areas:
• place evaluation rules,
• external provider validation/editor logic,
• feature editor grouping and actions,
• sidebar rendering,
• venue updating,
• whitelist behavior,
• runtime data loading,
• localization utilities.
This suggests a layered design where the business logic is mostly testable without WME, and the SDK/UI layers are thin adapters around that logic.
8) In one sentence
The repository implements a data-driven WME userscript with a bootstrap layer, a WME adapter layer, a rule-and-matching analysis engine, UI renderers for the feature editor and sidebar, local storage for settings/whitelist/cache, and a runtime configuration system that loads standards and locale data from an external companion repository.
Main entry points: wme.ts WME SDK · start.ts Start app · runtime-config.ts Runtime config · analysis-state.ts Analysis state
Components 34
Bootstrap
Userscript entrypoint and lifecycle gating.
- Entry · Tampermonkey entrypoint that starts the app.
src/main.ts - Start app · Initial app bootstrap and runtime wiring.
src/app/start.ts - Init · Waits for WME and SDK readiness before activation.
src/bootstrap/init.ts - Guards · Checks conditions required to safely run the script.
src/bootstrap/guards.ts - App state · Global runtime state for the script.
src/app/app-state.ts - Analysis state · Tracks the current venue or scan analysis results.
src/app/analysis-state.ts
WME Integration
Adapters around WME SDK, map events, editor panels, and writeback.
- WME SDK · Boundary to Waze Map Editor APIs and page state.
src/integration/sdk/wme.ts - Selection · Reads selected venue data from WME.
src/integration/sdk/venue-selection.ts - Mapper · Maps WME venue objects into internal place models.
src/integration/sdk/venue-mapper.ts - Visible venues · Enumerates venues currently visible on the map.
src/integration/sdk/visible-venues.ts - Updater · Applies supported changes back into WME.
src/integration/sdk/venue-updater.ts - Feature editor · Hooks into the WME feature editor panel.
src/integration/sdk/feature-editor.ts - Sidebar SDK · Hooks into the script sidebar and tab lifecycle.
src/integration/sdk/sidebar.ts - Auto scan · Triggers scanning of visible venues.
src/integration/sdk/map-auto-scan.ts
Analysis Engine
Matching, rules, and proposal generation.
- Matcher · Matches venues to configured chains and standards.
src/matching/chain-matcher.ts - Normalize · Normalizes chain and venue values for matching.
src/matching/normalize.ts - Evaluate · Evaluates a place against standards and rules.
src/rules/evaluate-place.ts - Proposals · Builds supported correction proposals from issues.
src/proposals/generate-proposals.ts - Phone rules · Validates phone number formatting.
src/rules/phone-format.ts - URL rules · Validates URL formatting.
src/rules/url-format.ts
Runtime Data
Remote configuration, chains, policies, and locale loading.
- Runtime config · Resolved configuration used by analysis and UI.
src/config/runtime-config.ts - Runtime chains · Effective chain data loaded at runtime.
src/config/runtime-chains.ts - Policy · Resolves country and build specific effective policy.
src/config/effective-policy.ts - Manifest loader · Loads the active data manifest from the companion repo.
src/config/manifest-loader.ts - Config loader · Loads overlay and runtime configuration data.
src/config/config-loader.ts - Chain loader · Loads chain definitions and related reference data.
src/config/chain-loader.ts - Locale runtime · Resolves the active UI locale and translations.
src/i18n/runtime.ts
Presentation
Feature editor, sidebar, and map highlighting.
- Editor view · Renders issues and actions in the feature editor.
src/ui/feature-editor/renderer.ts - Editor container · Coordinates feature editor state and composition.
src/ui/feature-editor/container.ts - Issue groups · Groups analysis issues for display.
src/ui/feature-editor/issue-groups.ts - Editor actions · Handles user actions from the feature editor.
src/ui/feature-editor/actions.ts - Sidebar view · Renders the sidebar summary and status.
src/ui/sidebar/renderer.ts - Script tab · Sidebar tab content for the harmonizer script.
src/ui/sidebar/script-tab.ts - Sidebar actions · Handles sidebar user interactions.
src/ui/sidebar/actions.ts
Connections 37
- Entry → Start app: bootstraps · Entry delegates startup to the app layer.
- Start app → Init: waits on · Startup waits for readiness gates.
- Start app → Guards: checks · Startup validates activation conditions.
- Start app → App state: creates · Initializes global app lifecycle state.
- Start app → Analysis state: tracks · Maintains current analysis state.
- Init → WME SDK: uses · Initialization depends on the WME SDK boundary.
- Selection → Mapper: normalizes · Selection is converted into the internal place model.
- Visible venues → Auto scan: feeds · Visible venues are used for scan automation.
- WME SDK → Selection: exposes · SDK layer provides selection events and data.
- WME SDK → Visible venues: exposes · SDK layer provides visible venue enumeration.
- WME SDK → Feature editor: hosts · WME feature editor integration is mounted through the SDK.
- WME SDK → Sidebar SDK: hosts · Sidebar integration is mounted through the SDK.
- Mapper → Runtime config: reads · Mapped venues are evaluated against active config.
- Mapper → Runtime chains: reads · Mapping feeds chain-aware matching.
- Runtime config → Manifest loader: loads via · Runtime config is resolved from manifest-driven data.
- Runtime config → Config loader: loads via · Config loader fetches and merges remote config.
- Runtime chains → Chain loader: loads via · Chain catalog is resolved from remote chain data.
- Runtime config → Policy: resolves · Effective policy is derived from runtime config.
- Runtime config → Locale runtime: selects · Runtime config contributes locale selection and fallbacks.
- Config loader → Matcher: supplies · Config and chain data feed matching.
- Matcher → Normalize: uses · Matching depends on normalization.
- Matcher → Evaluate: feeds · Matched places are evaluated by rules.
- Evaluate → Phone rules: checks · Evaluation includes phone formatting rules.
- Evaluate → URL rules: checks · Evaluation includes URL formatting rules.
- Evaluate → Proposals: produces · Rule results are converted into supported proposals.
- Proposals → Editor view: renders · Proposals and issues are surfaced in the editor UI.
- Proposals → Sidebar view: renders · Proposal summaries are surfaced in the sidebar UI.
- Editor view → Editor container: composes · Renderer is driven by the feature editor container.
- Editor container → Issue groups: groups · Issues are organized for display.
- Editor container → Editor actions: handles · Container wires user actions.
- Sidebar view → Script tab: composes · Sidebar rendering is organized around the script tab.
- Sidebar view → Sidebar actions: handles · Sidebar actions are wired into the renderer flow.
- Editor actions → Updater: applies · Supported user-selected fixes are written back to WME.
- Updater → WME SDK: writes to · Updater uses the SDK boundary to modify WME data.
- Analysis state → Editor view: drives · Current analysis state feeds the editor display.
- Analysis state → Sidebar view: drives · Current analysis state feeds the sidebar display.
- Analysis state → Visible venues: reflects · Scan state can reflect visible-venue analysis.