Your Ecological Address (YEA) — System Specification

A Multi-Source Ecological Profiling Engine for Any Location on Earth

Document ID: CNL-TN-2026-025
Version: 3.1
Date: March 5, 2026
Author: Michael P. Hamilton, Ph.D.

AI Assistance Disclosure: This technical note was developed with assistance from Claude (Anthropic). The AI contributed to system documentation, API reference compilation, file structure analysis, and manuscript drafting based on the author's working codebase and architectural decisions. The author takes full responsibility for the content, accuracy, and conclusions.

Abstract

Your Ecological Address (YEA) is a web application that transforms geographic coordinates into comprehensive ecological profiles by querying 20+ geospatial and biodiversity APIs in parallel. Given any latitude and longitude on Earth, the system returns a structured ecological identity spanning terrain morphometry, bedrock geology and stratigraphy, climate classification, multi-decadal climate history, water balance and evapotranspiration, ecoregion taxonomy, land cover characterization, vegetation community classification, conservation-listed species, land protection status, multi-taxon biodiversity inventories, seasonal phenology, recent avian field observations, and acoustic bird detections.

The interface is organized as a field guide with six thematic panels — Identity, Curated Discovery, Physical Place, Ecological Setting, Living Systems, and Field Notebook — each containing expandable data cards. A Curated Places layer provides enriched ecological profiles for 1,000+ field stations, nature reserves, and research sites across six continents, drawn from OBFS, UC NRS, LTER, NEON, ILTER, and The Nature Conservancy networks. Vision-enabled narratives combine 3D terrain screenshots with ecological data scaffolds, enabling Claude Sonnet to synthesize interpretive prose that integrates spatial reasoning with factual grounding.

A modular JavaScript frontend (twelve modules on the FG namespace) communicates with a PHP backend using parallel API fetching (curl_multi) and MySQL caching with source-appropriate TTL values. A monitoring widget system displays live sensor data from Tempest weather stations, BirdWeather acoustic monitors, Ecowitt sensors, panoramic cameras (Pannellum), and stratification arrays. An AI enrichment pipeline uses Claude with web_search to research and populate curated place profiles. A privacy-respecting analytics system tracks usage patterns without IP logging or cookies.

Planned near-term extensions add an Atmosphere panel (satellite sky imagery from GOES/Himawari geostationary platforms + 72-hour forecast arc) as a fifth panel between Physical Place and Ecological Setting. A four-layer platform architecture is in design: the existing field guide (Guide), a new data science workbench (Lab), a place-based publication layer (Journal), and the existing document archive (Archive).

YEA serves as a standalone ecological reference tool at yea.earth, a place-enriched discovery platform for natural areas worldwide, a metadata engine for the SCOPE panoramic photograph database, and a prototype component of the Macroscope integrated environmental observatory platform.

1. Introduction

1.1 Purpose and Concept

YEA computes an "ecological address" for any point on Earth. Where a postal address locates a person within a human administrative framework, an ecological address locates them within the planet's natural organization: what biogeographic realm, what biome, what ecoregion, what climate zone, what bedrock geology, what terrain, what vegetation community, what species assemblage, and what conservation designations protect the land. The tool answers the question: what would a naturalist tell you about this place?

The application accepts input via map click (Mapbox GL JS satellite imagery with 3D globe projection), place name search (dual iNaturalist and Mapbox Geocoding), direct coordinate entry, or browser geolocation. A single backend call orchestrates parallel queries to all data sources, returning a consolidated JSON response rendered as thematic panels with expandable data cards.

1.2 Context and Evolution

YEA was conceived as a citizen science environmental context engine — a way to provide ecological metadata for any coordinate in the SCOPE panoramic photography database. Within three weeks of initial development it had evolved into a significantly broader platform: a curated natural area discovery system, a vision-enabled AI interpretation engine, and a live monitoring integration layer. Six major capabilities not present in the initial design are now integrated:

• Curated Places — 1,000+ enriched ecological profiles with AI-assisted research narratives
• Vision Narratives — 3D terrain screenshot + data scaffold sent to Claude Sonnet for spatial-ecological interpretation
• Land Protection — PAD-US (CONUS) and WDPA (global) conservation designation overlay
• Monitoring Widgets — live sensor display for Tempest, STRATA, BirdWeather, Ecowitt, Pannellum panoramas
• AI Enrichment Pipeline — automated place research agent using Claude with web_search
• Panorama Integration — Pannellum viewer with OBFS 360-degree video import pipeline

Near-term planned extensions are described in Section 18.

1.3 Design Philosophy

Seven principles guide the system:

1. Naturalist interpretation over raw data. Data is contextualized, not just displayed. AI narratives interpret ecological relationships, not inventory them.
2. Senior-friendly accessibility. 26px Georgia serif base font, high-contrast warm parchment palette, large tap targets — informed by user feedback.
3. Progressive disclosure. Snapshot cards expand to full detail via drawer interaction.
4. Graceful degradation. US-only sources (EPA, NLCD, LANDFIRE, PAD-US) are skipped for international coordinates; global alternatives are always available.
5. Data richness over implementation complexity. Multiple APIs unified through straightforward parallel fetching and parsing.
6. Silo independence. Each data card owns its own API sources. Cross-silo interpretation is delegated to the narrative LLM layer, not embedded in the data pipeline.
7. Place-based ecological intelligence. Curated natural areas carry accumulated knowledge — field notes, photographs, sensor streams — that deepens interpretation at known research sites.

2. Architecture

2.1 Deployment

Table 1. Deployment configuration.

2.2 File Structure

Core application:

ecoADDRESS/
├── index.php                — Page shell: rotating globe, search bar, map, field guide
├── address_api.php          — Backend orchestrator: caching, API coordination, JSON response
├── narrative_api.php        — Vision+text narrative generation (Haiku + Sonnet)
├── enrich.php               — AI enrichment agent (place research + narrative via Claude)
├── about.php / contact.php  — Static pages
├── sources.php              — Public data sources page
└── api/
    └── atmosphere.php       — [PLANNED] Sky tile, forecast arc, VIIRS globe endpoint

CSS (6 core + admin):

css/
├── fieldguide.css           — Base styles: typography, color palette
├── layout.css               — Page layout: hero, nav, search, map, controls
├── panels.css               — Panel and card system: headers, bodies, status dots
├── drawers.css              — Drawer expansion, info modals, lightbox overlay
├── species.css              — Species lists, taxon groups, thumbnails
├── gallery.css              — Gallery/media grid
├── responsive.css           — Breakpoints at 850px and 500px
├── admin.css                — Admin dashboard shared styles
├── admin_places.css         — Places admin styles
├── monitoring-widgets.css   — Live monitoring widget display
├── monitoring-manager.css   — Monitoring source management admin
├── media-manager.css        — Media management admin
├── sources-manager.css      — Place source management
└── categories-manager.css   — Category management

JavaScript (12 FG modules + monitoring + 1 planned):

js/
├── fg-config.js        — Module 1: FG namespace, Mapbox globe, DOM refs, constants
├── fg-analytics.js     — Module 2: Privacy-respecting session tracking
├── fg-icons.js         — Module 3: Lucide SVG icon library
├── fg-helpers.js       — Module 4: Shared utilities
├── fg-species.js       — Module 5: Species list rendering, photo backfill
├── fg-snapshots.js     — Module 6: Snapshot summaries for all card types
├── fg-drawers.js       — Module 7: Drawer content builders
├── fg-search.js        — Module 8: Dual place search (iNat + Mapbox)
├── fg-gallery.js       — Module 9: Media gallery for curated places
├── fg-places.js        — Module 10: Curated places overlay, Natural Area detail panels
├── fg-map.js           — Module 11: Map interaction, terrain, camera transitions
├── fg-init.js          — Module 12: Master renderer, panel builders, event handlers
├── fg-atmosphere.js    — [PLANNED] Module 13: Atmosphere panel (Sky Now, Forecast Arc)
└── monitoring/
    ├── core.js              — Monitoring widget initialization and orchestration
    ├── mw-tempest.js        — Tempest weather station widget
    ├── mw-strata.js         — Stratification array widget
    ├── mw-birdweather.js    — BirdWeather acoustic monitor widget
    ├── mw-ecowitt.js        — Ecowitt sensor widget
    ├── mw-pano.js           — Pannellum panorama widget
    └── mw-pano-video.js     — Pannellum 360-degree video widget

PHP library (lib/):

lib/
├── sources.php         — URL builders, parallel fetch engine (curl_multi)
├── parsers.php         — Parser coordinator: loads sub-parsers, provides parseAll()
├── database.php        — MySQL caching, query logging, event logging, narrative cache
├── place_context.php   — Mapbox POI + Wikipedia geosearch enrichment
├── places.php          — Full CRUD for yea_places schema (v3.1)
├── place_sources.php   — Place source management
├── padus.php           — Protected Area Database (CONUS land protection)
├── wdpa.php            — World Database on Protected Areas (global)
└── parsers/
    ├── terrain.php             — parseTerrain(), compassLabel()
    ├── geology.php             — parseMacrostrat()
    ├── climate.php             — parseKoppen(), parseClimateArchive()
    ├── geography.php           — parseReverseGeo(), parseEcoregion(), parseResolveEcoregion()
    ├── landcover.php           — parseNlcd(), parseEsriLulc(), parseLandfireEvt()
    ├── landfire_evt_lookup.php — LANDFIRE EVT code-to-name table (1,068 entries)
    ├── weather.php             — parseWuNearby(), parseOpenMeteo()
    ├── biodiversity.php        — parseInatTotal(), parseInatTaxon()
    ├── birds.php               — parseEbirdRecent(), parseBirdWeatherSpecies()
    └── conservation.php        — parseConservation()

Admin (admin/):

admin/
├── index.php           — Dashboard: API health, cache stats, recent queries
├── analytics.php       — Usage analytics: sessions, devices, engagement
├── globe.php           — MapBox globe visualization of all queried locations
├── globe_data.php      — GeoJSON endpoint for globe
├── events_api.php      — POST handler for frontend usage events
├── monitoring.php      — Cross-place monitoring instruments overview
├── places.php          — Places management
├── people.php          — People management
├── organizations.php   — Organizations management
├── media.php           — Media management
├── media-browse.php    — Media browser
├── types.php           — Place type management
├── categories.php      — Category management
└── includes/header.php — Admin navigation

Panorama tools:

pano-add.php / pano-import.php              — Still panorama upload and import
pano-video-add.php / pano-video-import.php  — Video panorama upload and import
import-obfs-panos.php                       — Bulk OBFS Virtual Field panorama import
lib/pannellum.js / pannellum.css            — Pannellum equirectangular viewer
videojs-pannellum-plugin.js                 — 360-degree video support
video_min.js / video-js_min.css             — Video.js player

Background scripts (Galatea, launchd-managed):

viirs_earth_fetcher.py     — Daily 08:15: fetches 8K VIIRS true-color JPEG from NASA GIBS
goes_sky_fetcher.py        — [PLANNED] Hourly: fetches GOES/Himawari sky tiles per curated place

2.3 Credential Files (Outside Webroot)

/Library/WebServer/secure/credentials/ecoaddress/
  ai-config.php      — Defines WU_API_KEY, MAPBOX_TOKEN, EBIRD_API_KEY,
                        OPEN_METEO_API_KEY, ANTHROPIC_API_KEY
  ecoaddress.php     — Database credentials: $db_host, $db_name, $db_user, $db_pass

2.4 Request Flow

The primary ecological address lookup lifecycle:

1. User clicks map, searches a place name, enters coordinates, or uses browser geolocation.
2. fg-map.js calls GET address_api.php?lat={lat}&lon={lon}&sid={session_id}.
3. Orchestrator validates input and determines CONUS membership (US bounding box check).
4. Mapbox tile coordinates computed for zoom level 14.
5. MySQL cache checked for existing responses (cacheGetAll).
6. URLs built only for uncached sources (buildUrls in sources.php).
7. All uncached sources fetched in parallel via curl_multi.
8. New responses cached (cacheSetAll). All responses parsed (parseAll).
9. Sequential Weather Underground station iteration finds active PWS within 5 miles; validated against Open-Meteo ±10°F baseline.
10. Dynamic radius widening for iNaturalist (1→5→10→20 km), eBird (same cascade), BirdWeather (bounding box).
11. Conservation status queries run at final iNaturalist radius.
12. LANDFIRE EVT fetched with 30m grid-snapped coordinates (CONUS only).
13. Open-Meteo Historical archive queried for 1991–2025 climate + water balance (6 variables, permanent cache).
14. iNaturalist seasonal queries (month-filtered, 3-month window) run for all nine taxa.
15. PAD-US (CONUS) and WDPA (global) queried for land protection status.
16. Place context enrichment: Mapbox POI + Wikipedia geosearch + ecoregion fallback. POI name promotion within 200m of ecological categories.
17. Nearby curated places from yea_places checked (Haversine proximity query).
18. Query logged with timing, per-source status, user agent, referer, session ID.
19. Consolidated JSON returned to frontend.
20. fg-init.js renders field guide panels including Curated Discovery panel. Async bird photo backfill begins.

3. Data Sources

3.1 Source Summary

Table 2. External data sources integrated by YEA. Sources marked [PLANNED] are not yet implemented.

Removed: USDA FIA Forest Atlas (GeoPlatform identify endpoint returns HTTP 400 since Kubernetes migration, February 2026; vegetation type coverage now provided by LANDFIRE EVT at 30m).

Deferred: NASA GPM/IMERG precipitation raster tiles. Requires HDF5 ingestion pipeline and local tile hosting — data engineering scope beyond current architecture. Revisit as future technology.

3.2 API Endpoints

(Sections 3.2.1–3.2.18 as in v3.0, unchanged. New endpoints for planned sources documented in Section 10.)

3.2.1 Mapbox Terrain-RGB DEM [1]

https://api.mapbox.com/v4/mapbox.terrain-rgb/{z}/{tx}/{ty}.pngraw?access_token={token}

Returns a raw PNG tile encoding elevation in RGB channels. Elevation decoded as: −10000.0 + ((R × 256 × 256 + G × 256 + B) × 0.1), yielding 0.1m precision. Slope and aspect computed from a 3×3 pixel neighborhood gradient using ImageMagick CLI. Requires MAPBOX_TOKEN.

3.2.2 Macrostrat Geologic Map [19]

https://macrostrat.org/api/v2/geologic_units/map?lat={lat}&lng={lon}&response=long

Returns bedrock geology at multiple map scales. Parser selects the most detailed unit and returns: formation name, lithology, stratigraphic name, geologic age (top/bottom in Ma), period, best interval, map color, and source reference. No API key required. CC-BY 4.0 license. Global coverage from 225+ integrated geological survey maps.

3.2.3 Köppen Climate API [5]

http://climateapi.scottpinkelman.com/api/v1/location/{lat}/{lon}

Returns the Köppen-Geiger climate zone code and description. No API key required.

3.2.4 RESOLVE Ecoregions 2017 [6]

https://data-gis.unep-wcmc.org/server/rest/services/Bio-geographicalRegions/
  Resolve_Ecoregions/MapServer/identify
  ?geometry={lon},{lat}&geometryType=esriGeometryPoint&sr=4326
  &layers=all:0&tolerance=0&mapExtent={bbox ± 0.01°}
  &imageDisplay=800,600,96&returnGeometry=false&f=json

Returns realm, biome, ecoregion name, Nature Needs Half category. The tight bounding box (± 0.01°) is critical for accuracy at ecotone boundaries. No API key required.

3.2.5 Esri Sentinel-2 10m LULC [7]

https://ic.imagery1.arcgis.com/arcgis/rest/services/
  Sentinel2_10m_LandCover/ImageServer/identify
  ?geometry={"x":{x_merc},"y":{y_merc},"spatialReference":{"wkid":3857}}
  &geometryType=esriGeometryPoint&returnGeometry=false&f=json

Requires Web Mercator projection. Nine land cover classes. No API key required.

3.2.6 EPA Omernik Ecoregions [8,9]

https://geodata.epa.gov/arcgis/rest/services/ORD/
  USEPA_Ecoregions_Level_III_and_IV/MapServer/identify
  ?geometry={lon},{lat}&geometryType=esriGeometryPoint&sr=4326
  &layers=all:7&tolerance=0&mapExtent={bbox ± 0.01°}
  &imageDisplay=800,600,96&returnGeometry=false&f=json

US only. Layer 7 returns all four Omernik levels in a single query. The tight bounding box (± 0.01°) prevents incorrect polygon returns at mountain ecotone boundaries. No API key required.

3.2.7 MRLC NLCD 2021 [10]

https://www.mrlc.gov/geoserver/mrlc_display/NLCD_2021_Land_Cover_L48/ows
  ?service=WMS&version=1.1.1&request=GetFeatureInfo
  &layers=NLCD_2021_Land_Cover_L48&query_layers=NLCD_2021_Land_Cover_L48
  &info_format=application/json&x=50&y=50&width=101&height=101
  &srs=EPSG:4326&bbox={bbox ± 0.005°}

CONUS only. Twenty land cover classes at 30m resolution. No API key required.

3.2.8 LANDFIRE LF2024 Existing Vegetation Type [20]

https://lfps.usgs.gov/arcgis/rest/services/Landfire_LF230/
  US_230EVT/ImageServer/identify
  ?geometry={"x":{lon},"y":{lat},"spatialReference":{"wkid":4326}}
  &geometryType=esriGeometryPoint&returnGeometry=false&f=json

CONUS only, 30m resolution. Requires User-Agent header. Returns a numeric EVT code mapping to one of 1,068 NatureServe ecological system classifications. Standalone curl call with 30m grid-snapped coordinates.

Grid-snapping: Coordinates snapped to nearest 30m pixel center. lat_step = 30.0 / 111111.0 (~0.00027°); lon_step adjusted by cos(latitude).

3.2.9 Weather Underground [12]

Nearby stations:

https://api.weather.com/v3/location/near
  ?geocode={lat},{lon}&product=pws&format=json&apiKey={key}

Current conditions (sequential, per station):

https://api.weather.com/v2/pws/observations/current
  ?stationId={id}&format=json&units=e&apiKey={key}

Requires WU_API_KEY. Orchestrator iterates through up to five nearest stations until one reports non-null temperature. PWS data validated against Open-Meteo baseline; divergence exceeding ±10°F triggers station rejection.

3.2.10 Open-Meteo Pro [13]

https://customer-api.open-meteo.com/v1/forecast
  ?latitude={lat}&longitude={lon}
  &current=temperature_2m,relative_humidity_2m,wind_speed_10m,
           wind_direction_10m,surface_pressure
  &temperature_unit=fahrenheit&wind_speed_unit=mph&apikey={key}

Global modeled weather baseline. Always queried regardless of PWS availability. Requires OPEN_METEO_API_KEY.

3.2.11 iNaturalist [2]

https://api.inaturalist.org/v1/observations/species_counts
  ?lat={lat}&lng={lon}&radius={km}&per_page={n}[&iconic_taxa={taxon}]

Nine taxon groups queried independently: Plantae, Fungi, Aves, Mammalia, Reptilia, Amphibia, Insecta, Arachnida, Mollusca. Plants return per_page=20; others return per_page=10. No API key required.

3.2.12 iNaturalist Conservation [2]

https://api.inaturalist.org/v1/observations/species_counts
  ?lat={lat}&lng={lon}&radius={km}&threatened=true&per_page=100

Results grouped by conservation severity: Critically Endangered, Endangered, Vulnerable, Near Threatened, NatureServe Imperiled.

3.2.13 eBird API 2.0 [3,14]

Recent observations (30 days):

https://api.ebird.org/v2/data/obs/geo/recent
  ?lat={lat}&lng={lon}&dist={km}&back=30&sort=species&key={key}

Notable/rare species (14 days):

https://api.ebird.org/v2/data/obs/geo/recent/notable
  ?lat={lat}&lng={lon}&dist={km}&back=14&key={key}

Requires EBIRD_API_KEY.

3.2.14 BirdWeather GraphQL [15,16]

POST to https://app.birdweather.com/graphql. No API key required. Note: root stations query returns HTTP 500; station metadata recovered via Species.stations nested field.

3.2.15 Open-Meteo Historical Pro — Climate Archive [17,18]

https://customer-archive-api.open-meteo.com/v1/archive
  ?latitude={lat}&longitude={lon}
  &start_date=1991-01-01&end_date=2025-12-31
  &daily=temperature_2m_max,temperature_2m_min,temperature_2m_mean,
         precipitation_sum,sunshine_duration,et0_fao_evapotranspiration
  &temperature_unit=fahrenheit&precipitation_unit=inch
  &timezone=auto&apikey={key}

Single request feeds both Climate History and Water Balance cards (48% API cost reduction). Returns ~12,400 daily records processed into monthly summaries. Cached permanently.

3.2.16 iNaturalist Seasonal [2]

https://api.inaturalist.org/v1/observations/species_counts
  ?lat={lat}&lng={lon}&radius={km}&per_page={n}&month={prev},{current},{next}
  [&iconic_taxa={taxon}]

Month wrapping handled in PHP (e.g., January → month=12,1,2).

3.2.17 Place Context: Mapbox POI + Wikipedia [1,21]

POIs within 200m of ecological categories can be promoted to primary place identity. Tiered fallback: (1) nearby POIs, (2) nearby Wikipedia articles, (3) Wikipedia article for RESOLVE ecoregion name.

3.2.18 PAD-US and WDPA [11]

PAD-US 3.0 (CONUS): ArcGIS MapServer identify endpoint. Returns federal, state, local, and tribal protected area designations, managing agency, GAP status (1–4), and public access.

WDPA (global): Returns IUCN category, designation type, status, and managing authority. Both sources cached permanently.

4. Dynamic Radius Widening

All biodiversity sources (iNaturalist, eBird, BirdWeather) use progressive widening: 1→5→10→20 km. Accept first radius meeting threshold (<5 species triggers widen, <3 for seasonal), or accept 20 km result. Conservation queries use final iNaturalist radius. Final radius recorded in JSON response and displayed in UI.

5. Weather Validation

1. Open-Meteo always queried as global modeled baseline.
2. WU stations accepted only within 5 miles.
3. Up to 5 nearest stations iterated until non-null temperature found.
4. PWS temperature compared against Open-Meteo baseline; ±10°F divergence triggers rejection.
5. On rejection or absence, modeled Open-Meteo data used as fallback, tagged "modeled" in UI.

6. Database Schema

Database: ecological_address

6.1 lookup_cache

CREATE TABLE lookup_cache (
  id int UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
  coord_key varchar(24) NOT NULL,
  source varchar(32) NOT NULL,
  response MEDIUMTEXT NOT NULL,
  created_at datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  UNIQUE KEY uk_coord_source (coord_key, source),
  KEY idx_created (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

Coordinate key: Lat/lon rounded to 3 decimal places (~111m precision), e.g., "45.357,-122.607".

6.2 lookup_log

CREATE TABLE lookup_log (
  id int UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
  coord_key varchar(24) NOT NULL,
  lat decimal(8,4) NOT NULL,
  lon decimal(9,4) NOT NULL,
  place_name varchar(128) DEFAULT NULL,
  duration_ms int UNSIGNED NOT NULL,
  source_status JSON NOT NULL,
  user_agent varchar(512) DEFAULT NULL,
  referer varchar(512) DEFAULT NULL,
  session_id char(12) DEFAULT NULL,
  created_at datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  KEY idx_coord (coord_key),
  KEY idx_created (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

No IP addresses stored.

6.3 narrative_cache

CREATE TABLE narrative_cache (
  id int UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
  coord_key varchar(24) NOT NULL,
  data_hash char(32) NOT NULL,
  narratives MEDIUMTEXT NOT NULL,
  provider varchar(16) NOT NULL,
  model varchar(64) NOT NULL,
  created_at datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  UNIQUE KEY uk_coord_hash (coord_key, data_hash),
  KEY idx_created (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

Data hash is MD5 of parsed ecological data excluding weather and eBird. Cache TTL 30 days.

6.4 usage_events

CREATE TABLE usage_events (
  id int UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
  session_id char(12) NOT NULL,
  event_type varchar(32) NOT NULL,
  event_data JSON DEFAULT NULL,
  created_at datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  KEY idx_session (session_id),
  KEY idx_type (event_type),
  KEY idx_created (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

6.5 Cache TTL Strategy

Table 3. Cache expiration organized by temporal behavior.

7. Frontend Architecture

7.1 Panel Structure

Table 4. Field guide panel organization. The Atmosphere panel [PLANNED] sits between Physical Place and Ecological Setting, reflecting the causal chain from physical substrate through atmospheric mediation to ecological community.

Natural Area Detail Panel: When a curated place is selected, a full-width detail panel replaces the standard field guide with: identity header, site abstract, monitoring widgets, media gallery, Pannellum photopoints viewer, field log, associated people/staff, and source links. Rendered by fg-places.js.

7.2 Map: Globe and 3D Visualization

The map opens as a rotating globe (Mapbox GL JS globe projection) that spins slowly until a location is queried. On first lookup, transitions to satellite-streets 3D terrain. Four map controls: 3D/Nadir toggle, Orbit mode, Labels toggle, Natural Area pins.

Globe zoom computed from container dimensions via log₂ scaling from calibrated 640px baseline. Terrain DEM (exaggeration 1.3) loads on first 3D activation.

7.3 JavaScript Module Architecture

Table 5. JavaScript module responsibilities and load order.

7.4 Card States

• Placeholder — before search: category title and descriptive text.
• Snapshot — after search: one-line key value, source attribution, status indicator (green/red dot).
• Drawer — on click: full detail with all fields, species lists, charts, interactive elements.

CARD_SOURCE_MAP drives status indicators. CONUS_ONLY_CARDS marks cards skipped outside CONUS.

8. AI Systems

8.1 Field Notebook Narratives

Table 6. AI narrative personas and configuration.

Temperature 0.6 for all personas.

8.2 Vision-Enabled Narratives

Frontend captures a Mapbox 3D terrain screenshot (getCanvas().toDataURL()) and sends it with the full ecological data scaffold to narrative_api.php. If image present, uses Claude Sonnet 4.6 with base64 image block.

Three-component architecture: vision (spatial pattern recognition) + scaffold (20+ scientific databases) + persona (interpretive frame) → synthesis that neither image nor data alone could produce. First described as the "tricorder architecture" in Hamilton (2026) [22].

Anti-hallucination constraints: Every factual claim must come from the ecological data profile. Absent data categories explicitly flagged. Vision calls may describe terrain imagery but not name landmarks absent from the data scaffold.

Urban-context awareness: Developed/urban land cover triggers an alternative prompt frame for urban ecology interpretation.

Curated place enrichment: If coordinate falls within a curated place, prompt receives site_abstract, stewardship description, and history context from yea_places.

8.3 AI Enrichment Pipeline (enrich.php)

Admin-only. Three modes: research (Claude + web_search → populate all enrichment fields), narrative (enrichment data + ecological address → curated_narrative), save (targeted field update).

Allowed models: claude-haiku-4-5-20251001, claude-sonnet-4-5-20250929, claude-opus-4-5-20250918, ollama:gpt-oss:20b. Explicit allowlist; safe default if unrecognized model requested.

8.4 Narrative Caching

Narratives cached by coordinate + MD5 hash of ecological data (excluding weather/eBird). Multiple persona tiers accumulate in single JSON object per coordinate+hash. Cache TTL 30 days; hash change triggers fresh generation.

9. Curated Places System

9.1 Overview

1,000+ natural areas, field stations, and research sites. Networks: OBFS, UC NRS, LTER, NEON, ILTER, The Nature Conservancy. Places carry site abstracts, conservation narratives, photopoints, 360-degree panoramas, and live monitoring sensor feeds.

9.2 Database Schema (yea_places v3.1)

yea_places — name, slug, lat, lon, radius_km, status, category, type_id, organization_id, country, state_province, elevation_m, area_acres, established_date, site_abstract, wikipedia_url, website, place_description, stewardship_description, history_description, facilities_description, access_description, curated_narrative, badge_path, elevation_range, created_at, updated_at.

yea_photopoints — place_id FK, name, description, lat, lon, elevation_m, bearing, pano_type, status, sort_order.

yea_media — place_id FK, photopoint_id FK, type, filename, title, caption, taxon_id, category, tags (JSON), file_size, width, height, taken_at, author, license, sort_order, status.

yea_people — name, slug, title, affiliation, orcid, email, bio, role_description, photo_filename.

yea_monitoring_sources — place_id FK, name, type, class (physical/virtual/human), platform_id, config (JSON), status, notes.

Supporting tables: yea_tags, yea_field_log, yea_person_organizations, yea_place_sources.

9.3 Proximity Detection

findNearbyPlaces($lat, $lon) uses Haversine formula. Returns published places where query coordinate falls within place radius_km, ordered by distance.

9.4 Frontend: Curated Discovery Panel

Rendered by fg-places.js. Network badges, place cards with distance, click → Natural Area Detail panel.

Natural Area Detail Panel: Full-width view with identity header, site abstract, monitoring widgets, media gallery, Pannellum panorama viewer, field log, researchers/staff, source links. Breadcrumb returns to field guide.

10. Atmosphere Panel (Planned)

Specified in CNL-SP-2026-027 [25]. This section summarizes the specification for integration into the system record.

10.1 Overview

A new fifth panel in the field guide drawer sequence, positioned between Physical Place and Ecological Setting. The atmosphere mediates nearly every ecological process at a site; this panel elevates atmospheric observation from a supporting detail (current weather card) to a first-class domain with satellite-derived and forecast data.

The prior VIIRS cloud layer overlay approach (Phase 6 workplan) is retired: cloud extraction from VIIRS composites confused clouds with snow and ice, and the Mapbox globe image source introduced a ~10–15° latitude shift. The new approach reframes satellite imagery as a place-specific observational tool rather than a decorative globe overlay.

10.2 Panel Position

Identity → Curated Discovery → Physical Place → Atmosphere → Ecological Setting → Living Systems → Field Notebook

10.3 Cards

Table 7. Atmosphere panel cards.

10.4 Sky Now Card

A 512×512 pixel satellite tile crop (~300km radius) centered on the queried coordinate. Band selection based on solar altitude at coordinate:

solar_altitude > 10°    → Red Visible (GOES Band 2, 1km)
solar_altitude > −6°    → Red Visible (twilight, may be dim)
solar_altitude ≤ −6°    → Clean Infrared (Band 13, 2km, day and night)

Satellite selection by longitude:

Coverage gap: Europe, Africa, and western Asia not covered. Meteosat integration deferred.

NASA GIBS WMS endpoint:

https://gibs.earthdata.nasa.gov/wms/epsg4326/best/wms.cgi
  ?SERVICE=WMS&REQUEST=GetMap&VERSION=1.1.1
  &LAYERS={LayerIdentifier}&FORMAT=image/jpeg
  &WIDTH=512&HEIGHT=512&SRS=EPSG:4326
  &BBOX={lon-delta},{lat-delta},{lon+delta},{lat+delta}
  &TIME={YYYY-MM-DDTHH:MM:SSZ}

No authentication or API key required. Attribution required per NASA GIBS usage guidelines.

Computed metrics: cloud fraction (% of tile pixels classified as cloud), estimated solar attenuation (cloud_fraction × 0.7), cloud top temperature (infrared only).

Card display: satellite tile image, band indicator, UTC/local timestamp, cloud fraction with qualitative label (Clear / Partly Cloudy / Mostly Cloudy / Overcast), solar radiation estimate, ecological one-liner (Haiku-generated).

10.5 Forecast Arc Card

Open-Meteo Forecast API with extended atmospheric parameter set:

https://customer-api.open-meteo.com/v1/forecast
  ?latitude={lat}&longitude={lon}
  &hourly=cloud_cover,precipitation_probability,precipitation,
          pressure_msl,wind_speed_10m,wind_direction_10m,
          shortwave_radiation,direct_radiation,diffuse_radiation,
          temperature_2m,relative_humidity_2m,sunshine_duration
  &daily=sunrise,sunset,daylight_duration,
         precipitation_sum,precipitation_hours,shortwave_radiation_sum
  &temperature_unit=fahrenheit&wind_speed_unit=mph
  &timezone=auto&forecast_days=3&apikey={key}

Card components: 72-hour cloud cover sparkline (area chart, color-coded clear/cloudy with precipitation overlay and sunrise/sunset markers), pressure trend with directional arrow, solar radiation budget (actual vs. clear-sky potential, expressed as %), 2–3 sentence ecological interpretation (Haiku-generated from forecast + place context).

10.6 VIIRS Globe Widget

Simplified viirs_earth_fetcher.py v3.0 (removes cloud extraction pipeline; retains daily 8K JPEG fetch and archive). Three.js sphere with latest_earth.jpg as diffuse texture, atmospheric limb glow, slow rotation, mouse/touch drag, scroll zoom, raycasting coordinate display. Adapted from LCARS Planetary Observation System proof-of-concept. Embedded as interactive thumbnail in Atmosphere panel header or accessible as standalone view.

10.7 Data Pipeline: GOES Sky Fetcher

Script: goes_sky_fetcher.py on Galatea, launchd daemon every 60 minutes.

Per-execution pipeline:

1. Query yea_places for all published places with valid coordinates.
2. For each place: determine nearest geostationary satellite; compute solar altitude; select band; construct GIBS WMS request; fetch 512×512 tile; compute cloud fraction and solar attenuation.
3. Write manifest JSON with per-place metadata.

Cache structure:

/Library/WebServer/Documents/.../atmosphere/
  ├── manifest.json           — all places, current state
  ├── tiles/
  │   ├── {place_slug}_sky.jpg     — most recent tile
  │   └── {place_slug}_meta.json   — metrics for this place
  └── archive/
      └── {YYYY-MM-DD}/
          └── {place_slug}_{HH}00.jpg

10.8 Atmosphere API Endpoint

File: api/atmosphere.php

10.9 VIIRS Cloud Layer Removal (Cleanup)

The prior cloud layer implementation is removed from the frontend during Atmosphere panel development:

• fg-config.js — remove VIIRS cloud layer source, cloud-layer map layer, FG.cloudsVisible, FG.toggleClouds(), FG._cloudOpacityForZoom()
• index.php — remove clouds toggle button; add Atmosphere panel markup; add fg-atmosphere.js script include
• layout.css — remove cloud toggle button styles

10.10 Implementation Sequence

Table 8. Atmosphere panel implementation steps from CNL-SP-2026-027.

Steps 1–2 are cleanup and can proceed immediately. Steps 3–5 establish the data pipeline. Steps 6–8 build the frontend. Step 7 can proceed in parallel with steps 3–6.

11. Monitoring Widgets

11.1 Architecture

Self-contained modules (mw-*.js + mw-*.php) displayed in the Natural Area Detail Panel for places with configured monitoring sources. core.js orchestrates initialization.

11.2 Widget Types

Table 9. Monitoring widget modules.

11.3 Panorama Import Pipeline

• pano-add.php / pano-import.php — single or batch still panoramas; validates equirectangular format, generates thumbnails.
• pano-video-add.php / pano-video-import.php — 360-degree video files; served via Video.js + Pannellum.
• import-obfs-panos.php — bulk import of OBFS Virtual Field Project archive (33 stations, 457 panoramas, 2020–2022).

12. Four-Layer Platform Architecture (Planned)

Described in CNL-FN-2026-029 [26]. This section summarizes the architectural vision and planned development sequence.

12.1 Overview

YEA is conceived as evolving into a four-layer platform, each layer serving a distinct cognitive mode while sharing a common data substrate:

Table 10. Four-layer platform architecture.

The existing field guide is Layer 1. Layers 2 and 3 are new applications. Layer 4 is the existing CNL document series.

12.2 YEA Lab

A standalone data science workbench launched from a main tab on the YEA home page. Place-centric entry, full-width interactive instruments, adjustable time windows, cross-place comparison capability, data export. Three spatial scales:

• Point scale — single curated place; monitoring instruments with room to breathe. Full-width time series, annotation tools, date range selectors, side-by-side instrument overlays, CSV/JSON export.
• Landscape scale — place plus ecological neighborhood; Open-Meteo gridded virtual weather, iNaturalist observation density surfaces, elevation-temperature gradients, BirdWeather acoustic coverage mapping.
• Gradient scale — across places; latitudinal/elevation/precipitation transects, phenological wave analysis, climate refugia screening, migration corridor analysis.

Point scale is the entry point for initial implementation. Landscape and gradient scales emerge as the curated place network grows.

Virtual instruments are first-class citizens alongside physical sensors. An Open-Meteo modeled time series is a different kind of instrument from a Tempest station — not a lesser substitute, but a complementary one with different strengths (global coverage, historical reanalysis) and limitations (spatial averaging, no microclimate sensitivity).

Relationship to monitoring widgets: The existing MW system provides compact status indicators for the field guide. In the Lab, the same data sources power full-scale instruments. The monitoring card on the field guide gains an "Open in Lab" link per instrument. The compact widget is a window; the Lab instrument is the room.

12.3 YEA Journal

A standalone hypermedia publication accessible from a main tab on the YEA home page. Place-centric and event-driven — content appears because something ecologically noteworthy happened, not because it's Tuesday. Each curated place generates a running column of four content types:

• Place Cards — compact ecological address summaries for first-time visitors.
• Trend Digests — instrument-generated summaries of notable patterns ("Spring is running 8 days ahead of the 10-year phenological mean at Canemah Bluff"). Written by the AI summarizer, reviewed and verified by human curators before publication.
• Q&A Highlights — findings reframed as questions a curious naturalist would ask, drawn from the Science persona's interpretive output. Questions invite inquiry; declarations close conversations.
• Lab Callouts — links to specific experiments, visualizations, and datasets in the Lab ("Explore the full acoustic migration timeline →").

The publication loop: Collection (instruments run continuously) → Detection (periodic routines scan for noteworthy patterns) → Narration (AI generates draft entry, human curator reviews and verifies) → Invitation (entry links to Lab for evidence exploration) → Response (human field notes annotate and ground-truth what instruments detected).

This loop is not hypothetical. The existing yea_field_log table already supports it: author_type distinguishes human from AI from verified entries, data_sources carries JSON provenance, and verified_by records the curator who approved an AI-generated summary.

Human editorial authority: The Journal never publishes an AI-generated entry without curator review. The verified author type is the quality guarantee that makes the Journal credible.

12.4 Phased Development Sequence

Table 11. Lab and Journal development phases from CNL-FN-2026-029.

13. Analytics System

13.1 Design Principles

No IP addresses logged, no cookies set, no persistent user identifiers. Session identity is a 12-character random alphanumeric string (tab-scoped, dies with tab close).

13.2 Frontend Event Tracking

Table 12. Analytics events tracked by fg-analytics.js.

Transport: navigator.sendBeacon with fetch keepalive fallback.

13.3 Administrative Dashboard

• Dashboard — API health, cache statistics, recent queries with timing.
• Analytics — 14-day sessions, daily trends, entry methods, card engagement, narrative persona usage, device/browser, referrers.
• Globe — GPU-rendered circle layers (~111m diameter). Time filter (7d/30d/90d/All). Click-to-fly.
• Places admin — full CRUD, media, people, organizations, monitoring sources, enrichment queue.
• Monitoring — cross-place instruments, filterable by class and status.

14. UI Design Specifications

14.1 Color Palette (Warm Parchment)

Table 13. UI color palette.

14.2 Typography

14.3 Responsive Breakpoints

15. Key Technical Decisions

Table 14. Key technical decisions and rationale.

16. Verified Test Sites

Table 15. Sites used for system verification.

17. Limitations

Coverage gaps: US-specific sources (EPA, NLCD, LANDFIRE, PAD-US) unavailable internationally. iNaturalist density varies dramatically by region. BirdWeather concentrated in North America and Western Europe. Atmosphere Sky Now has no coverage for Europe, Africa, or western Asia (Meteosat deferred).

API stability: Köppen Climate API has no SLA. BirdWeather root stations returns HTTP 500 (workaround via nested field). Open-Meteo Historical 35-year query times out intermittently (retry logic implemented).

Vision narratives: Quality depends on terrain rendering at queried location. Ocean, flat terrain, and cloud-obscured satellite imagery produce less informative calls. Vision calls may describe satellite imagery processing artifacts as landscape features.

AI enrichment: Research quality varies by web documentation of a place. Synthesized inaccuracies possible; all enriched content requires human review before publishing.

Narrative anti-hallucination: Constraints effective but not infallible. Teaser narrative (50-word target) occasionally exceeds word count.

Coordinate resolution: 3-decimal rounding (~111m) means users 120m apart receive different profiles; users closer than ~111m share the same cached result.

Atmosphere panel (planned): GOES sky tiles cached hourly — sky conditions can change significantly in 60 minutes, particularly in convective environments. Cloud fraction is an approximation; snow/ice confusion possible. Ecological one-liner interpretations are AI-generated estimates, not ground-truth ecological assessment.

18. Planned Development Sequence

Table 16. Near-term development roadmap.

19. Development Conventions

19.1 Code Standards

• Simplicity over cleverness — readable, maintainable, ≤200 lines/file.
• Minimal changes — never reimplement from scratch without permission.
• Style consistency — match existing code patterns.
• Scope discipline — never make unrelated changes.
• No filename prefixes (new_, improved_, updated_).
• Complete files ready for BBEdit; never snippets.
• File headers in all PHP and JS files: path, filename, purpose, change description.
• Proceed protocol: pause after each delivery and wait for confirmation.

19.2 Naming Conventions

Table 17. Naming convention summary.

19.3 Error Handling

API failures return null — orchestrator never crashes. Frontend shows "No data" for null sections. curl_multi treats non-2xx/3xx as null. LANDFIRE standalone curl has 18-second timeout. Climate archive fetch has retry logic with 2-second pauses.

References

[1] Mapbox (2026). "Mapbox GL JS, Terrain-RGB v1, Geocoding v5, Search Box v1." https://docs.mapbox.com/ (accessed March 5, 2026).

[2] iNaturalist (2026). "iNaturalist: A Community for Naturalists." https://www.inaturalist.org (accessed March 5, 2026).

[3] Sullivan, B. L., Wood, C. L., Iliff, M. J., Bonney, R. E., Fink, D., & Kelling, S. (2009). "eBird: A Citizen-Based Bird Observation Network in the Biological Sciences." Biological Conservation, 142(10), 2282–2292.

[4] Hamilton, M. P. (2026). "Canemah Nature Laboratory." https://canemah.org (accessed March 5, 2026).

[5] Peel, M. C., Finlayson, B. L., & McMahon, T. A. (2007). "Updated World Map of the Köppen-Geiger Climate Classification." Hydrology and Earth System Sciences, 11, 1633–1644. https://doi.org/10.5194/hess-11-1633-2007

[6] Dinerstein, E., Olson, D., Joshi, A., et al. (2017). "An Ecoregion-Based Approach to Protecting Half the Terrestrial Realm." BioScience, 67(6), 534–545. https://doi.org/10.1093/biosci/bix014

[7] Karra, K., Kontgis, C., Statman-Weil, Z., et al. (2021). "Global Land Use / Land Cover with Sentinel-2 and Deep Learning." 2021 IEEE IGARSS, 4704–4707. https://doi.org/10.1109/IGARSS47720.2021.9553499

[8] Omernik, J. M. (1987). "Ecoregions of the Conterminous United States." Annals of the Association of American Geographers, 77(1), 118–125.

[9] Omernik, J. M. & Griffith, G. E. (2014). "Ecoregions of the Conterminous United States: Evolution of a Hierarchical Spatial Framework." Environmental Management, 54(6), 1249–1266. https://doi.org/10.1007/s00267-014-0364-1

[10] Dewitz, J. (2023). "National Land Cover Database (NLCD) 2021 Products." U.S. Geological Survey data release. https://doi.org/10.5066/P9JZ7AO3

[11] USGS / UNEP-WCMC (2024). "Protected Area Database of the United States (PAD-US) 3.0 / World Database on Protected Areas." https://www.protectedplanet.net

[12] The Weather Company (2026). "Weather Underground API." https://www.wunderground.com/member/api-keys (accessed March 5, 2026).

[13] Open-Meteo (2026). "Open-Meteo Weather API (Pro)." https://open-meteo.com (accessed March 5, 2026).

[14] Sullivan, B. L., Aycrigg, J. L., Barry, J. H., et al. (2014). "The eBird Enterprise: An Integrated Approach to Development and Application of Citizen Science." Biological Conservation, 169, 31–40. https://doi.org/10.1016/j.biocon.2013.11.003

[15] Scribe Labs (2026). "BirdWeather: A Living Library of Bird Vocalizations." https://www.birdweather.com (accessed March 5, 2026).

[16] Kahl, S., Wood, C. M., Eibl, M., & Klinck, H. (2021). "BirdNET: A Deep Learning Solution for Avian Diversity Monitoring." Ecological Informatics, 61, 101236. https://doi.org/10.1016/j.ecoinf.2021.101236

[17] Zippenfenig, P. (2023). "Open-Meteo.com Weather API." Zenodo. https://doi.org/10.5281/ZENODO.7970649

[18] Hersbach, H., Bell, B., Berrisford, P., et al. (2023). "ERA5 Hourly Data on Single Levels from 1940 to Present." ECMWF, Copernicus Climate Change Service. https://doi.org/10.24381/cds.adbb2d47

[19] Peters, S. E., Husson, J. M., & Czaplewski, J. (2018). "Macrostrat: A Platform for Geological Data Integration and Deep-Time Earth Crust Research." Geochemistry, Geophysics, Geosystems, 19(4), 1393–1409. https://doi.org/10.1029/2018GC007467

[20] LANDFIRE (2024). "LANDFIRE LF2024 Existing Vegetation Type (EVT)." USDA/USDI. https://landfire.gov (accessed March 5, 2026).

[21] Wikipedia (2026). "MediaWiki API: Geosearch." https://www.mediawiki.org/wiki/API:Geosearch (accessed March 5, 2026).

[22] Hamilton, M. P. (2026). "The Morning I Gave the Field Guide Eyes." Coffee with Claude. https://coffeewithclaude.com/post.php?slug=the-morning-i-gave-the-field-guide-eyes

[23] Hamilton, M. P. (2026). "Science Community Observatory for Participatory Ecology." Coffee with Claude. https://coffeewithclaude.com/post.php?slug=science-community-observatory-for-participatory-ecology

[24] NASA GIBS (2026). "Global Imagery Browse Services." NASA Earth Science Data and Information System. https://nasa.github.io/gibs/ (accessed March 5, 2026).

[25] Hamilton, M. P. (2026). "YEA Atmosphere Panel: Satellite Sky Tiles and Forecast Integration." Canemah Nature Laboratory Specification CNL-SP-2026-027. https://canemah.org/archive/document.php?id=CNL-SP-2026-027

[26] Hamilton, M. P. (2026). "YEA Lab and YEA Journal: A Data Science Portal and Hypermedia Publication for Place-Based Ecological Monitoring." Canemah Nature Laboratory Field Note CNL-FN-2026-029. https://canemah.org/archive/document.php?id=CNL-FN-2026-029

Document History

End of Document — CNL-TN-2026-025 v3.1