Home / Notes / Live map event contract

Field note · live interfaces

Before the map, define the event.

An API can deliver thousands of positions and still leave an operator unable to answer “What changed?” A useful map module starts with the meaning and lifecycle of an event.

1. What is one event?

Agree the stable identifier, type, location or geometry, source and observation time. Decide whether a later message creates a new event or updates an existing one. Without that rule, the interface can duplicate markers or hide a change.

2. When is it stale?

“Live” needs a measurable meaning. The feed owner should define expected update frequency and what the UI shows when a source is late, disconnected or recovering. Put that state near the affected view, not only in a distant system log.

3. What does the operator decide?

Start with one task: inspect a unit, triage a warning, compare a corridor, or prepare a notice. That task determines which filters, details and history belong in the first screen. A map with every layer switched on rarely answers a specific question.

4. Which view is the source of selection?

Map, table, chart and detail panel should refer to the same selected event. The operator needs a clear way to move between them, including by keyboard. If an item falls outside the current map extent or filter, explain where it went.

5. What belongs to the platform?

Write down who owns the feed, identity and permissions, business rules, alerts, exports and 24/7 operation. A front-end module can present and act on these services; it should not silently become responsible for them in a fixed-price scope.

6. How will you accept the work?

Test with sample events that include updates, missing coordinates, out-of-order times, empty results and a disconnected feed. Agree the operator task and expected screen state for each case before the build begins.

These are scoping questions, not a universal data standard. The exact event contract depends on the system and the people using it. Our SWARCO case study shows the operator-facing layer of a connected-mobility project.

Have a feed and an operator task?

A redacted schema is enough for an initial boundary review.