Macroscope: Next Generation — Architectural Vision

Document ID: CNL-DR-2026-037 Version: 0.1 Date: March 29, 2026 Author: Michael P. Hamilton, Ph.D.

AI Assistance Disclosure: This design review was developed with assistance from Claude (Opus 4, Anthropic). The AI contributed to codebase reconnaissance, architectural analysis, component inventory, and manuscript drafting. The author takes full responsibility for the content, accuracy, and conclusions.

1. Abstract

This design review proposes the architecture for Macroscope: Next Generation (MNG), a unified ecological intelligence platform that consolidates four existing systems: yea.earth (place profiles and monitoring widgets), the Galatea Macroscope (STRATA intelligence agents and sensor registry), MEO v7 (operational monitoring and multi-database federation), and the Data-local macroscope.nexus prototype (agentic concepts). MNG adopts a LAMP stack (PHP 8.5, MySQL 8.4, Apache 2) with a federated twin-database architecture separating public ecological data (EARTH, LIFE domains on Galatea) from private observatory data (HOME, SELF domains on Data). The system introduces a four-tier ecological intelligence pipeline inspired by Google DeepMind's Aletheia paper [1]: Observation (micro-agent summaries), Verification (cross-platform validation), Interpretation (STRATA context builders with narrative personas), and Discovery (pattern recognition with literature validation). A clean site/platform/sensor hierarchy resolves naming confusion from prior iterations. The platform scales from densely instrumented sites like the Canemah Nature Laboratory (five physical instruments, 300+ sensor channels, 35 years of climate record) to thousands of curated natural areas using only public API data. This document captures the complete architectural vision following reconnaissance of all four source codebases.

2. Introduction

2.1 Context and Motivation

Macroscope: Next Generation (MNG) unifies the best components of four existing systems into a single ecological intelligence platform built on LAMP. The goal is to take yea.earth's proven panel/card/drawer architecture and infuse it with STRATA intelligence agents, MEO v7's operational reliability, and a tiered ecological intelligence system inspired by Google DeepMind's Aletheia paper [1].

MNG must scale from the densely instrumented Canemah Nature Laboratory (five physical instruments, 300+ sensor channels, 35 years of climate record) to thousands of curated natural areas with only public API data. It must serve two audiences through a federated twin-database architecture: the public Macroscope at macroscope.nexus, and the private observatory on Data that incorporates HOME and SELF domains.

2.2 Scope

This design review documents the proposed architecture for MNG based on comprehensive reconnaissance of four source codebases conducted on March 29, 2026, including a live tour of yea.earth's production capabilities via Chrome. The document covers database architecture, UI patterns, the ecological intelligence pipeline, the sensor registry, data collection infrastructure, the address API, places architecture, narrative intelligence, project structure, and a phased development sequence.

2.3 Components Retained

2.4 Components Retired

The following components are explicitly retired: the Node.js/Express/Preact stack from macroscope.nexus; the monolithic 35,000-line platforms.php from Galatea Macroscope; the dark theme UI from MEO v7; the confused domain/platform naming conventions from macroscope.nexus; and the incomplete STRATA integration from macroscope.nexus.

3. Methodology

3.1 Reconnaissance Approach

The architectural vision was developed through direct codebase analysis of all four source systems. File counts, directory structures, database schemas, and key modules were inventoried using automated exploration agents. The yea.earth production system was examined live via browser automation, navigating the Canemah Nature Laboratory profile and exercising all six monitoring widgets (Tempest, BirdWeather, Ecowitt, STRATA Climate Tracker, 360 panorama, and monitoring program info).

3.2 Source Systems Examined

Galatea Macroscope (Projects/Live/Galatea/Macroscope/): 48 directories, 310 files. Pure PHP/LAMP. Key subsystems: sensor registry (13 modules in includes/registry/), STRATA agents (agents/ with spatial, temporal, and 13 platform micro-agents), context builders (includes/context/, seven modules), and collectors (collectors/, 17 files running 24/7).

MEO v7 (Projects/Live/MacroNexus/Active/meo-v7/): Separated into meo-v7-public/ and meo-v7-admin/. Federated database class (lib/db.php, 263 lines) with prepared statements and multi-database support across 14 databases: meo_admin, Weather_DB, inaturalist_observations, birdweather_observations, Ecowitt_DB, Airthings_DB, WeatherLink_DB, davis_weather_archive, ws5000_archive, Earth_DB, Geography_DB, Patterns_DB, BirdWeather_Environmental_DB, and meo_docs.

yea.earth (Projects/Live/Galatea/canemah.org/projects/yea3d/): 112 PHP files, 46 JavaScript modules, 35 CSS files. Key subsystems: address API (address_api.php, 26 KB, orchestrating 21 parallel API fetches), narrative API (narrative_api.php, 42 KB, three personas), monitoring widgets (js/monitoring/, self-registering module pattern), and curated places (lib/places.php, 48 KB, 1,000+ sites).

macroscope.nexus (Data) (Projects/Live/Macroscope/): 84 directories, 94 files. Node.js/Express + Preact frontend. Key concepts: temporal pulse agent with Ollama synthesis, real-time GPS spatial agent, 52,000 words of specification documentation. Decision: Node.js abandoned, concepts retained for PHP reimplementation.

3.3 Hardware and Software

Development: MacBook Pro M4 Max (Data). Production: Mac Mini M4 Pro with 1 Gb fiber (Galatea). Stack: PHP 8.5, MySQL 8.4, Apache 2. Browser testing via Claude in Chrome against localhost URLs.

4. Results

4.1 Federated Twin-Database Architecture

Following the cnl-admin pattern of bidirectional sync between Data and Galatea, MNG separates databases by deployment target and privacy domain.

Galatea (Public -- macroscope.nexus): Two databases serve the public interface: macroscope_public (places, monitoring sources, cached narratives, public sensor data) and macroscope_collectors (raw collector intake tables for Tempest, BirdWeather, Ecowitt, and iNaturalist). All public API endpoints are read-only.

Data (Private -- localhost): Two databases serve the private observatory: macroscope_admin (full admin CRUD, intelligence configuration, agent state) and macroscope_private (HOME domain sensors including AirLink and AirThings, and SELF domain sensors including Withings, Apple Health, and OHSU Clinical data). Bidirectional sync uses the proven data_writer pattern from cnl-admin.

Shared Read Access: Data's data_reader account queries Galatea's collector databases directly for analysis. MEO v7's existing 14-database federation continues as the collector backbone.

4.2 The Site/Platform/Sensor Hierarchy

The naming confusion that plagued macroscope.nexus is resolved with a clean three-tier hierarchy:

SITE (a place)
  +-- PLATFORM (a physical or virtual instrument deployed at that site)
        +-- SENSOR (a measurement channel on that platform)

Sites are places: Canemah Nature Laboratory, Owl Farm, Steele/Burnand Desert Research Center, or any of the 1,000+ natural areas in yea_places. Sites have geographic coordinates, boundaries, habitat types, and elevation ranges.

Platforms are instruments: WeatherFlow Tempest, BirdWeather PUC, Ecowitt Garden Station, STRATA Climate Tracker. Platforms are either PHYSICAL (hardware on site) or VIRTUAL (API-sourced data streams). Each platform is deployed at a specific site.

Sensors are measurement channels: temperature_f, soil_moisture_1, detection_count. Defined by the sensor registry (13 modules, approximately 300 total sensors). Each sensor belongs to a platform and carries metadata: unit, category, aggregation type, and domain assignment.

Domains (EARTH, LIFE, HOME, SELF) are interpretive lenses applied across the hierarchy, not organizational containers. A single site can have platforms spanning multiple domains. The domain assignment lives at the sensor level in the registry. EARTH and LIFE are public (macroscope.nexus). HOME and SELF are private (Data-local only). This is enforced by database architecture -- different databases, different servers, different sync directions.

4.3 UI Architecture: Evolved Panel/Card/Drawer

The yea.earth UI architecture is the foundation. Five colored panels organize ecological knowledge into natural categories:

Each panel contains cards (collapsed summaries with expansion triggers) and cards can open drawers (full-width content areas that slide open below). The Monitoring card uses an icon grid where each icon triggers a widget drawer via the MW.openWidget() dispatcher.

MNG adds two capabilities to this foundation. Intelligence Drawers render STRATA agent output rather than raw sensor data. When a user opens an intelligence drawer, the system assembles context from multiple sensor streams and passes it through the agent pipeline (Section 4.4). The result is a narrative interpretation, not a data table. Observatory Mode is a toggle that shifts from yea.earth's place-profile view to a real-time monitoring dashboard (MEO-style). Same data, different temporal focus. Profile mode shows "what is this place?" Observatory mode shows "what is happening right now?"

The self-registering widget system from yea.earth's monitoring/core.js is the template. Each widget is a self-contained module (~100 lines) that self-registers with the core via MW.register(), fetches data from a platform-specific PHP endpoint, renders HTML with semantic CSS classes, builds time-series charts via MW.buildChart() (Chart.js 4), and provides a "View in Macroscope" link to deeper analysis. MNG extends this pattern with intelligence widgets that call STRATA endpoints instead of raw sensor APIs, and composite widgets that blend data from multiple platforms.

4.4 Ecological Intelligence Architecture

Google DeepMind's Aletheia paper [1] demonstrates that autonomous research benefits from a Generator --> Verifier --> Reviser loop with inference-time scaling. MNG adapts this to ecological intelligence as a four-tier system:

Tier 1: Observation. Thirteen platform-specific micro-agents (one per sensor registry module) each run on a five-minute cycle, producing structured output containing a text summary, key readings, and an update timestamp. Pure data summarization -- no interpretation, no LLM calls. Each is a PHP function of approximately 100 lines that reads directly from collector databases, with output cached as JSON state files.

Tier 2: Verification. New for MNG. The verification tier compares readings across platforms at the same site, flags discrepancies with contextual explanations (e.g., Tempest humidity 94% vs. Ecowitt leaf wetness 2% -- plausible because leaf wetness measures surface condensation, not atmospheric moisture), validates against STRATA Climate Tracker's historical baselines (ERA5 reanalysis back to 1940), and checks BirdWeather detection counts against expected seasonal patterns from iNaturalist and eBird. No LLM required -- rule-based PHP with configurable thresholds.

Tier 3: Interpretation. Seven or more modular context builders assemble system prompts from verified Tier 2 output. Three narrative personas (Naturalist, Scientist, Teacher) generate interpretive text via Claude API calls using the strata_context.php orchestrator pattern. Output is cached for 30 days per yea.earth's narrative_cache pattern, triggered on demand or on schedule. New for MNG: context builders for HOME domain (AirThings indoor air + AirLink outdoor air) and SELF domain (health vitals + activity), available only on Data-local installation.

Tier 4: Discovery. Longer-running analysis jobs look for correlations across time and platforms using MEO v7's Patterns_DB as the storage backend. Web search tool integration provides literature validation -- Aletheia's key finding was that tool use reduces hallucination. Dawn chorus intelligence from MEO v7 serves as the first implemented Tier 4 pattern.

4.5 Sensor Registry

The Galatea Macroscope's convention-based sensor registry transfers directly to MNG. Each of 13 modules defines sensors for one platform using a standardized schema with fields for database column name, display label, unit, category, domain assignment (EARTH/LIFE/HOME/SELF), primary flag, aggregation type, and description.

This registry drives the monitoring widget icon grid, provides metadata for intelligence agents, and defines the sensor catalog for the admin UI.

4.6 Data Collection Infrastructure

MEO v7's collector infrastructure runs continuously on Galatea via launchd and is inherited unchanged. Environmental collectors include Tempest weather (one-minute intervals), Ecowitt garden station (five-minute intervals), AirLink outdoor air quality (five-minute intervals), AirThings indoor air quality (five-minute intervals), and NASA earth imagery (daily). Biological collectors include the BirdWeather continuous collector across three stations (AVR-1, AVR-2, AVR-3), iNaturalist observations (periodic harvest), and BirdWeather environmental data. Analysis jobs include batch intelligence processing, taxonomic crosswalks, geographic harvesting, and pattern correlation.

4.7 The Address API

yea.earth's address_api.php is a 26 KB orchestrator that fetches from 21 external APIs in parallel to build an ecological portrait of any coordinate on Earth. This is MNG's scaling mechanism -- every location gets a baseline ecological profile without any local instrumentation. API sources include Open-Meteo, OpenTopoData, USGS, EPA, Mapbox, eBird, iNaturalist, GBIF, and USGS PAD-US. Caching operates at 11-meter resolution grid. When a site has local instruments, the address API response is enriched with live sensor data, enabling Tier 2 verification.

4.8 Tiered Site Classification

MNG classifies sites by instrumentation density:

Tier A: Fully Instrumented (Canemah pattern). Multiple physical platforms (Tempest + BirdWeather + Ecowitt + panorama), virtual platforms (STRATA Climate Tracker), all four intelligence tiers available, real-time observatory mode, collectors running 24/7.

Tier B: API-Enriched Curated (yea.earth natural area pattern). Curated metadata and descriptions, address API ecological portrait, public API sensor streams where available (eBird, iNaturalist, weather), Tiers 1-3 intelligence available (virtual instruments only), narrative personas active.

Tier C: Address-Only (any coordinate on Earth). Address API ecological portrait on demand, no curated content, Tier 1 observation only, entry point for discovering and curating new sites.

4.9 Narrative Intelligence

yea.earth's narrative system generates interpretive text in three personas: the Naturalist (observational, sensory, place-based), the Scientist (analytical, quantitative, citation-aware), and the Teacher (accessible, contextual, connecting). Generated via Claude API with assembled context, cached 30 days, 150-300 words per narrative. In MNG, narratives gain access to STRATA intelligence output, allowing personas to reference verified sensor data, historical patterns, and discovered correlations.

5. Discussion

5.1 Design Principles

Eight principles guide MNG development:

1. yea.earth is the UI ancestor. Every design decision starts with "how would this work in the panel/card/drawer pattern?" If it doesn't fit, the idea needs refinement, not the pattern.

2. MEO v7 is the reliability standard. If Dr. Hamilton can't check birds and weather every morning without friction, MNG has failed regardless of intelligence layer sophistication.

3. LAMP is the stack. PHP 8.5, MySQL 8.4, Apache 2. No Node.js in production. No frameworks. Vanilla JavaScript with Chart.js and Mapbox as the only external dependencies.

4. Intelligence is layered, not monolithic. Each tier adds value independently. A site with only Tier 1 (raw data) is still useful. Tier 4 (discovery) is a bonus, not a requirement.

5. Physical vs Virtual is explicit. Every platform is typed. Users understand whether data comes from hardware on the bluff or an API call to Open-Meteo. Transparency builds trust.

6. Public vs Private is architectural. The EARTH/LIFE public split and HOME/SELF private split is enforced by database architecture -- different databases, different servers, different sync directions.

7. Files stay small. No file exceeds 200 lines. If a file grows beyond 200 lines, it needs splitting.

8. The sensor registry is the source of truth. Every sensor in the system is defined in exactly one place. Adding a new sensor platform means adding one registry file and one widget module.

5.2 Development Sequence

5.3 Proposed Project Structure

macroscope-nexus/
+-- index.php                        Main entry point, ?page= routing (MEO v7 pattern)
+-- config/                          sites.php, domains.php, app.php
+-- lib/                             db.php, auth.php, cache.php, api_client.php
+-- registry/                        13 sensor definition modules + loader.php
+-- agents/
|   +-- spatial_agent.php            Site-aware location context
|   +-- temporal_agent.php           5-minute pulse orchestrator
|   +-- summaries/                   13 platform micro-agents (Tier 1)
|   +-- verification/                Cross-platform validators (Tier 2)
|   +-- context/                     System prompt builders (Tier 3)
+-- api/
|   +-- address.php                  Ecological portrait endpoint
|   +-- narrative.php                LLM narrative generation
|   +-- monitoring/                  Per-platform widget endpoints
|   +-- intelligence/                STRATA endpoints (Tiers 2-4)
|   +-- places/                      Place CRUD and search
+-- content/                         Page renderers (dashboard, place, patterns, etc.)
+-- js/
|   +-- monitoring/                  Widget modules (core + 5 platform widgets)
|   +-- intelligence/                Intelligence widget renderers
+-- css/                             tokens, panels, cards, drawers, widgets, observatory
+-- admin/                           Data-local only (places, sources, agents, sync)
+-- sync/                            push.php, pull.php

6. Limitations

This design review is an initial architectural vision based on codebase reconnaissance. It has not been validated through implementation. The following questions remain open:

1. Mapbox Globe vs Flat Map. Should MNG default to a globe view (emphasizing the earth observatory identity) or flat map (practical for local navigation)?

2. Terrarium Integration. The 3D terrarium widgets are indexed but not yet integrated into yea.earth. What rendering approach is appropriate -- Three.js in a drawer, or a separate page?

3. Collector Migration. Should MEO v7's collectors be forked into MNG's codebase, or should MNG continue reading MEO v7's databases directly?

4. Spatial Surveyor Workflow. How does field data (panorama transects, GPS tracks, field observations) flow from the Surveyor into MNG?

5. Intelligence Budget. Tier 3 (Claude API) and Tier 4 (extended analysis + web search) have cost implications. What is the acceptable budget per site per day?

6. Timeline Realism. The 16-week development sequence assumes focused work. Actual availability and priority relative to other Macroscope projects must be determined.

7. Conclusion

Macroscope: Next Generation consolidates four years of ecological monitoring platform development into a unified architecture. By building on yea.earth's proven UI patterns, Galatea Macroscope's agent infrastructure, and MEO v7's operational reliability, MNG avoids starting from scratch while addressing the limitations of each predecessor. The four-tier intelligence pipeline (Observation, Verification, Interpretation, Discovery) provides a framework for incremental development where each tier adds value independently. The federated twin-database architecture cleanly separates public ecological data from private observatory data, and the site/platform/sensor hierarchy resolves the naming confusion that hindered macroscope.nexus. The production version will be deployed as macroscope.nexus on Galatea, with the internal version incorporating HOME and SELF monitoring and intelligence on Data.

8. References

[1] Abbe, E., Braverman, M., Hod, S., Lempel, E., & Nakkiran, P. (2025). "Aletheia: A Large-Scale Dataset for Autonomous Mathematical Reasoning." Google DeepMind. arXiv:2602.10177.

[2] WeatherFlow (2024). "Tempest Weather System API." https://weatherflow.github.io/Tempest/ (accessed March 29, 2026).

[3] BirdWeather (2024). "BirdWeather API Documentation." https://app.birdweather.com (accessed March 29, 2026).

[4] Open-Meteo (2025). "Open-Meteo Free Weather API." https://open-meteo.com (accessed March 29, 2026).

[5] Cornell Lab of Ornithology (2025). "eBird API 2.0." https://documenter.getpostman.com/view/664302/S1ENwy59 (accessed March 29, 2026).

[6] iNaturalist (2025). "iNaturalist API v1." https://api.inaturalist.org/v1/docs/ (accessed March 29, 2026).

Document History