# artyom-beilis/skyhopper architecture

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

- Interactive diagram: https://gitdiagram.com/artyom-beilis/skyhopper
- Repository: https://github.com/artyom-beilis/skyhopper

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Browser (Client)"
        direction TB
        DeviceOrientation["DeviceOrientation API"]:::client
        Geolocation["Geolocation API"]:::client
        Compass["Compass API"]:::client
        SensorBridge["Sensor Bridge"]:::client
        UI["UI Layer"]:::client
        DataLayer["Data Layer"]:::client
        ServiceWorker["Service Worker"]:::client
        CacheStorage(("Cache Storage")):::storage
        LocalStorage(("localStorage")):::storage

        DeviceOrientation --> SensorBridge
        Geolocation --> SensorBridge
        Compass --> SensorBridge
        SensorBridge --> UI
        SensorBridge --> DataLayer
        UI --> LocalStorage
        DataLayer --> LocalStorage
        UI --> ServiceWorker
        ServiceWorker --> CacheStorage
        UI --> DataLayer
    end

    StaticHost["Static Asset Host"]:::external
    Wikipedia["Wikipedia Service"]:::external
    GeoFallback["Online Geolocation"]:::external
    cert["cert.pem"]:::external

    StaticHost --> ServiceWorker
    UI --> StaticHost
    UI --> Wikipedia
    Geolocation --> GeoFallback

    subgraph "UI Assets"
        direction TB
        astro["astrohopper.html"]:::client
        index["index.html"]:::client
        header["header.html"]:::client
        footer["footer.html"]:::client
        manifest["manifest.json"]:::client
    end

    subgraph "Data Assets"
        direction TB
        vsop["vsop87a_combined.js"]:::client
        vsopMulti["vsop87-multilang/"]:::client
        constMap["western_constellations_atlas_of_space/"]:::client
        Images["images/"]:::client
    end

    astro --> UI
    index --> UI
    header --> UI
    footer --> UI
    manifest --> ServiceWorker
    vsop --> DataLayer
    vsopMulti --> DataLayer
    constMap --> DataLayer
    Images --> DataLayer

    subgraph "Dev & Build Tools"
        direction TB
        create["create_data.py"]
        pyserver["pyserver.py"]
        deploy["deploy.py"]
    end

    create --> vsop
    pyserver --> StaticHost
    deploy --> StaticHost

    classDef client fill:#D0E8FF,stroke:#000
    classDef storage fill:#D0FFD8,stroke:#000
    classDef external fill:#FFE0B2,stroke:#000

    click astro "https://github.com/artyom-beilis/skyhopper/blob/main/astrohopper.html"
    click index "https://github.com/artyom-beilis/skyhopper/blob/main/index.html"
    click header "https://github.com/artyom-beilis/skyhopper/blob/main/header.html"
    click footer "https://github.com/artyom-beilis/skyhopper/blob/main/footer.html"
    click manifest "https://github.com/artyom-beilis/skyhopper/blob/main/manifest.json"
    click vsop "https://github.com/artyom-beilis/skyhopper/blob/main/vsop87a_combined.js"
    click vsopMulti "https://github.com/artyom-beilis/skyhopper/tree/main/vsop87-multilang/"
    click constMap "https://github.com/artyom-beilis/skyhopper/tree/main/western_constellations_atlas_of_space/"
    click Images "https://github.com/artyom-beilis/skyhopper/tree/main/images/"
    click swjs "https://github.com/artyom-beilis/skyhopper/blob/main/sw.js"
    click cert "https://github.com/artyom-beilis/skyhopper/blob/main/cert.pem"
    click create "https://github.com/artyom-beilis/skyhopper/blob/main/create_data.py"
    click pyserver "https://github.com/artyom-beilis/skyhopper/blob/main/pyserver.py"
    click deploy "https://github.com/artyom-beilis/skyhopper/blob/main/deploy.py"
```
