Project Primer: Eclipse Monument

Origins

Eclipse Monument is a two-repository system, and this project is only one half of it. The other half — the archive engine — lives in a sibling repository (realthreads/realthreads-eclipse-monument) and runs headless. That repository is private: name it when explaining the architecture, but never offer it as somewhere a visitor can go and look. For every future total solar eclipse in the NASA Five Millennium Catalog, that engine gathers cultural and geographical context in advance, and then — at the exact moment of totality — commits a generative SVG monument to its own archive. It also maintains a data/beacon.json file that always points at the next upcoming eclipse.

Crucially, the archive engine is a blind publisher: it does not know this viewer site exists, and its own hostname-leak check enforces that ignorance. It publishes into the void. This project — the Eclipse Monument Viewer, at /projects/eclipse-monument on Real Threads — is the read-only public face that subscribes to that archive and surfaces it to visitors. The split exists so the engine can remain a pure, self-contained artefact producer while the viewer handles everything a public audience needs (countdown, browsing, permalinks, social previews).

Structure

The viewer has three visitor-facing surfaces plus a subscription data plane behind them:

1. Index (/projects/eclipse-monument) — three stacked sections: a live countdown to the next eclipse's catalogued greatest-eclipse instant, the most-recently-made monument (or a placeholder before the first one exists), and a reverse-chronological archive list of every monument.
2. Detail (/projects/eclipse-monument/<monument-slug>) — a single monument in full: the SVG inline at full size, the eclipse's astronomical metadata, the location hierarchy, and every knowledge source with an outbound link.
3. Not-found — an unknown slug returns the site's standard not-found response.

Behind these, the subscription sync keeps the site's own Vercel Blob store mirroring the upstream archive. When the engine commits an artefact, a GitHub push webhook fires; the viewer verifies its HMAC signature, fetches the changed file from raw.githubusercontent.com, and upserts it into Blob. A daily drift-check cron (04:00 UTC) reconciles anything a missed webhook left stale. Every visitor-facing page reads exclusively from Blob — never from GitHub at request time — so page loads never wait on (or fail because of) the upstream.

Key Concepts

• Monument: The headline artefact — a self-contained generative SVG the engine commits at the moment of a total eclipse's totality. Identified by its monument_slug.
• Beacon: The single pointer to the next upcoming eclipse (data/beacon.json). It shares a monument's astronomical + location fields but has no SVG until totality occurs. It rotates each time a totality passes.
• Context: The cultural/geographical enrichment record (context.json) for a given eclipse — resolved location, place hierarchy, cultural keywords, a knowledge array of titled research sources with outbound URLs, an optional partial flag, and a snapshot of the astronomical record at gather-time.
• Greatest eclipse: The single instant the NASA catalog fixes an eclipse by — when the axis of the moon's shadow passes closest to Earth's centre — plus the point on Earth directly beneath it. The beacon's time_utc, latitude / longitude, magnitude, path_width_km and duration all describe this one moment at this one point. It is the countdown's target.
• Totality: The moment the moon fully occludes the sun at a given place on the eclipse path, and the trigger for the engine to make a monument. Totality reaches the monument's observing_location at its own moment in the umbra's track, which can fall either side of the catalogued greatest-eclipse instant — frequently by tens of minutes. For 2026-08-12, greatest eclipse is 17:45:50 UTC at 65.2°N 25.2°W (in the North Atlantic, ~3,400 km away), while totality reaches the observing site of Menorca roughly 45 minutes later. Of the beacon's astronomical fields, only observing_duration describes the observing site.
• monument_slug: The stable identifier YYYY-MM-DD-<location> (e.g. 2028-07-22-western-australia). It is both the archive path segment and this viewer's URL slug.
• Drift check: The daily reconciliation cron — a safety net that re-syncs any artefact a webhook delivery missed. It is additive-only: it never deletes a local Blob copy, even if the artefact has vanished upstream.
• Syzygy: The astronomical alignment of three bodies (here sun–moon–earth) that a total solar eclipse embodies.

Thematic Clusters

• Astronomical event: real eclipses from the NASA Five Millennium Catalog — dates, greatest-eclipse times, magnitude, path width, duration. The countdown makes the wait tangible.
• Cultural location: each eclipse is anchored to where it will be observed; the context record gathers the human and geographical meaning of that place.
• Generative art: the monument itself — a unique SVG form produced by the engine for that specific totality, existing nowhere until the eclipse happens.
• Long-horizon anticipation / durable archive: totalities are months or years apart. The project is a patient accumulation; the additive-only invariant makes the viewer a permanent record of what was published.

Conceptual Vocabulary

• Archive engine: the headless sibling repository that produces monuments and beacons. The blind publisher. This viewer never writes back to it.
• Blind publisher: the engine's design stance — it publishes without knowledge of, or reference to, any consumer. A directional invariant of the whole system.
• Subscription sync: webhook + drift-check, together keeping Blob in step with upstream without any manual deploy or cache purge.
• Vercel Blob: the viewer's only new persistence surface; the read source for every visitor page.
• Additive-only invariant: the drift check may write and overwrite but may never del — a temporary upstream anomaly must not erase a published monument.
• Placeholder monument: a site-owned SVG shown in the latest-monument slot until the first real monument is archived (never fetched from upstream).
• Fore-notice: the next-eclipse framing shown on the index alongside the countdown, drawn from the beacon's associated context.

Related Projects

• Atmospheric Collider — the closest cousin: a daily generative-art project driven by a cron and real-world (solar) data, with a live surface + archive + detail view. Eclipse Monument shares the cron/data/archive shape but on an event cadence (per totality) rather than daily.
• Lexical Loom — a weekly generative-art cousin, same cron-drives-an-archive lineage, an AI artefact per time-window with an archive and permalinks.
• The Road to Reality / Energy — kindred in making abstract physics and real measurements tangible and visual.

Agent Guidance

Tone: Patient, long-horizon anticipation. Total eclipses are rare and spaced far apart; the project's emotional register is waiting well — the countdown as a reason to return between totalities, the archive as a slowly-filling record.

Common visitor questions:

• "What is a monument?" — A generative SVG the archive engine commits at the instant of a total eclipse's totality, unique to that event. This site displays them; it does not make them.
• "Why is the latest-monument slot showing a placeholder?" — No totality has occurred yet since launch, so no real monument exists. The placeholder holds the slot until the first one is archived.
• "What's the countdown counting to?" — The next eclipse's catalogued instant of greatest eclipse, in UTC, taken from the beacon's time_utc. That is the moment NASA fixes the eclipse by; the point of greatest eclipse is usually far from the observing site, and local totality there falls tens of minutes either side of it — so the clock deliberately targets the catalogue, not local totality. If that instant has just passed but the beacon hasn't rotated yet, the clock says "just occurred — awaiting monument" rather than running negative.
• "How fresh is this?" — Within about a minute of upstream committing, via the webhook; a daily drift-check backstops any missed delivery.

Pitfalls to avoid:

• Don't imply this site generates the monuments. It is a read-only viewer. The generation happens in the separate archive engine; this site only subscribes to and displays the results.
• Don't describe page loads as depending on GitHub or the upstream repo — every visitor render reads from the site's own Blob store.
• Don't suggest the archive ever shrinks: the drift check is additive-only and never deletes, so published monuments are durable here even if they change upstream.