# potatosserver/youbike architecture

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

- Interactive diagram: https://gitdiagram.com/potatosserver/youbike
- Repository: https://github.com/potatosserver/youbike

## Overview

##### Project type and purpose
- This is primarily a client-side Progressive Web App (PWA) for searching YouBike station data, with an optional Android “wrapper” app that embeds the PWA in a WebView (using GoNative and custom plugins).
- The PWA fetches real-time data from the YouBike public API, displays station info, supports offline caching, geolocation, PWA installation, dark mode, and integrates with Google Maps for station navigation.

##### File structure
Top-level:
- Android/ → native Android project that packages the same PWA in a WebView.
– /app/src/main/assets → offline.html and all web assets for embedded offline mode.
– /app/src/main/java/co/median/android → GoNative core classes (WebView setup, JS bridge, file download, config updater, theme manager, etc.).
– /plugins/lottieAnimation → a plugin module for Lottie animations, illustrating the project’s plugin-based architecture.

##### README for additional insights
- Confirms it is a “simple, beautiful, low-traffic YouBike station searcher” with PWA features (offline, installable), geolocation, and Android APK releases.
- No custom backend: the app relies on YouBike’s public API and Google Maps links.

##### Main components and their interactions
A. Client Platform (User’s device/browser or Android app)
- Browser: loads index.html → main.js
- Android Native: launches WebView (GoNativeApplication) → loads offline.html or network index.html via GoNativeWindowManager
B. Frontend SPA
- service-worker.js → intercepts requests to cache static assets & API responses for offline mode
C. External Services
- YouBike Public API → station list & real-time availability
- Google Maps → deep link for station location
D. Native Plugins & Modules (Android only)
- GoNativeJSBridgeLibrary → bridge between JS and native code for downloads, file sharing, custom headers, etc.
- LottieAnimation plugin → supplies animated progress & splash screens
E. Device APIs
- Geolocation → calculate nearest stations and distances
- Notifications/Install prompts → for PWA or Android app updates

##### Architectural patterns & design principles
- SPA + Service Worker for offline first and responsive UX
- Plugin-based extensibility in native layer (e.g., Lottie plugin)
- Clear separation:
- Web layer (presentational + business logic in JS)
- Caching layer (Service Worker)
- Native wrapper (Android WebView + platform APIs)
- External API integrations

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Device Boundary
    subgraph "User Device"
        direction TB

        subgraph "Web Browser (PWA)"
            direction TB
            Index["index.html"]:::web
            MainJS["main.js"]:::web
            Manifest["manifest.json"]:::web
            SW["service-worker.js"]:::web
            Cache["Cache Storage"]:::cache
            Icons["icons/"]:::web
            Images["img/"]:::web
        end

        subgraph "Android App (WebView + Native Modules)"
            direction TB
            Launcher["MainActivity.java"]:::native

            subgraph "GoNative WebView Layer"
                direction TB
                WebView["GoNative WebView"]:::native
                OfflineHTML["offline.html"]:::web
                Assets["assets (PWA files)"]:::web
            end

            subgraph "JS Bridges"
                direction TB
                GNB["GoNativeJSBridgeLibrary.js"]:::native
                BlobDL["BlobDownloader.js"]:::native
            end

            subgraph "Native Modules"
                direction TB
                FileDL["FileDownloader.java"]:::native
                DownloadSvc["DownloadService.java"]:::native
                ConfigUpd["ConfigUpdater.java"]:::native
                CustomHdr["CustomHeaders.java"]:::native
                ThemeUtils["ThemeUtils.java"]:::native
                URLNav["UrlNavigation.java"]:::native
                GeoHelper["LocationServiceHelper.kt"]:::native
            end

            subgraph "Lottie Animation Plugin"
                direction TB
                LottieJS["lottie-plugin.js"]:::native
                LottieNative["LottiePlugin.kt"]:::native
                LottieRes["resources"]:::native
            end
        end
    end

    %% External Services
    YouBikeAPI(("YouBike Public API")):::external
    GoogleMaps(("Google Maps")):::external

    %% Data Flows - PWA
    Index -->|loads| MainJS
    MainJS -->|registers| SW
    SW -->|caches static| Cache
    SW -->|fetch network| YouBikeAPI
    MainJS -->|GET /stations| YouBikeAPI
    MainJS -->|navigator.geolocation| GeoHelper
    Index -->|Open in Google Maps| GoogleMaps
    Manifest -->|PWA Install| Index

    %% Data Flows - Android
    Launcher -->|starts| WebView
    WebView -->|load offline shell| OfflineHTML
    WebView -->|load network| Index
    WebView <-->|JS Bridge| GNB
    GNB -->|uses| BlobDL
    GNB -->|invokes| FileDL
    GNB -->|invokes| DownloadSvc
    GNB -->|invokes| ConfigUpd
    GNB -->|invokes| CustomHdr
    GNB -->|invokes| ThemeUtils
    GNB -->|invokes| URLNav
    GNB -->|invokes| GeoHelper

    %% Click Events
    click Index "https://github.com/potatosserver/youbike/blob/main/index.html"
    click MainJS "https://github.com/potatosserver/youbike/blob/main/main.js"
    click Manifest "https://github.com/potatosserver/youbike/blob/main/manifest.json"
    click SW "https://github.com/potatosserver/youbike/blob/main/service-worker.js"
    click Icons "https://github.com/potatosserver/youbike/tree/main/icons/"
    click Images "https://github.com/potatosserver/youbike/tree/main/img/"
    click Launcher "https://github.com/potatosserver/youbike/blob/main/android/app/src/main/java/co/median/android/MainActivity.java"
    click OfflineHTML "https://github.com/potatosserver/youbike/blob/main/android/app/src/main/assets/offline.html"
    click Assets "https://github.com/potatosserver/youbike/tree/main/android/app/src/main/assets/"
    click GNB "https://github.com/potatosserver/youbike/blob/main/android/app/src/main/assets/GoNativeJSBridgeLibrary.js"
    click BlobDL "https://github.com/potatosserver/youbike/blob/main/android/app/src/main/assets/BlobDownloader.js"
    click FileDL "https://github.com/potatosserver/youbike/blob/main/android/app/src/main/java/co/median/android/FileDownloader.java"
    click DownloadSvc "https://github.com/potatosserver/youbike/blob/main/android/app/src/main/java/co/median/android/DownloadService.java"
    click ConfigUpd "https://github.com/potatosserver/youbike/blob/main/android/app/src/main/java/co/median/android/ConfigUpdater.java"
    click CustomHdr "https://github.com/potatosserver/youbike/blob/main/android/app/src/main/java/co/median/android/CustomHeaders.java"
    click ThemeUtils "https://github.com/potatosserver/youbike/blob/main/android/app/src/main/java/co/median/android/ThemeUtils.java"
    click URLNav "https://github.com/potatosserver/youbike/blob/main/android/app/src/main/java/co/median/android/UrlNavigation.java"
    click GeoHelper "https://github.com/potatosserver/youbike/blob/main/android/app/src/main/java/co/median/android/LocationServiceHelper.kt"
    click LottieJS "https://github.com/potatosserver/youbike/blob/main/android/plugins/lottieAnimation/src/main/assets/lottie-plugin.js"
    click LottieNative "https://github.com/potatosserver/youbike/blob/main/android/plugins/lottieAnimation/src/main/java/co/median/android/plugins/lottie/LottiePlugin.kt"
    click LottieRes "https://github.com/potatosserver/youbike/tree/main/android/plugins/lottieAnimation/src/main/res/"

    %% Styles
    classDef web fill:#D0E6FF,stroke:#333,stroke-width:1px
    classDef native fill:#DFFFD0,stroke:#333,stroke-width:1px
    classDef external fill:#ECECEC,stroke:#333,stroke-width:1px
    classDef cache fill:#F0F0F0,stroke:#333,stroke-width:1px
```
