# Map Armenia Layer Specification Version: 2026-06-28 Owner: Ararat Lab / AP Map Armenia Scope: Republic of Armenia thematic maps only. Wider Armenian cultural geography remains in the Armenian World Historical Atlas and the Armenian Cultural Heritage Atlas. ## Product standard Map Armenia is not a generic layer switcher. It is a thematic atlas room for the Republic of Armenia. Every layer must answer five questions for the user: 1. What is visible? 2. What is the measured or classified value? 3. What unit is used? 4. What geography and period does it describe? 5. What source profile supports the layer? Public popups must show readable facts. Technical import labels, raw field names, source acronyms, and processing notes belong in Ararat Lab, not inside every map popup. ## Required layer contract Each thematic layer must have these fields in the layer manifest: | Field | Purpose | |---|---| | `id` | Stable layer identifier used by the viewer and Rust API. | | `title` | Public map title. | | `category` | Atlas section: base, geology-risk, climate-water, land-agriculture, economy, population, heritage. | | `coverage` | Must be `Republic of Armenia` unless explicitly marked as a handoff layer. | | `period` | Temporal coverage or observation period. | | `geometry_family` | `polygon`, `point`, `line`, `grid`, `mixed`, or `raster/vector-tile target`. | | `display_mode` | How the layer should render: choropleth, categorical symbols, proportional symbols, heat/grid, line network, reference outline. | | `unit` | Public measurement unit, such as meters, Celsius, millimeters, magnitude, people/km2. | | `legend_type` | Continuous ramp, categorical legend, proportional legend, or class breaks. | | `popup_template` | Public fact fields shown in selected feature panel. | | `source_label` | Public source label, usually `Ararat Lab`. | | `source_profile` | Where detailed source notes live. | | `confidence_rule` | How uncertainty is described without cluttering the map. | | `performance_rule` | Whether loaded as GeoJSON, API chunk, vector tiles, or PMTiles. | | `upgrade_target` | Next data improvement needed for world-class quality. | ## Public popup standard A selected feature should use this order: 1. Name or class label. 2. Map-specific value and unit. 3. Place or administrative context. 4. Period or observation year. 5. Short interpretation sentence. 6. Source: Ararat Lab. 7. Link: Open source profile. Forbidden in public popups: - raw terms such as `adm1`, `grid_cell`, `external_source_record`, `osm_id`, `wikidata_candidate`; - long import paths; - repeated source acronyms when a clean source link is enough; - internal pipeline notes. ## Cartographic rules - Armenia boundary must be shown as one clean mainland state outline without enclave/exclave holes. - Outside Armenia should remain muted and non-competitive: no foreign city labels, no strong country names, no bright external boundaries. - Polygons must not block point selection. Boundary and choropleth fills should use low opacity and be below point and line layers. - Every category must have visually distinct colors. Marzes must not share the same visible color. - Continuous physical layers should use ramps, not random categorical colors. - Scientific maps should prefer measured values over decorative symbols. - Dense point layers must cluster, simplify, or load by viewport/zoom. ## Priority layer program ### 1. Administrative Map of the Republic of Armenia Goal: clean reference map of state boundary, marzes, Yerevan, and communities. Required display: - Marz polygons with distinct colors. - Armenia state outline in AP gold. - Community layer optional at higher zoom. - No enclave/exclave holes in public view. Public units: - Area: km2. - Population: people, when available. Popup facts: - Region name. - Administrative type. - Center. - Area. - Population. - Source: Ararat Lab. Upgrade target: - Add official RA community attributes, administrative centers, area, population, and ISO-style codes. ### 2. Physical Map of Armenia Goal: terrain comprehension without visual clutter. Required display: - Elevation classes. - Major relief zones. - Mountain labels and significant peaks at high zoom. Public units: - Elevation: meters. Popup facts: - Terrain class. - Elevation range. - Representative elevation. - Region. Upgrade target: - Replace point grid with vector-tile or raster terrain classes derived from DEM. ### 3. Hypsometric Map Goal: professional elevation-band map comparable to printed thematic atlases. Required display: - Class breaks: 0-800 m, 800-1200 m, 1200-1800 m, 1800-2500 m, 2500+ m. - Smooth ramp from lowland warm tones to high mountain cold tones. Public units: - Meters above sea level. Upgrade target: - Generate clipped DEM-derived contour and hypsometric vector tiles. ### 4. Geological Map Goal: geological interpretation, not decorative geology. Required display: - Lithological polygons when reliable source is acquired. - Faults and mineral records as separate toggles. - No pseudo-geology grid if a real layer is not available. Public units: - Geological period / formation class. Upgrade target: - Acquire authoritative lithological polygons, normalize legend, and add cross-section references. ### 5. Tectonic Map Goal: active faults and tectonic structure. Required display: - Fault lines by activity/confidence class. - Direction or slip type where available. Public units: - Fault type, slip rate if available. Upgrade target: - Add national seismic zoning and fault metadata from specialist catalogs. ### 6. Earthquake Map Goal: real seismic history and risk reading. Required display: - Epicenters by magnitude. - Depth classes. - Date/time on popup. - Optional heat/density view. Public units: - Magnitude, depth km, year/date. Upgrade target: - Add regional historical earthquake catalog and live/recent feed separation. ### 7. Mineral Resources Map Goal: natural-resource geography without overclaiming economic status. Required display: - Mines, deposits, occurrences, and commodity groups. - Distinguish active site, historical site, occurrence, and review candidate. Public units: - Commodity class; status where available. Upgrade target: - Add RA official mineral cadastre fields if obtainable. ### 8. Climate Regions Goal: Armenia climate zones as map classes. Required display: - Zone polygons or model grid. - Region labels and short climate description. Public units: - Climate class. Upgrade target: - Replace regular sample points with continuous climate-zone polygons. ### 9. January Temperature Goal: winter temperature geography. Required display: - Continuous ramp in Celsius. - Low/high legend. Public units: - Degrees Celsius. Upgrade target: - Add 30-year climate-normal period and interpolation metadata. ### 10. July Temperature Goal: summer temperature geography. Required display: - Continuous ramp in Celsius. - Low/high legend. Public units: - Degrees Celsius. Upgrade target: - Add 30-year climate-normal period and interpolation metadata. ### 11. Precipitation Goal: precipitation distribution. Required display: - Annual or monthly precipitation classes. - Unit must be visible in legend. Public units: - Millimeters. Upgrade target: - Add annual/monthly mode and station-model comparison if available. ### 12. Snow Cover Goal: winter/snow geography. Required display: - Snow-climate classes or days with snow cover. Public units: - Days/year or index value; if modeled, call it an index. Upgrade target: - Replace proxy grid with snow-cover climatology or remote-sensing product. ### 13. Winds Goal: wind exposure and energy-relevant geography. Required display: - Wind speed classes. - Direction arrows only if direction data is present. Public units: - m/s. Upgrade target: - Add seasonal wind speed and elevation-aware interpolation. ### 14. River Network Goal: hydrological network. Required display: - Rivers by order or importance. - Lakes/reservoirs separate. - Line weight by stream class. Public units: - Name, class, length when available. Upgrade target: - Add basin names and river order classification. ### 15. Lake Sevan Goal: focused Sevan basin and lake context. Required display: - Lake polygon. - Tributaries, nearby settlements, protected areas, hydrological context. Public units: - Area, elevation, water body type. Upgrade target: - Add historical water-level change if reliable data is available. ### 16. Groundwater Goal: water infrastructure and groundwater-related public features. Required display: - Springs, wells, pumping stations, drinking-water infrastructure. Public units: - Feature type and status. Upgrade target: - Add hydrogeological basin polygons and aquifer class data. ### 17. Soils Goal: soil geography. Required display: - Soil property classes, not generic dots. Public units: - Soil class, organic carbon, pH, texture, or selected parameter. Upgrade target: - Convert SoilGrids samples to interpolated class surfaces or vector tiles. ### 18. Vegetation Goal: land-cover and vegetation classes. Required display: - Natural/landuse classes with readable colors. - Avoid every OSM tag as separate legend item. Public units: - Land-cover class. Upgrade target: - Add Copernicus/ESA land-cover source for consistent categories. ### 19. Forests Goal: forest geography. Required display: - Forest polygons and forest-related land cover. - Optional protected forest areas. Public units: - Forest type/status if available. Upgrade target: - Add national forest inventory or high-quality land-cover classification. ### 20. Agricultural Crops Goal: agricultural land and crop geography. Required display: - Crop/landuse classes, irrigation where available. Public units: - Crop class or landuse type. Upgrade target: - Add official agricultural statistics by marz/community. ### 21. Viticulture Goal: grape and wine geography. Required display: - Vineyards, wine regions, wineries where available. Public units: - Vineyard/winery type; elevation when useful. Upgrade target: - Add wine-region classification and production context. ### 22. Horticulture Goal: orchard and fruit-growing geography. Required display: - Orchards and horticulture landuse. Public units: - Crop/landuse type. Upgrade target: - Add official orchard area by community or marz. ### 23. Livestock Goal: livestock geography. Required display: - Livestock facilities, pastures, veterinary/infrastructure where available. Public units: - Facility type or density if official data is available. Upgrade target: - Add statistical livestock counts by marz/community. ### 24. Industry Goal: industrial geography. Required display: - Industrial points by sector. - Major industrial zones when available. Public units: - Sector and facility type. Upgrade target: - Add official enterprise/sector geography and industrial zone boundaries. ### 25. Electric Power and Utility Infrastructure Goal: energy infrastructure. Required display: - Power plants, substations, lines, transmission class. Public units: - Voltage, facility type, capacity if available. Upgrade target: - Add energy capacity and ownership/status fields. ### 26. Mining Industry Goal: mining economy, separate from mineral occurrence. Required display: - Mines and processing facilities by commodity/status. Public units: - Commodity, operation status. Upgrade target: - Add RA mining licenses and active/inactive status. ### 27. Transport Goal: roads, railways, airports, corridors. Required display: - Roads by class. - Railways separate. - Airports/terminals separate. Public units: - Class, route type, status. Upgrade target: - Add route hierarchy, international corridors, tunnels, bridges, and border crossings. ### 28. Population Density Goal: population distribution. Required display: - Density grid or choropleth. - Cities/settlements optional as overlay. Public units: - People/km2. Upgrade target: - Add census period and official marz/community population tables. ### 29. National Composition Goal: ethnicity/national composition with caution. Required display: - Must be official/statistical; avoid symbolic or single-point simplification. Public units: - Percent or people by group. Upgrade target: - Add official census table by marz/community. Until then, keep conservative. ### 30. Cities and Settlements Goal: settlement hierarchy. Required display: - Capital, cities, towns, villages, settlement points. - Symbol size by population when available. Public units: - Population, type, marz/community. Upgrade target: - Add official settlement population and coordinates. ### 31. Public Institutions and Landmarks Goal: public geography and civic landmarks. Required display: - Schools, hospitals, government buildings, cultural sites, public offices by category. Public units: - Institution category. Upgrade target: - Separate civic services, education, health, culture, and tourism into sublayers. ### 32. Armenian Heritage and Architecture Goal: handoff layer from Map Armenia to heritage atlases. Required display: - Only Armenia-room preview records here. - Full heritage geography belongs to Armenian Cultural Heritage Atlas and Armenian World Historical Atlas. Public units: - Heritage type, period, source profile. Upgrade target: - Keep this as a curated bridge, not a replacement for the full heritage map. ## Rust API target The viewer should be able to operate through these stable calls: | Endpoint action | Purpose | |---|---| | `armenia_room_index` | Returns layer list, section structure, titles, descriptions, counts, and public status. | | `armenia_room_layer` | Returns a selected layer by `id`, optionally filtered by bbox and zoom. | | `armenia_room_feature` | Returns one feature record by stable ID for deep links and record panels. | | `armenia_room_sources` | Returns source-profile summaries for Ararat Lab. | | `armenia_room_legend` | Returns color classes, units, and legend labels for a selected layer. | ## Performance targets | Data size | Recommended delivery | |---|---| | Under 5,000 features | Rust API GeoJSON. | | 5,000-50,000 features | Rust API by bbox/zoom or simplified GeoJSON chunks. | | Over 50,000 features | Vector tiles or PMTiles. | | Continuous surfaces | Raster tiles or derived vector class polygons. | | Heavy historical/source records | Database-backed API with viewport filtering. | ## Immediate build priorities 1. Convert every popup to public language and remove remaining service/import labels. 2. Add `unit`, `legend_type`, `display_mode`, and `popup_template` to the layer contract. 3. Upgrade administrative map with clean marz facts: area, center, population. 4. Upgrade physical/hypsometric maps from point grids to DEM-derived class surfaces. 5. Add proper continuous legends for temperature, precipitation, wind, snow, and population density. 6. Add clustering/viewport loading for dense OSM-derived layers. 7. Add Ararat Lab source cards for every layer family. 8. Prepare PostGIS schema for layer families, feature records, source profiles, and geometry simplification.