# gigaag/wme-place-harmonizer-row-edition architecture

> Architecture diagram of the GitHub repository gigaag/wme-place-harmonizer-row-edition, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gigaag/wme-place-harmonizer-row-edition
- Repository: https://github.com/gigaag/wme-place-harmonizer-row-edition

## Overview

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: [`src/integration/sdk/wme.ts`](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/integration/sdk/wme.ts) (WME SDK), [`src/app/start.ts`](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/app/start.ts) (Start app), [`src/config/runtime-config.ts`](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/config/runtime-config.ts) (Runtime config), [`src/app/analysis-state.ts`](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/app/analysis-state.ts) (Analysis state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_bootstrap["Bootstrap"]
  node_main(("Entry<br/>[main.ts]"))
  node_app_start["Start app<br/>startup orchestrator<br/>[start.ts]"]
  node_bootstrap_init["Init<br/>wme readiness<br/>[init.ts]"]
  node_bootstrap_guards["Guards<br/>[guards.ts]"]
  node_app_state[("App state<br/>lifecycle state<br/>[app-state.ts]")]
  node_analysis_state[("Analysis state<br/>scan state<br/>[analysis-state.ts]")]
end

subgraph group_group_integration["WME Integration"]
  node_wme_sdk["WME SDK<br/>host adapter<br/>[wme.ts]"]
  node_venue_selection["Selection<br/>venue adapter<br/>[venue-selection.ts]"]
  node_venue_mapper["Mapper<br/>venue normalizer<br/>[venue-mapper.ts]"]
  node_visible_venues["Visible venues<br/>map scan adapter<br/>[visible-venues.ts]"]
  node_venue_updater["Updater<br/>writeback adapter<br/>[venue-updater.ts]"]
  node_feature_editor["Feature editor<br/>editor integration<br/>[feature-editor.ts]"]
  node_sidebar_sdk["Sidebar SDK<br/>panel integration<br/>[sidebar.ts]"]
  node_map_auto_scan["Auto scan<br/>scan automation<br/>[map-auto-scan.ts]"]
end

subgraph group_group_engine["Analysis Engine"]
  node_chain_matcher["Matcher<br/>chain matching<br/>[chain-matcher.ts]"]
  node_normalize["Normalize<br/>name normalization<br/>[normalize.ts]"]
  node_evaluate_place["Evaluate<br/>rule engine<br/>[evaluate-place.ts]"]
  node_proposals["Proposals<br/>proposal generator"]
  node_phone_format["Phone rules<br/>format rule<br/>[phone-format.ts]"]
  node_url_format["URL rules<br/>format rule<br/>[url-format.ts]"]
end

subgraph group_group_data["Runtime Data"]
  node_runtime_config[("Runtime config<br/>data config<br/>[runtime-config.ts]")]
  node_runtime_chains[("Runtime chains<br/>chain catalog<br/>[runtime-chains.ts]")]
  node_effective_policy["Policy"]
  node_manifest_loader["Manifest loader<br/>remote manifest<br/>[manifest-loader.ts]"]
  node_config_loader["Config loader<br/>remote config<br/>[config-loader.ts]"]
  node_chain_loader["Chain loader<br/>remote chains<br/>[chain-loader.ts]"]
  node_locale_runtime["Locale runtime<br/>i18n runtime<br/>[runtime.ts]"]
end

subgraph group_group_ui["Presentation"]
  node_feature_renderer["Editor view<br/>ui renderer<br/>[renderer.ts]"]
  node_feature_container["Editor container<br/>ui container<br/>[container.ts]"]
  node_issue_groups["Issue groups<br/>ui grouping<br/>[issue-groups.ts]"]
  node_feature_actions["Editor actions<br/>ui actions<br/>[actions.ts]"]
  node_sidebar_renderer["Sidebar view<br/>ui renderer<br/>[renderer.ts]"]
  node_sidebar_script_tab["Script tab<br/>ui tab<br/>[script-tab.ts]"]
  node_sidebar_actions["Sidebar actions<br/>ui actions<br/>[actions.ts]"]
end

subgraph group_group_state["Local State"]
end

node_main -->|"bootstraps"| node_app_start
node_app_start -->|"waits on"| node_bootstrap_init
node_app_start -->|"checks"| node_bootstrap_guards
node_app_start -->|"creates"| node_app_state
node_app_start -->|"tracks"| node_analysis_state
node_bootstrap_init -->|"uses"| node_wme_sdk
node_venue_selection -->|"normalizes"| node_venue_mapper
node_visible_venues -->|"feeds"| node_map_auto_scan
node_wme_sdk -->|"exposes"| node_venue_selection
node_wme_sdk -->|"exposes"| node_visible_venues
node_wme_sdk -->|"hosts"| node_feature_editor
node_wme_sdk -->|"hosts"| node_sidebar_sdk
node_venue_mapper -->|"reads"| node_runtime_config
node_venue_mapper -->|"reads"| node_runtime_chains
node_runtime_config -->|"loads via"| node_manifest_loader
node_runtime_config -->|"loads via"| node_config_loader
node_runtime_chains -->|"loads via"| node_chain_loader
node_runtime_config -->|"resolves"| node_effective_policy
node_runtime_config -->|"selects"| node_locale_runtime
node_config_loader -->|"supplies"| node_chain_matcher
node_chain_matcher -->|"uses"| node_normalize
node_chain_matcher -->|"feeds"| node_evaluate_place
node_evaluate_place -->|"checks"| node_phone_format
node_evaluate_place -->|"checks"| node_url_format
node_evaluate_place -->|"produces"| node_proposals
node_proposals -->|"renders"| node_feature_renderer
node_proposals -->|"renders"| node_sidebar_renderer
node_feature_renderer -->|"composes"| node_feature_container
node_feature_container -->|"groups"| node_issue_groups
node_feature_container -->|"handles"| node_feature_actions
node_sidebar_renderer -->|"composes"| node_sidebar_script_tab
node_sidebar_renderer -->|"handles"| node_sidebar_actions
node_feature_actions -->|"applies"| node_venue_updater
node_venue_updater -->|"writes to"| node_wme_sdk
node_analysis_state -->|"drives"| node_feature_renderer
node_analysis_state -->|"drives"| node_sidebar_renderer
node_analysis_state -->|"reflects"| node_visible_venues

click node_main "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/main.ts"
click node_app_start "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/app/start.ts"
click node_bootstrap_init "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/bootstrap/init.ts"
click node_bootstrap_guards "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/bootstrap/guards.ts"
click node_app_state "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/app/app-state.ts"
click node_analysis_state "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/app/analysis-state.ts"
click node_wme_sdk "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/integration/sdk/wme.ts"
click node_venue_selection "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/integration/sdk/venue-selection.ts"
click node_venue_mapper "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/integration/sdk/venue-mapper.ts"
click node_visible_venues "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/integration/sdk/visible-venues.ts"
click node_venue_updater "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/integration/sdk/venue-updater.ts"
click node_feature_editor "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/integration/sdk/feature-editor.ts"
click node_sidebar_sdk "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/integration/sdk/sidebar.ts"
click node_map_auto_scan "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/integration/sdk/map-auto-scan.ts"
click node_runtime_config "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/config/runtime-config.ts"
click node_runtime_chains "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/config/runtime-chains.ts"
click node_effective_policy "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/config/effective-policy.ts"
click node_manifest_loader "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/config/manifest-loader.ts"
click node_config_loader "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/config/config-loader.ts"
click node_chain_loader "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/config/chain-loader.ts"
click node_locale_runtime "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/i18n/runtime.ts"
click node_chain_matcher "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/matching/chain-matcher.ts"
click node_normalize "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/matching/normalize.ts"
click node_evaluate_place "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/rules/evaluate-place.ts"
click node_proposals "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/proposals/generate-proposals.ts"
click node_phone_format "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/rules/phone-format.ts"
click node_url_format "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/rules/url-format.ts"
click node_feature_renderer "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/ui/feature-editor/renderer.ts"
click node_feature_container "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/ui/feature-editor/container.ts"
click node_issue_groups "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/ui/feature-editor/issue-groups.ts"
click node_feature_actions "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/ui/feature-editor/actions.ts"
click node_sidebar_renderer "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/ui/sidebar/renderer.ts"
click node_sidebar_script_tab "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/ui/sidebar/script-tab.ts"
click node_sidebar_actions "https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/ui/sidebar/actions.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_app_start,node_bootstrap_init,node_bootstrap_guards,node_app_state,node_analysis_state toneBlue
class node_wme_sdk,node_venue_selection,node_venue_mapper,node_visible_venues,node_venue_updater,node_feature_editor,node_sidebar_sdk,node_map_auto_scan toneAmber
class node_chain_matcher,node_normalize,node_evaluate_place,node_proposals,node_phone_format,node_url_format toneMint
class node_runtime_config,node_runtime_chains,node_effective_policy,node_manifest_loader,node_config_loader,node_chain_loader,node_locale_runtime toneRose
class node_feature_renderer,node_feature_container,node_issue_groups,node_feature_actions,node_sidebar_renderer,node_sidebar_script_tab,node_sidebar_actions toneIndigo
```

## Components

### Bootstrap

Userscript entrypoint and lifecycle gating.

- [Entry](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/main.ts): userscript entry · Tampermonkey entrypoint that starts the app. · `src/main.ts`
- [Start app](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/app/start.ts): startup orchestrator · Initial app bootstrap and runtime wiring. · `src/app/start.ts`
- [Init](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/bootstrap/init.ts): wme readiness · Waits for WME and SDK readiness before activation. · `src/bootstrap/init.ts`
- [Guards](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/bootstrap/guards.ts): activation guards · Checks conditions required to safely run the script. · `src/bootstrap/guards.ts`
- [App state](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/app/app-state.ts): lifecycle state · Global runtime state for the script. · `src/app/app-state.ts`
- [Analysis state](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/app/analysis-state.ts): scan 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](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/integration/sdk/wme.ts): host adapter · Boundary to Waze Map Editor APIs and page state. · `src/integration/sdk/wme.ts`
- [Selection](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/integration/sdk/venue-selection.ts): venue adapter · Reads selected venue data from WME. · `src/integration/sdk/venue-selection.ts`
- [Mapper](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/integration/sdk/venue-mapper.ts): venue normalizer · Maps WME venue objects into internal place models. · `src/integration/sdk/venue-mapper.ts`
- [Visible venues](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/integration/sdk/visible-venues.ts): map scan adapter · Enumerates venues currently visible on the map. · `src/integration/sdk/visible-venues.ts`
- [Updater](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/integration/sdk/venue-updater.ts): writeback adapter · Applies supported changes back into WME. · `src/integration/sdk/venue-updater.ts`
- [Feature editor](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/integration/sdk/feature-editor.ts): editor integration · Hooks into the WME feature editor panel. · `src/integration/sdk/feature-editor.ts`
- [Sidebar SDK](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/integration/sdk/sidebar.ts): panel integration · Hooks into the script sidebar and tab lifecycle. · `src/integration/sdk/sidebar.ts`
- [Auto scan](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/integration/sdk/map-auto-scan.ts): scan automation · Triggers scanning of visible venues. · `src/integration/sdk/map-auto-scan.ts`

### Analysis Engine

Matching, rules, and proposal generation.

- [Matcher](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/matching/chain-matcher.ts): chain matching · Matches venues to configured chains and standards. · `src/matching/chain-matcher.ts`
- [Normalize](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/matching/normalize.ts): name normalization · Normalizes chain and venue values for matching. · `src/matching/normalize.ts`
- [Evaluate](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/rules/evaluate-place.ts): rule engine · Evaluates a place against standards and rules. · `src/rules/evaluate-place.ts`
- [Proposals](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/proposals/generate-proposals.ts): proposal generator · Builds supported correction proposals from issues. · `src/proposals/generate-proposals.ts`
- [Phone rules](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/rules/phone-format.ts): format rule · Validates phone number formatting. · `src/rules/phone-format.ts`
- [URL rules](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/rules/url-format.ts): format rule · Validates URL formatting. · `src/rules/url-format.ts`

### Runtime Data

Remote configuration, chains, policies, and locale loading.

- [Runtime config](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/config/runtime-config.ts): data config · Resolved configuration used by analysis and UI. · `src/config/runtime-config.ts`
- [Runtime chains](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/config/runtime-chains.ts): chain catalog · Effective chain data loaded at runtime. · `src/config/runtime-chains.ts`
- [Policy](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/config/effective-policy.ts): policy resolver · Resolves country and build specific effective policy. · `src/config/effective-policy.ts`
- [Manifest loader](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/config/manifest-loader.ts): remote manifest · Loads the active data manifest from the companion repo. · `src/config/manifest-loader.ts`
- [Config loader](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/config/config-loader.ts): remote config · Loads overlay and runtime configuration data. · `src/config/config-loader.ts`
- [Chain loader](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/config/chain-loader.ts): remote chains · Loads chain definitions and related reference data. · `src/config/chain-loader.ts`
- [Locale runtime](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/i18n/runtime.ts): i18n runtime · Resolves the active UI locale and translations. · `src/i18n/runtime.ts`

### Presentation

Feature editor, sidebar, and map highlighting.

- [Editor view](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/ui/feature-editor/renderer.ts): ui renderer · Renders issues and actions in the feature editor. · `src/ui/feature-editor/renderer.ts`
- [Editor container](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/ui/feature-editor/container.ts): ui container · Coordinates feature editor state and composition. · `src/ui/feature-editor/container.ts`
- [Issue groups](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/ui/feature-editor/issue-groups.ts): ui grouping · Groups analysis issues for display. · `src/ui/feature-editor/issue-groups.ts`
- [Editor actions](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/ui/feature-editor/actions.ts): ui actions · Handles user actions from the feature editor. · `src/ui/feature-editor/actions.ts`
- [Sidebar view](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/ui/sidebar/renderer.ts): ui renderer · Renders the sidebar summary and status. · `src/ui/sidebar/renderer.ts`
- [Script tab](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/ui/sidebar/script-tab.ts): ui tab · Sidebar tab content for the harmonizer script. · `src/ui/sidebar/script-tab.ts`
- [Sidebar actions](https://github.com/gigaag/wme-place-harmonizer-row-edition/blob/main/src/ui/sidebar/actions.ts): ui actions · Handles sidebar user interactions. · `src/ui/sidebar/actions.ts`

## Connections

- 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.
