How andythebreaker/minarun works
Project type and purpose
• From the file tree and README, this is a client-side React single-page web application (SPA) packaged as a PWA (“minarun”), with added utilities for converting JSON to GPX. It’s delivered as a static site (GitHub Pages) and can run locally via a Python GUI (setup.py). CI/CD is handled through GitHub Actions.
File structure
• Top-level directories:
• config/webpack* & babel* & jest*: build, test and transform configurations
• public/: static assets, HTML template, PWA manifest
• src/: React source code, styling, PWA service worker, unit tests
• build/: compiled output (JS, HTML, fonts, manifest)
• scripts/: npm lifecycle wrappers (build.js, start.js, test.js)
• .github/workflows/main.yml: CI/CD for build & deploy to gh-pages
• setup.py + json2gpx.py: Python CLI/GUI for JSON→GPX conversion
• example.json, gpx2.js, home_url_change.js: demo and utility scripts
Insights from the README
• Instructions to run locally (npm run serve + pubhtmlhere), build (npm run build), deploy (GitHub Actions).
• Notes on PWA, GPX generation pipeline (DB JSON → GPX via Python or JS), toggling between Linux/Windows via setup.py.
• TODOs around publicPath/homepage consistency.
Main components
a. Developer workstation
• IDE/editor
• Node.js & npm/yarn (package.json)
• Python environment (setup.py, json2gpx.py)
b. Build & Test subsystem
• Babel & webpack config → bundling React code → build/
• Jest transforms & unit tests (src/unit)
• scripts/ orchestrating npm run build, npm test, npm run serve
c. Continuous Integration / Deployment
• GitHub Actions (.github/workflows/main.yml)
• Action “deploy-react-to-ghpages” → publishes build/ to gh-pages
d. Runtime / Client side
• Browser as PWA
• Service Worker (src/src-sw.js, serviceWorkerRegistration.js)
• IndexedDB (demo in garbage/indexeddb.html) or other local cache
• JSON→GPX converter (integrated in JS: src/unit/json2gpx.js; or external Python script)
e. Hosting / External Services
• GitHub Pages static site
• (Optionally) local HTTP server via pubhtmlhere
Relationships & interactions
• Developer → (npm scripts, Python CLI) → Build pipeline → build/
• CI pipeline automatically triggers on push → runs tests → builds → deploys to GitHub Pages
• End user’s browser fetches static assets from GitHub Pages → app shell (index.html + main.js)
• Service Worker intercepts requests → caches assets for offline PWA functionality
• App retrieves DB JSON (via import or user upload) → calculateDistance functions → JSON→GPX conversion → export
• Python GUI alternative (setup.py) invokes json2gpx.py for JSON→GPX outside the browser
Architectural patterns & design principles
• SPA with PWA enhancements (offline first via service worker, manifest.json)
• Clear separation: source (src/) vs. build output (build/)
• CI/CD as code (GitHub Actions)
• Modular JS (React components, utility modules) and CSS
• Polyglot tooling: Node.js ecosystem + optional Python tool
Essential elements to capture
• Clear labels on each component (e.g., “webpack bundler”, “Service Worker”)