planet/docs/plans/earth-bgp-earth-rendering-plan.md

BGP Earth Rendering Plan

Goal

This document defines how the BGP region activity layer and incident layer should coexist on Earth without conflicting.

The main question it answers is:

• how to add a regional observability background layer
• without weakening the current incident-first event focus

Core Principle

The Earth design should follow a strict semantic hierarchy:

• collector layer = observation infrastructure
• region activity layer = background situational awareness
• incident layer = focal high-confidence event objects

In short:

• collectors prove the network is observing
• regions show where routing behavior is active or abnormal
• incidents show the concrete event worth clicking

Region aggregation is therefore not a replacement for incident rendering. It is the context layer that makes sparse incident markers legible.

Rendering Hierarchy

Recommended visual stack order:

1. collector network / collector halos
2. region activity glow
3. incident markers and incident pulses

This ordering should always hold.

Why:

• collectors should stay visible but quiet
• regions should create ambient activity presence
• incidents must remain the first thing users notice as a concrete event

Role Separation

Region Layer

The region layer answers:

• where is routing activity building up
• where is there current noise or instability
• which part of the world is currently worth looking at

The region layer should feel:

• broad
• ambient
• low-frequency
• contextual

Incident Layer

The incident layer answers:

• which exact event should the user inspect
• where is the highest-confidence routing event located right now

The incident layer should feel:

• sharp
• compact
• high-contrast
• intentionally clickable

Non-Conflict Rules

To avoid visual and semantic conflict, these implementation rules should be treated as hard constraints:

1. region markers must not use the same symbol language as incidents
2. region emphasis must stay weaker than incident emphasis
3. region animation frequency must stay lower than incident animation frequency
4. incident markers must always render above region glows
5. region layer should support the event, not compete with it

If a user notices the region layer first but misses the incident marker, the region layer is too strong.

If a user only sees isolated incident points and cannot feel broader activity context, the region layer is too weak.

Region Rendering Rules

The region layer should not be rendered as a second kind of incident point.

Recommended representation:

• diffuse glow
• halo
• low-detail pulse
• soft center, not a sharp icon

Status Mapping

observing

• weak glow
• cool color, such as cyan or blue
• little to no pulse
• purpose: keep the globe alive during calm periods

anomaly

• stronger glow
• warmer color, such as amber
• gentle breathing or low-frequency pulse
• purpose: show that a region is experiencing abnormal routing noise

incident

• strongest regional background emphasis
• still clearly weaker than the incident marker itself
• purpose: lift the surrounding area so the focal event does not feel isolated

Region Visual Characteristics

Recommended properties:

• large radius
• low opacity
• soft edge
• low-contrast outline or no outline
• low pulse amplitude

Avoid:

• sharp symbol shapes
• strong icon silhouettes
• bright hard-edged centers
• incident-like pulse language

Incident Rendering Rules

The incident layer should remain visually sharper and more explicit than region activity.

Recommended qualities:

• clear event symbol
• compact hot core
• one or two outward ring pulses
• high contrast
• clear click target

The incident layer should read as:

• focal
• deliberate
• high-confidence

while the region layer should read as:

• contextual
• ambient
• supporting

Region And Incident In The Same Area

When a region contains one or more incidents:

• the region glow may intensify
• but the incident marker must remain the dominant local feature

Interpretation should be:

• region says this area is in an event state
• incident marker says this is the concrete event object

So a region with incident status is not itself the event marker. It is the background state around the event.

Interaction Model

Interaction should also preserve hierarchy.

Click Region

Open a regional situation view, such as:

• region name
• observation count
• anomaly count
• incident count
• affected prefix count
• affected ASN count
• recent incidents in the region

Click Incident

Keep the current incident-focused detail interaction.

This creates a natural two-step flow:

1. region gives context
2. incident gives detail

Layer Relationship To Existing BGP Elements

Collector Layer

Collectors should remain:

• quieter than regions
• more infrastructural than semantic
• proof of coverage, not proof of incident

Region Layer

Regions should become:

• the main ambient activity layer
• the bridge between collectors and incidents
• the answer to low-density map quietness

Incident Layer

Incidents should remain:

• the most legible event layer
• sparse but dominant
• compact and symbol-driven

Practical Visual Test

Use this test when tuning the Earth implementation:

Calm Period

Expected result:

• collectors visible
• some weak region glows present
• no region feels alarm-heavy
• globe still feels alive

Anomaly Period

Expected result:

• one or more regions brighten noticeably
• user can sense the active area before clicking
• still no confusion between region background and incident objects

Incident Period

Expected result:

• region provides broader context
• incident marker is the first explicit focal object the eye lands on
• user can immediately tell both:
  • which region is active
  • which specific event to inspect

Failure Modes To Avoid

Region Too Strong

Symptoms:

• incident markers disappear into the glow
• users treat the region center as the main event
• the map feels like area flooding instead of event focus

Region Too Weak

Symptoms:

• incident markers still feel isolated
• low-incident periods still look visually empty
• users cannot tell where routing activity is generally happening

Region Uses Incident Language

Symptoms:

• region and incident both look like event markers
• users cannot distinguish context from event

Final Design Rule

The desired reading order is:

1. see the specific incident marker
2. feel the active region around it
3. understand that collectors and background activity keep the globe alive even during quieter periods

In one sentence:

incident is the point; region is the field.