jhiller
README.md

DC Helium Mobile Hotspot Growth Map

An interactive visualization of Helium Mobile hotspot growth in the DC Metro area over time. Watch the network expand from its first hotspot to over 1,000 deployments.

Live demo: https://dc-hotspot-growth.val.run/

Features

  • Interactive Timeline: Scrub through the entire history of DC-area hotspot deployments
  • Animated Playback: Watch hotspots appear over time with play/pause controls
  • H3 Clustering: Hotspots grouped by Uber H3 hexagons (resolution 8) for clean visualization at any zoom level
  • Age-based Coloring:
    • Green: New hotspots (< 7 days old)
    • Blue: Recent hotspots (< 30 days old)
    • Grey: Established hotspots (30+ days old)
  • Hotspot Details: Click any cluster to see individual hotspot names (animal hash format) with links to Helium World

Tech Stack

  • Platform: Val Town (Deno runtime)
  • Backend: Hono HTTP framework
  • Database: Val Town SQLite (Turso)
  • Frontend: React 18 + deck.gl (WebGL)
  • Clustering: Uber H3 hexagonal hierarchical geospatial indexing
  • Map Tiles: CartoDB dark-matter basemap

How It Works

Data Pipeline

  1. Backfill: Initial data populated from the Helium Entity API, filtering for mobile hotspots within the DC Metro bounding box
  2. Daily Cron: Runs at 6 AM UTC to capture new hotspots and track location changes
  3. Pre-computed Snapshots: Daily statistics stored for instant timeline scrubbing

Visualization

The map uses deck.gl's ScatterplotLayer for WebGL-accelerated rendering of thousands of hotspots at 60fps. Circles are scaled using a square root easing curve so that cluster growth is visually apparent without large clusters dominating the view.

Project Structure

dc-hotspot-map/
├── index.ts                 # Hono server & API routes
├── cron.ts                  # Daily scraper job
├── backend/
│   ├── db.ts               # SQLite schema & queries
│   ├── heliumApi.ts        # Helium Entity API client
│   ├── scraper.ts          # Backfill & daily scrape logic
│   └── migrate.ts          # Database migration utilities
├── frontend/
│   ├── index.html          # Entry point
│   ├── components/
│   │   └── App.tsx         # Main React component
│   ├── utils/
│   │   └── animalHash.ts   # Hotspot name generator
│   └── style.css           # Helium-inspired dark theme
└── shared/
    └── types.ts            # TypeScript interfaces

API Endpoints

EndpointDescription
GET /api/hotspotsAll active hotspots with coordinates and dates
GET /api/snapshotsDaily snapshot statistics for timeline
GET /api/statsCurrent total count and latest snapshot

Development

This project uses the Val Town CLI:

# Push changes to Val Town
vt push

# Open in browser
vt browse

Coverage Area

The map covers the DC Metro area with approximately a 50-mile radius:

  • Latitude: 38.5° to 39.3° N
  • Longitude: 77.5° to 76.7° W
  • Cities: Washington DC, Arlington, Alexandria, Bethesda, Silver Spring, College Park, and surrounding areas

Credits

License

MIT