How artyom-beilis/skyhopper works
Project type and purpose
• AstroHopper is a Pure-Client Progressive Web Application (PWA).
• Its purpose is to allow users to align a telescope by “hopping” from a known bright object to a fainter one using the phone’s orientation sensors.
• It runs entirely in a modern browser (desktop or mobile), works offline, and requires no server-side application logic.
File structure
Top level files/directories and their roles:
• HTML entry points: index.html, astrohopper.html (single-page app)
• Assets: images/, western_constellations_atlas_of_space/, vsop87-multilang/ (static data folders)
• JavaScript data & logic: vsop87a_combined.js, other JS modules embedded in HTML
• PWA configuration: manifest.json, sw.js (service worker), cert.pem (for HTTPS deployment)
• Build/deploy/dev scripts: create_data.py (generates JS data files), pyserver.py (local dev HTTP server), deploy.py
• Templates/partials: header.html, footer.html
• Documentation: README.md, README_developers.md, Changelog.md, COPYING.md
Key insights from README
• Single-page app, offline-first behavior via service worker and browser cache.
• Primary dependencies: standard Web APIs (DeviceOrientation, Geolocation), browser storage (localStorage), and static JS data.
• External integrations: Wikipedia iframe, optional network access for Wikipedia and online geolocation.
Main components
a. Client Device & Sensors
• DeviceOrientation API (gyro, gravity)
• Geolocation API
• Optional Compass API (heading)
b. Browser Runtime
• HTML/CSS/JS Engine
• UI Layer (canvas or DOM map, control buttons)
• Data Layer (in-memory JS objects, watch lists in localStorage)
• Service Worker & Cache Storage
• IndexedDB or localStorage for user data (watch lists, user objects)
c. Static Asset Host
• GitHub Pages or any static HTTP(S) server
• HTTPS + Service Worker scope (cert.pem in local deploy)
d. External Services
• Wikipedia iframe (when clicking “W”)
• Optional network for geolocation fallback
• create_data.py (builds vsop87 data)
• deploy.py (push to gh-pages)
• pyserver.py (local testing)
Relationships and interactions
• On load, Browser fetches index.html/astrohopper.html, CSS, JS, manifest.json, sw.js from Static Asset Host.
• Service Worker intercepts requests → populates Cache Storage → enables offline.
• UI code registers event listeners on DeviceOrientation and Geolocation → updates viewing direction.
• User alignment/telescope hopping flows through JS modules → updates canvas/DOM.
• Watch list and User Objects persisted to localStorage.
• On Wikipedia lookup, UI opens iframe to Wikipedia.org (optional network).
Architectural patterns and design principles
• PWA offline-first: Service Worker → Cache → Static content
• Modular JS data (astronomical databases separated from UI logic)
• Single responsibility: UI module, Data module, Sensor module
• Separation of concerns: Build scripts vs. runtime code