How safecast/tilemap works
Project type and purpose
• It provides map tile overlays, a bGeigie log viewer, a raster cell lookup HUD, and a real-time sensor viewer.
File structure
• Top-level files: index.html, safemap.js (main codebehind), bitstore.js, bgeigie_viewer.js, rt_viewer.js, hud.js, slideout.min.js, various HTML partials, CSS, images, config (package.json)
• Directories:
• server_scripts – shell scripts to generate, retile, and sync map tiles to S3
• prototype – experimental pages
• Build/deploy scripts: setup.sh, new-proxy-server.js, api-proxy.js
• No backend code here – it’s pure front-end plus deployment scripts.
Insights from README
• Components are loaded asynchronously via proxy pseudo-classes to avoid race conditions.
• External dependencies:
• Google Maps API v3
• bitstore.js (external library)
• Data sources:
• api.safecast.org (Ruby + PostgreSQL API)
• safecast.media.mit.edu (OS X VM tile generator)
• Amazon S3 buckets (us-east-1 for production, us-east-1 & us-ap-northeast-1 for tiles, safecast-production for logs)
• rt.safecast.org (real-time sensor JSON)
• 107.161.164.166 (chart image generator)
Main components
a. Client front-end modules
– index.html & UI container
– safemap.js (core orchestrator)
– bitstore.js (tile existence indexer)
– bgeigie_viewer.js (on-demand log viewer)
– rt_viewer.js (always-loaded real-time sensors)
– hud.js (on-demand raster value HUD)
– slideout.min.js (UI menu)
– HTML partials & CSS assets
b. External services & data
– Google Maps API v3 (map base)
– Tile image hosts (S3 buckets & safecast.media VM)
– API server (api.safecast.org) for spatial queries and log metadata
– S3 safecast-production for static bGeigie log files
– Real-time server (rt.safecast.org → devices.json)
– Chart generator (107.161.164.166)
c. Tile generation & deployment pipeline
– api.safecast.org exports raw data →
– Safecast OS X app & Python interpolation cron jobs on safecast.media VM →
– Retile (256×256 → 512×512) →
– s3cmd sync to primary S3 buckets →
– bucket-to-bucket sync to Japan region
Relationships & interactions
• safemap.js directs module loads and UI events
• bitstore.js proxy answers “shouldLoadTile?” before requesting tile URLs
• Tile requests flow to the nearest S3 endpoint (us or jp region) or safecast.media if not yet on S3
• HUD module fetches tile pixel data, then maps RGB to values
• bGeigie viewer fetches log URLs from api.safecast.org, then downloads from safecast-production S3
• rt_viewer.js calls rt.safecast.org for devices.json, then fetches charts from 107.161.164.166
• All external communication is asynchronous
Architectural patterns and principles
• Asynchronous module loading via proxy pseudo-classes to avoid race conditions
• Separation of concerns: a single large orchestrator (safemap.js) with specialized modules loaded on demand
• CDN/distributed static hosting for performance
• Cron-driven batch tile generation and continuous sync to S3
• Minimal backend logic in front-end repo – all server code lives separately