# hopechen067/mapstage architecture

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

- Interactive diagram: https://gitdiagram.com/hopechen067/mapstage
- Repository: https://github.com/hopechen067/mapstage

## Overview

MapStage is an interactive map-and-globe tuner, paired with an agent skill for applying exported styles. The main workflow is to tune projection, imagery, terrain and visual effects, then copy a JSON preset for an agent to apply to a map scene. Other documented capabilities include vector water, region isolation and city-tier settlements. The graph uses README-documented relationships and the sampled configuration and boundary-patching code; unsampled browser wiring is not inferred.

Main entry points: [`mapstage/tuner/index.html`](https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/index.html) (Interactive Tuner), [`mapstage/tuner/map-tiles.config.js`](https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/map-tiles.config.js) (Tile Configuration), [`mapstage/tuner/assets/water-pack.json`](https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/assets/water-pack.json) (Vector Water), [`mapstage/tuner/assets/region-isolate-data.js`](https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/assets/region-isolate-data.js) (Region Geometry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tuning["Map Tuner"]
  node_tuner["Interactive Tuner<br/>[index.html]"]
  node_tile_config["Tile Configuration"]
end

subgraph group_layers["Map Layers"]
  node_projection["Map / Globe<br/>[index.html]"]
  node_satellite["Satellite Basemap<br/>[index.html]"]
  node_terrain["Terrain Relief<br/>[index.html]"]
  node_water["Vector Water<br/>[water-pack.json]"]
  node_color_grade["CSS Color Grade<br/>[map-fx.js]"]
  node_isolation["Region Isolate<br/>[region-isolate.js]"]
  node_city_tiers["City Tiers<br/>[han-city-3d.js]"]
end

subgraph group_presets["Preset Workflow"]
  node_preset_export["JSON Preset Export<br/>[index.html]"]
  node_skill["MapStage Skill<br/>[SKILL.md]"]
  node_preset_schema["Preset Schema"]
end

subgraph group_geodata["Region Data"]
  node_region_data["Region Geometry"]
  node_boundary_patch["Boundary Builder"]
  node_island_patch["Island Regions"]
end

node_user(("Map Designer"))
node_eox["EOX Tiles"]
node_mapterhorn["Mapterhorn DEM"]
node_openfreemap["OpenFreeMap Water"]
node_agent(("Agent"))

node_user -->|"tunes map"| node_tuner
node_tuner -->|"offers projection"| node_projection
node_tuner -->|"offers basemap"| node_satellite
node_tuner -->|"offers terrain"| node_terrain
node_tuner -->|"offers water"| node_water
node_tuner -->|"offers grading"| node_color_grade
node_tuner -->|"offers isolation"| node_isolation
node_tuner -->|"offers settlements"| node_city_tiers
node_tile_config -->|"configures tiles"| node_eox
node_tile_config -->|"configures DEM"| node_mapterhorn
node_satellite -->|"fetches tiles"| node_eox
node_terrain -->|"fetches DEM"| node_mapterhorn
node_water -->|"uses vector layers"| node_openfreemap
node_tuner -->|"copies JSON"| node_preset_export
node_preset_export -->|"provides preset"| node_agent
node_agent -->|"applies style"| node_skill
node_preset_export -.->|"describes preset"| node_preset_schema
node_boundary_patch -->|"patches geometry"| node_region_data
node_island_patch -->|"writes regions"| node_region_data

click node_tuner "https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/index.html"
click node_tile_config "https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/map-tiles.config.js"
click node_projection "https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/index.html"
click node_satellite "https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/index.html"
click node_terrain "https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/index.html"
click node_water "https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/assets/water-pack.json"
click node_color_grade "https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/assets/map-fx.js"
click node_isolation "https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/assets/region-isolate.js"
click node_city_tiers "https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/assets/han-city-3d.js"
click node_preset_export "https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/index.html"
click node_skill "https://github.com/hopechen067/mapstage/blob/master/mapstage/SKILL.md"
click node_preset_schema "https://github.com/hopechen067/mapstage/blob/master/mapstage/schemas/map-preset.schema.json"
click node_region_data "https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/assets/region-isolate-data.js"
click node_boundary_patch "https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/scripts/patch-china-boundaries.mjs"
click node_island_patch "https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/scripts/patch-maritime-islands.mjs"

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_tuner,node_tile_config toneBlue
class node_projection,node_satellite,node_terrain,node_water,node_color_grade,node_isolation,node_city_tiers toneAmber
class node_preset_export,node_skill,node_preset_schema toneMint
class node_region_data,node_boundary_patch,node_island_patch toneRose
class node_user,node_eox,node_mapterhorn,node_openfreemap,node_agent toneIndigo
```

## Components

### Map Tuner

- [Interactive Tuner](https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/index.html): `mapstage/tuner/index.html`
- [Tile Configuration](https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/map-tiles.config.js): `mapstage/tuner/map-tiles.config.js`

### Map Layers

- [Map / Globe](https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/index.html): `mapstage/tuner/index.html`
- [Satellite Basemap](https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/index.html): `mapstage/tuner/index.html`
- [Terrain Relief](https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/index.html): `mapstage/tuner/index.html`
- [Vector Water](https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/assets/water-pack.json): `mapstage/tuner/assets/water-pack.json`
- [CSS Color Grade](https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/assets/map-fx.js): `mapstage/tuner/assets/map-fx.js`
- [Region Isolate](https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/assets/region-isolate.js): `mapstage/tuner/assets/region-isolate.js`
- [City Tiers](https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/assets/han-city-3d.js): `mapstage/tuner/assets/han-city-3d.js`

### Preset Workflow

- [JSON Preset Export](https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/index.html): `mapstage/tuner/index.html`
- [MapStage Skill](https://github.com/hopechen067/mapstage/blob/master/mapstage/SKILL.md): `mapstage/SKILL.md`
- [Preset Schema](https://github.com/hopechen067/mapstage/blob/master/mapstage/schemas/map-preset.schema.json): `mapstage/schemas/map-preset.schema.json`

### Region Data

- [Region Geometry](https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/assets/region-isolate-data.js): `mapstage/tuner/assets/region-isolate-data.js`
- [Boundary Builder](https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/scripts/patch-china-boundaries.mjs): `mapstage/tuner/scripts/patch-china-boundaries.mjs`
- [Island Regions](https://github.com/hopechen067/mapstage/blob/master/mapstage/tuner/scripts/patch-maritime-islands.mjs): `mapstage/tuner/scripts/patch-maritime-islands.mjs`

### Other components

- **Map Designer**
- **EOX Tiles**
- **Mapterhorn DEM**
- **OpenFreeMap Water**
- **Agent**

## Connections

- Map Designer → Interactive Tuner: tunes map (evidence: `README.md`)
- Interactive Tuner → Map / Globe: offers projection (evidence: `README.md`)
- Interactive Tuner → Satellite Basemap: offers basemap (evidence: `README.md`)
- Interactive Tuner → Terrain Relief: offers terrain (evidence: `README.md`)
- Interactive Tuner → Vector Water: offers water (evidence: `README.md`)
- Interactive Tuner → CSS Color Grade: offers grading (evidence: `README.md`)
- Interactive Tuner → Region Isolate: offers isolation (evidence: `README.md`)
- Interactive Tuner → City Tiers: offers settlements (evidence: `README.md`)
- Tile Configuration → EOX Tiles: configures tiles (evidence: `mapstage/tuner/map-tiles.config.js`)
- Tile Configuration → Mapterhorn DEM: configures DEM (evidence: `mapstage/tuner/map-tiles.config.js`)
- Satellite Basemap → EOX Tiles: fetches tiles (evidence: `README.md`)
- Terrain Relief → Mapterhorn DEM: fetches DEM (evidence: `README.md`)
- Vector Water → OpenFreeMap Water: uses vector layers (evidence: `README.md`)
- Interactive Tuner → JSON Preset Export: copies JSON (evidence: `README.md`)
- JSON Preset Export → Agent: provides preset (evidence: `README.md`)
- Agent → MapStage Skill: applies style (evidence: `README.md`)
- JSON Preset Export → Preset Schema: describes preset
- Boundary Builder → Region Geometry: patches geometry (evidence: `mapstage/tuner/scripts/patch-china-boundaries.mjs`)
- Island Regions → Region Geometry: writes regions (evidence: `mapstage/tuner/scripts/patch-maritime-islands.mjs`)
