# andythebreaker/minarun architecture

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

- Interactive diagram: https://gitdiagram.com/andythebreaker/minarun
- Repository: https://github.com/andythebreaker/minarun

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer Machine"
        node1["Node.js & npm/yarn"]:::blue
        python["Python CLI/GUI"]:::purple
    end

    subgraph "Build & Test Subsystem"
        webpack["webpack bundler"]:::blue
        babel["Babel"]:::blue
        jest["Jest Test Runner"]:::blue
        scripts["npm Script Wrappers"]:::blue
    end

    subgraph "CI/CD Server"
        ci["GitHub Actions"]:::orange
    end

    subgraph "Build Output"
        buildOut["Static Site Artifacts"]:::orange
    end

    subgraph "Hosting / CDN"
        ghpages["GitHub Pages"]:::cloud
    end

    subgraph "Runtime / Client"
        browser["Browser (PWA Runtime)"]:::green
        serviceWorker["Service Worker"]:::green
        manifest["PWA Manifest"]:::green
        indexHTML["HTML Shell"]:::green
        reactEntry["React App"]:::green
        indexedDB[(IndexedDB Storage)]:::green
        jsonConvert["In-Browser JSON→GPX"]:::green
        demoJS["Standalone JS Utility"]:::green
        utilityPatch["Home URL Patch Script"]:::green
    end

    node1 --> webpack
    node1 --> babel
    node1 --> jest
    node1 --> scripts

    scripts --> webpack
    scripts --> babel
    scripts --> jest

    babel --> webpack
    webpack --> buildOut
    buildOut --> ghpages

    ci --> jest
    ci --> webpack
    ci --> buildOut
    ci --> ghpages

    ghpages --> browser

    browser --> serviceWorker
    serviceWorker --> browser

    browser --> indexedDB
    browser --> reactEntry
    browser --> manifest
    browser --> indexHTML
    browser --> jsonConvert
    browser --> utilityPatch

    python --> jsonConvert

    %% Click Events
    click node1 "https://github.com/andythebreaker/minarun/blob/main/package.json"
    click node1 "https://github.com/andythebreaker/minarun/blob/main/package-lock.json"
    click python "https://github.com/andythebreaker/minarun/blob/main/setup.py"
    click python "https://github.com/andythebreaker/minarun/blob/main/json2gpx.py"
    click webpack "https://github.com/andythebreaker/minarun/blob/main/config/webpack.config.js"
    click webpack "https://github.com/andythebreaker/minarun/blob/main/config/webpackDevServer.config.js"
    click webpack "https://github.com/andythebreaker/minarun/tree/main/config/webpack/"
    click webpack "https://github.com/andythebreaker/minarun/blob/main/webpack.config.js"
    click babel "https://github.com/andythebreaker/minarun/blob/main/babel.config.js"
    click babel "https://github.com/andythebreaker/minarun/blob/main/babel-plugin-macros.config.js"
    click jest "https://github.com/andythebreaker/minarun/tree/main/config/jest/"
    click jest "https://github.com/andythebreaker/minarun/blob/main/src/setupTests.js"
    click jest "https://github.com/andythebreaker/minarun/tree/main/src/unit/"
    click scripts "https://github.com/andythebreaker/minarun/blob/main/scripts/build.js"
    click scripts "https://github.com/andythebreaker/minarun/blob/main/scripts/start.js"
    click scripts "https://github.com/andythebreaker/minarun/blob/main/scripts/test.js"
    click ci "https://github.com/andythebreaker/minarun/blob/main/.github/workflows/main.yml"
    click reactEntry "https://github.com/andythebreaker/minarun/blob/main/src/index.js"
    click reactEntry "https://github.com/andythebreaker/minarun/blob/main/src/App.js"
    click reactEntry "https://github.com/andythebreaker/minarun/blob/main/src/index.css"
    click reactEntry "https://github.com/andythebreaker/minarun/blob/main/src/App.css"
    click indexHTML "https://github.com/andythebreaker/minarun/blob/main/public/index.html"
    click manifest "https://github.com/andythebreaker/minarun/blob/main/public/manifest.json"
    click manifest "https://github.com/andythebreaker/minarun/blob/main/src/manifest.json"
    click manifest "https://github.com/andythebreaker/minarun/blob/main/pwa/manifest.json"
    click serviceWorker "https://github.com/andythebreaker/minarun/blob/main/src/src-sw.js"
    click serviceWorker "https://github.com/andythebreaker/minarun/blob/main/src/serviceWorkerRegistration.js"
    click indexedDB "https://github.com/andythebreaker/minarun/blob/main/garbage/indexeddb.html"
    click jsonConvert "https://github.com/andythebreaker/minarun/blob/main/src/unit/json2gpx.js"
    click demoJS "https://github.com/andythebreaker/minarun/blob/main/gpx2.js"
    click utilityPatch "https://github.com/andythebreaker/minarun/blob/main/home_url_change.js"
    click utilityPatch "https://github.com/andythebreaker/minarun/blob/main/src/home_url_change.js"
    click buildOut "https://github.com/andythebreaker/minarun/blob/main/build/index.html"
    click buildOut "https://github.com/andythebreaker/minarun/blob/main/build/main.js"
    click buildOut "https://github.com/andythebreaker/minarun/blob/main/build/manifest.json"
    click buildOut "https://github.com/andythebreaker/minarun/blob/main/build/*.eot"
    click buildOut "https://github.com/andythebreaker/minarun/blob/main/build/*.LICENSE.txt"

    classDef blue fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef green fill:#C2FABC,stroke:#333,stroke-width:1px
    classDef orange fill:#FFD59E,stroke:#333,stroke-width:1px
    classDef purple fill:#E3C1FF,stroke:#333,stroke-width:1px
    classDef cloud fill:#FFEBCC,stroke:#333,stroke-width:1px
    classDef storage fill:#C2FABC,stroke:#333,stroke-width:1px,shape:cylinder
```
