Killington GIS Viewer — Software Architecture

Project Context: World Cup Course Crew & GIS Mapping Platform for Killington Mountain ("The Beast") and Pico Mountain, VT.
Author: Phillip Sweeney (phillipjsweeney@gmail.com) with Google DeepMind / Anthropic Opus 5.5.
Architecture Style: dbserver pattern (Node.js/Express, flat-file JSON tables, dark theme UI, model-viewer GLB streaming, GCP App Engine Standard).

Technology Stack Summary

Layer Component Specification & Details
Server RuntimeNode.js 22.x + Express 4.21REST API routes, static file streaming, sanitized configuration endpoints
GIS EngineLeaflet.js 1.9.4Multi-layer engine: Standard OSM, Clean Terrain, ESRI Satellite, USGS Topo
Google MapsGoogle Maps JavaScript APITerrain mode with custom natural styling, GPS course lines & polygons
3D Mesh ViewerGoogle <model-viewer> 3.5.0WebGL / WebGPU PBR renderer for high-resolution 3D terrain meshes (GLB)
DEM Elevation SourceAWS Open Data Terrarium / USGS 3DEP1-meter resolution elevation grids, keyless automated download fallback
Elevation PipelinePython 3.13 (rasterio, trimesh, PIL)GeoTIFF downsampling, normal calculation, vertex coloring & GLB export
Database LayerFlat JSON files (/database/)db-trails.json, db-settings.json (Zero external DB dependency)
Hosting TargetGCP App Engine Standardruntime: nodejs22, project mkatlabs, service killington
DiagrammingMermaid.js (Dark Theme)Live client-rendered system flowcharts, DFDs, and ER diagrams

System Architecture Diagram

graph TD subgraph Client Browser A1[GIS Map - Leaflet] A2[Google Maps View] A3[Superstar 3D - model-viewer] A4[Trail Map Exporter] end subgraph GCP App Engine Standard B[Express Server - server.js] C1[(db-trails.json)] C2[(db-settings.json)] C3[config.json] C4[glb_files/ Directory] end subgraph Offline / CLI Python Pipeline D1[fetch_elevation.py] D2[dem_to_glb.py] E1[AWS Open Terrain / Terrarium] E2[OpenTopography API] end A1 -->|HTTP GET /| B A2 -->|HTTP GET /google-maps| B A3 -->|HTTP GET /glb_files/*.glb| B A4 -->|Download Trigger| E1 B --> C1 B --> C2 B --> C3 B --> C4 D1 -->|Fetch Elevation| E1 D1 -.->|Optional Key| E2 D1 -->|GeoTIFF| D2 D2 -->|Generate GLB| C4

Data Flow Sequence (DFD)

sequenceDiagram autonumber participant U as Course Crew User participant B as Web Client participant S as Express Server participant DB as JSON Database participant GLB as 3D GLB Storage U->>B: Open Dashboard (index.html / superstar-3d) B->>S: GET /api/config (Sanitized Config) S-->>B: Return Bounding Boxes & Map Defaults B->>S: GET /api/trails S->>DB: Read database/db-trails.json DB-->>S: Trail Metrics & GPS Quads S-->>B: JSON Trail Data B->>GLB: Stream /glb_files/superstar_terrain.glb GLB-->>B: Binary GLB Mesh (4.98 MB) B-->>U: Render Interactive 3D Terrain + Hot Pink Course

News Feed, Mountain Cam and Visits Architecture (2026-11-16)

Daily data is made on the PC by scheduled tasks, kept as flat JSON by date, and read by the site through one small store (utils/store.js: the data/ folder on the PC, the project bucket on App Engine). Nothing is deleted or overwritten.

graph LR subgraph Sources GN[Google News RSS search] KW[killington.com Live Webcams page] FIS[FIS official result sheets] WEB[Public web research] end subgraph PC scheduled tasks FN[fetch_news.py
daily 06:15] WS[webcam_snapshot.py
sunrise +45 min, sunset -30 min] BT[build_teamstats.py] BS[build_stories.py] end subgraph Stores flat JSON ND[(data/news/DATE.json)] WD[(data/webcam/index.json + pictures)] TS[(database/db-teamstats.json)] ST[(database/db-stories.json)] VD[(data/visits/DATE/instance.json)] end subgraph Site server.js + utils/site-data.js AN[GET /api/news] AW[GET /api/webcam] AV[POST /api/visit
GET /api/admin/visits] end subgraph Pages TK[News ticker on every page] NP[news.html] WP[webcam.html + LIVE MOUNTAIN] TP[team-stats.html + teams.html] AP[admin.html Dashboard] end GN --> FN --> ND --> AN --> TK AN --> NP TS -. racer names and teams drive the searches .-> FN KW --> WS --> WD --> AW --> WP FIS --> BT --> TS --> TP WEB --> BT WEB --> BS --> ST --> NP ST --> TK TK -. every page load .-> AV --> VD AV --> AP
FeedWhenWhat is keptHow a headline is sorted
News (scripts/fetch_news.py)Every morning 06:15, one file per dayHeadline, source, link, date. No article text. Searches: the event; the last race and the next three; every racer with a biography and each team's two best scorers. Topic: killington, races, stories (family, comeback, interview, video ...) or teams. Teams and racers are tagged by matching the racers' surnames.
Mountain Cam (scripts/webcam_snapshot.py)45 min after sunrise and 30 min before sunset (computed for Killington)Page picture + thumbnail + one record per pictureid = date (morning) or date_evening
Team data (scripts/build_teamstats.py)After each raceOne row per starter per race, from the FIS sheetStandings, start order, team totals and each racer's season are worked out from the rows, never stored twice
VisitsEvery page viewTime, page, IP, place, referrer, browser, bot flagOne file per day; admin only

Entity Relationship Diagram (ERD)

Every store of the site and how they connect, generated from the real data files by scripts/make_erd.py (field names = the first record of each store). Lines are right-angled; the ends show the cardinality: | one, o zero, crow's foot many. Versioned: docs/erd_vN.svg, older versions kept.

Entity Relationship Diagram of the Killington World Cup site

Team and racer names come from the FIS result sheets (125 racers, 32 teams after the first two races); 30 racers also have a researched biography. Field lists: docs/requirements.md (Data).

Superstar World Cup Coordinates Specification

Feature South / West Corner North / East Corner Visual Styling
Superstar World Cup Course Line 43.60722, -72.80242 (Finish) 43.61771, -72.80206 (Start Gate) Hot Pink (#ff1493) with fluorescent glow
Superstar Trail Quad S: 43.60704, W: -72.80456 N: 43.61771, E: -72.80027 Red Boundary (#ff4444)
Superstar Event & Race Area S: 43.60655, W: -72.80678 N: 43.61774, E: -72.79828 Orange Dashed Area (#ffaa00)
Pico Ski Area Bounds S: 43.62200, W: -72.85200 N: 43.63800, E: -72.83500 Cyan Dashed Area (#00ccff)

Use Cases & Requirements Notepad