diff --git a/README.md b/README.md index f7d9a4b..d6231b4 100644 --- a/README.md +++ b/README.md @@ -154,6 +154,7 @@ gone private; see [Troubleshooting](docs/troubleshooting.md#docker-compose-up-fa - [High level design](docs/high-level-design.md): how it works, the schema, the ingest pipeline. - [API contract](docs/api-contract.md): REST, WebSocket, admin endpoints, errors. +- [My Atlas](docs/my-atlas.md): the per-browser node watchlist and what its cards mean. - [Backup and export](docs/backup-export.md) and [CPU profiling](docs/profiling.md). **Change it** diff --git a/docs/configuration.md b/docs/configuration.md index af797a6..854d745 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -40,7 +40,7 @@ Visitors get the new values on their next page load. Any characters are fine in | `VITE_API_BASE` | yes | REST base URL as the browser sees it, for example `https://beacon.example.com/api/v1`. It must be the public address, never `localhost`. | | `VITE_WS_URL` | yes | WebSocket URL as the browser sees it, for example `wss://beacon.example.com/ws`. | | `VITE_MAP_CENTER`, `VITE_MAP_ZOOM` | no | Fallback map view as decimal `lat,lon` and a zoom from 0 to 22, used before airports load or when the selected region has no location. Unset is a world view. | -| `VITE_DISABLED_TABS` | no | Comma-separated tabs to hide. Options: `Packets,Channels,Map,Nodes,Observers,Routes,Traces,Analytics`. | +| `VITE_DISABLED_TABS` | no | Comma-separated tabs to hide. Options: `Packets,Channels,Map,Nodes,Observers,Routes,Traces,Analytics,MyAtlas`. | | `VITE_ENABLED_THEMES` | no | Comma-separated theme ids. When set, only these themes are offered. Listing `meshmapper_dark` or `meshmapper_light` is the only way to enable those two. | | `VITE_APP_NAME` | no | Wordmark text in the top left. Default `BEACON`. | | `VITE_SKIP_SPLASH` | no | `true` skips the once-per-session loading splash. | diff --git a/docs/my-atlas.md b/docs/my-atlas.md new file mode 100644 index 0000000..d38f88f --- /dev/null +++ b/docs/my-atlas.md @@ -0,0 +1,43 @@ +# My Atlas + +A per-browser watchlist of up to twelve nodes, each shown as a card of recent activity and signal. +It is the last tab in the desktop row and under **More** on a phone; the URL is `?tab=MyAtlas`. +Hide it for a deployment with `VITE_DISABLED_TABS=MyAtlas` (see [Configuration](configuration.md)). + +## What is stored, and where + +Pins live only in the visitor's browser, under the localStorage key `beacon-my-atlas-v1`: +node ID, full public key, last known name, card order and the activity window (24h or 3d). +There is no account and no sync between browsers or devices; clearing site data removes the +collection. If storage is unavailable, the page says so and edits last for the visit. + +Pins are keyed by the full public key. If a server reset changes a node's ID, the page looks the +key up again before loading anything and saves the new ID; it never adopts a different node at +the old ID. A node that cannot be loaded stays on the page and can still be removed. + +## Search + +**Add nodes** searches every region by name or hexadecimal public-key prefix (the region picker +does not apply to this tab). A search needs at least two characters, and a non-hex key is not sent +to the server; the card says which rule is holding a search back. Each result shows its key prefix +(the full key on hover) so two nodes with the same name can be told apart before adding one. + +## Reading a card + +Each card is the Analytics Signal row for one node, over the selected window: + +- **Observations** — stored receptions of packets originating from that key. The card loads the + latest 200; when those do not reach back to the start of the window, the tile says "latest 200" + and the bars start at the oldest loaded reception rather than drawing empty hours the sample + cannot speak for. +- **Mean SNR / Mean RSSI** — averages of the observers' last-hop measurements, with an hourly + sparkline. The zero-RSSI / zero-SNR "no measurement" sentinel is excluded; a real zero SNR is + included. These describe the receivers' side, not the node's radio health. +- **Active hours** — hours in the window with at least one reception. +- The freshness badge is the server's `stale` verdict; the client does not infer online/offline. +- **Heard by** lists the observers of the newest loaded packet, with when it was heard, and opens + that packet in the analyzer. It is not lifetime reach. +- On a narrow card the action buttons drop under the name rather than crowding it. + +Every card polls once a minute while the tab is open, keeps polling through a failed refresh, and +pauses while the server is rate-limiting.