# safecast/tilemap architecture

> Architecture diagram of the GitHub repository safecast/tilemap, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/safecast/tilemap
- Repository: https://github.com/safecast/tilemap

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Front-end (Browser)
    subgraph "Front-end (Browser)"
        direction TB
        UI["index.html"]:::frontend
        Core["safemap.js"]:::frontend
        Bitstore["bitstore.js"]:::frontend
        BGeigie["bgeigie_viewer.js"]:::frontend
        BGeigieWorker["bgeigie_viewer_worker.js"]:::frontend
        RT["rt_viewer.js"]:::frontend
        HUD["hud.js"]:::frontend
        HUDWorker["hud_worker.js"]:::frontend
        FlyTo["fly_to_extent.js"]:::frontend
        MapPolys["map_polys.js"]:::frontend
        PopupFix["popup-fix.js\npopup-fix-simple.js\npopup-fix-clean.js"]:::frontend
        Icons["images/generate-icons.js"]:::frontend
        CSSMain["safemap.css"]:::frontend
        CSSInline["bgeigie_viewer_inline.css"]:::frontend
        About["about_inline.html"]:::frontend
        DebugPopup["debug-popup.html"]:::frontend
        DebugPage["debug.html"]:::frontend
        Methodology["methodology.html"]:::frontend
        WhatsNew["whatsnew_en_inline.html\nwhatsnew_ja_inline.html"]:::frontend
    end

    %% External Services & APIs
    subgraph "External Services & APIs"
        direction TB
        MapsAPI["Google Maps API v3"]:::external
        APIServer["api.safecast.org"]:::external
        RTSrv["rt.safecast.org\n(devices.json)"]:::external
        ChartSrv["107.161.164.166\n(chart images)"]:::external
    end

    %% Tile Storage & Generation
    subgraph "Tile Storage & Generation"
        direction TB
        VM["safecast.media VM\n(tile generator)"]:::storage
        S3US["S3 Bucket (us-east-1)"]:::storage
        S3JP["S3 Bucket (ap-northeast-1)"]:::storage
        LogsS3["S3 Bucket (safecast-production)"]:::storage
    end

    %% Build/Deploy Pipeline
    subgraph "Build/Deploy Pipeline"
        direction TB
        Setup["setup.sh"]:::pipeline
        ProxyNew["new-proxy-server.js"]:::pipeline
        APIProxy["api-proxy.js"]:::pipeline
        SimpleProxy["simple-proxy.js"]:::pipeline
        LegacyProxy["proxy-server.js\nproxy-server-fixed.js"]:::pipeline
        TileSync["server_scripts/TileExportRetileAndSyncS3.sh"]:::pipeline
        DocsReadme["docs/README.md"]:::pipeline
        DocsDiag["docs/diagrams_for_webmap.key"]:::pipeline
        Prototype["prototype/"]:::pipeline
    end

    %% Front-end interactions
    UI -->|loads| Core
    Core -->|orchestrates| Bitstore
    Core -->|orchestrates| BGeigie
    Core -->|orchestrates| RT
    Core -->|orchestrates| HUD
    Core -->|uses| FlyTo
    Core -->|loads| MapPolys
    Core -->|loads| PopupFix
    Core -->|loads| Icons
    Core -->|loads| CSSMain
    Core -->|loads| CSSInline
    Core -->|includes| About
    Core -->|includes| DebugPopup
    Core -->|includes| DebugPage
    Core -->|includes| Methodology
    Core -->|includes| WhatsNew

    Bitstore -->|HTTP GET tiles| S3US
    Bitstore -->|HTTP GET tiles| S3JP
    Bitstore -->|fallback| VM

    BGeigie -->|JSON metadata| APIServer
    BGeigie -->|HTTP GET logs| LogsS3
    BGeigieWorker -->|work| BGeigie

    RT -->|JSON devices| RTSrv
    RT -->|HTTP GET charts| ChartSrv

    HUD -->|pixel lookup| HUDWorker
    HUDWorker -->|HTTP GET tile pixel| S3US
    HUDWorker -->|HTTP GET tile pixel| S3JP

    Core -->|JS Maps| MapsAPI

    %% Tile generation pipeline
    APIServer -->|export raw data| VM
    VM -->|cron jobs & interpolation| VM
    VM -->|256→512 retile| TileSync
    TileSync -->|sync| S3US
    S3US -->|bucket-to-bucket sync| S3JP

    %% Proxy / Deployment
    Setup --> ProxyNew
    Setup --> APIProxy
    Setup --> SimpleProxy
    Setup --> LegacyProxy

    %% Documentation & Prototype
    DocsReadme --> DocsDiag
    DocsReadme --> Prototype

    %% Click Events
    click UI "https://github.com/safecast/tilemap/blob/master/index.html"
    click Core "https://github.com/safecast/tilemap/blob/master/safemap.js"
    click Bitstore "https://github.com/safecast/tilemap/blob/master/bitstore.js"
    click BGeigie "https://github.com/safecast/tilemap/blob/master/bgeigie_viewer.js"
    click BGeigieWorker "https://github.com/safecast/tilemap/blob/master/bgeigie_viewer_worker.js"
    click RT "https://github.com/safecast/tilemap/blob/master/rt_viewer.js"
    click HUD "https://github.com/safecast/tilemap/blob/master/hud.js"
    click HUDWorker "https://github.com/safecast/tilemap/blob/master/hud_worker.js"
    click FlyTo "https://github.com/safecast/tilemap/blob/master/fly_to_extent.js"
    click MapPolys "https://github.com/safecast/tilemap/blob/master/map_polys.js"
    click PopupFix "https://github.com/safecast/tilemap/blob/master/popup-fix.js"
    click Icons "https://github.com/safecast/tilemap/blob/master/images/generate-icons.js"
    click CSSMain "https://github.com/safecast/tilemap/blob/master/safemap.css"
    click CSSInline "https://github.com/safecast/tilemap/blob/master/bgeigie_viewer_inline.css"
    click About "https://github.com/safecast/tilemap/blob/master/about_inline.html"
    click DebugPopup "https://github.com/safecast/tilemap/blob/master/debug-popup.html"
    click DebugPage "https://github.com/safecast/tilemap/blob/master/debug.html"
    click Methodology "https://github.com/safecast/tilemap/blob/master/methodology.html"
    click WhatsNew "https://github.com/safecast/tilemap/blob/master/whatsnew_en_inline.html"
    click ProxyNew "https://github.com/safecast/tilemap/blob/master/new-proxy-server.js"
    click APIProxy "https://github.com/safecast/tilemap/blob/master/api-proxy.js"
    click SimpleProxy "https://github.com/safecast/tilemap/blob/master/simple-proxy.js"
    click LegacyProxy "https://github.com/safecast/tilemap/blob/master/proxy-server.js"
    click TileSync "https://github.com/safecast/tilemap/blob/master/server_scripts/TileExportRetileAndSyncS3.sh"
    click Setup "https://github.com/safecast/tilemap/blob/master/setup.sh"
    click DocsReadme "https://github.com/safecast/tilemap/blob/master/docs/README.md"
    click DocsDiag "https://github.com/safecast/tilemap/blob/master/docs/diagrams_for_webmap.key"
    click Prototype "https://github.com/safecast/tilemap/tree/master/prototype/"

    %% Styles
    classDef frontend fill:#ccffcc,stroke:#006600,stroke-width:1px
    classDef external fill:#ccccff,stroke:#000066,stroke-width:1px
    classDef storage fill:#ffcc99,stroke:#663300,stroke-width:1px
    classDef pipeline fill:#e5ccff,stroke:#660099,stroke-width:1px
```
