maptool/docs/architecture.adoc

Architecture

Table of Contents

• Overview
• Directory layout
• Offline maps
  • Known limitation: no offline text labels
• Weather radar overlay
• Networking

Overview

MapTool is a Sinatra web application, served locally by Puma and opened in a browser.

Directory layout

Path	Purpose
app.rb, config.ru	Sinatra application and Rack entry point.
config/puma.rb	Puma server configuration (binds to 127.0.0.1 only — the app is local-only, not exposed on the network).
public/, views/	Frontend assets and Sinatra templates. The map view uses MapLibre GL JS, rendering vector tiles.
public/vendor/	Third-party frontend libraries, vendored (not loaded from a CDN) so the app also works with no internet access. See docs/third-party-notices.adoc.
data/	Local, gitignored data files, e.g. offline.pmtiles.
docs/	Project documentation, in AsciiDoc.

Offline maps

Map data is vector, not raster: the app ships MapLibre GL JS (vendored, see below) and the map view (public/js/map.js) offers two styles:

• Online — a full hosted vector style, OpenFreeMap "liberty", requires internet access.

• Offline — built at runtime from a local PMTiles archive at data/offline.pmtiles, served as-is (see below) at /tiles/offline.pmtiles, decoded client-side by pmtiles.js registered as a pmtiles:// protocol handler, and styled with base layers from protomaps-themes-base.

GET /api/offline-tiles reports whether data/offline.pmtiles is present ({"available": true|false}); the frontend uses it once, on load, to default to the offline style when local tile data exists — otherwise it defaults to the online style. Either way, the layer toggle in the top-left of the map lets the user switch manually.

PMTiles is a single, self-indexed file, which is why this needs no tile-decoding logic on the server: app.rb’s `/tiles/offline.pmtiles route (send_file, which Sinatra serves with HTTP range-request support) just returns byte ranges of the file; pmtiles.js in the browser reads the archive’s own directory and requests only the bytes it needs for the tiles on screen.

Known limitation: no offline text labels

The offline style only renders `protomaps-themes-base’s non-label layers (roads, buildings, land use, water — no place names or street labels). Label rendering in MapLibre needs a "glyphs" server serving font PBF ranges, which would mean vendoring a font glyph set locally too; that has not been done, to keep the initial scope manageable. Revisit this if labelled offline maps turn out to matter in practice.

No PMTiles file ships with the repository — it is expected to be supplied locally (see docs/development.adoc) and stays gitignored because such extracts are typically large binary files.

Weather radar overlay

public/js/radar.js adds a "Radar" map control that overlays recent precipitation radar from RainViewer's free public API (no API key required). Enabling it:

1. Fetches https://api.rainviewer.com/public/weather-maps.json, which lists RainViewer’s past radar frames (fixed 10-minute cadence, at most 13 covering the last 120 minutes).

2. Takes the most recent 7 (last ~60 minutes — the same default as the Home Assistant weather-radar-card, for a consistent feel with that setup) and adds one MapLibre raster source/layer per frame, all pre-loaded but only the current frame’s raster-opacity non-zero.

3. Animates by toggling that opacity across frames on an interval (play/pause + a scrub slider), rather than swapping tiles in and out — avoids reloading tiles on every step.

Tile URL: {host}{frame.path}/256/{z}/{x}/{y}/2/1_0.png — 2 is RainViewer’s "Universal Blue" color scheme, 1 enables their smoothing, 0 disables the snow overlay. host and each frame’s path come from the API response.

Since map.setStyle() (switching Online/Offline) tears down all custom sources and layers, the control listens for style.load and re-adds the radar layers if the overlay was on.

This is a live, online-only overlay — it always needs internet access and is unrelated to the offline PMTiles basemap above. Per RainViewer’s terms, the API is free for personal/non-commercial use.

Networking

The Sinatra server only binds to 127.0.0.1. It is not meant to be reachable from other machines.