# colachiang/youbike-opendata-explorer architecture

> Architecture diagram of the GitHub repository colachiang/youbike-opendata-explorer, 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/colachiang/youbike-opendata-explorer
- Repository: https://github.com/colachiang/youbike-opendata-explorer

## Overview

##### Project Type and Purpose
- This is a full-stack mobile navigation app for YouBike users.
- Frontend: App Inventor mobile app (.aia)
- Backend: Python Flask server serving real-time station status and ARIMA-based forecasts
- Data: YouBike open API, weather open data, geoJSON for Taipei map

##### File Structure
Top-level files and directories:
- ubike_data_crawler.py – Ingests YouBike station data
- C-B0024-001.json, weather.ipynb, 天氣資料概述.docx – Weather data ingestion and exploration
- _ubike_static (1).ipynb – Exploratory data analysis for YouBike data
- forcast.py – Implements ARIMA forecasting model
- geojson_Taipei.json – GeoJSON used for mapping station locations
- test.py – Unit or integration tests
- requirements.txt – Python dependencies
- README.md – Project overview and usage
Configuration:
- .gitignore – Ignores IPython outputs, data files, envs
- ngrok used to expose local Flask endpoints

##### Key Architectural Components
a. Data Ingestion Layer
– YouBike Data Crawler (ubike_data_crawler.py)
– Weather Data Fetcher (via C-B0024-001.json or direct API)
– Data stored temporarily (CSV/JSON or lightweight DB)
b. Data Processing & Model
– Preprocessing notebooks (_ubike_static.ipynb, weather.ipynb)
– Forecast script (forcast.py) training or generating ARIMA predictions
c. Backend API
– Flask app exposing REST endpoints:
- /stations/status – real-time availability
- /stations/predict – ARIMA forecast for given station ID
– Runs locally, exposed via ngrok for external access
d. Frontend (App Inventor)
– Mobile app imported from Youbike_navigate.aia
– UI screens: Map view, station list, status detail, navigation
– Calls Flask endpoints over HTTP
e. External Services
– YouBike Open API (real-time data)
– Weather Open Data API
– Map tiles or Google Maps for navigation
– ngrok tunnel for HTTP forwarding

##### Relationships and Interactions
- App Inventor front end ← HTTP/HTTPS → Flask backend
- Flask backend ← internal calls to crawler & forecast modules → Data files or in-memory data
- Crawler ↔ YouBike API
- Weather fetcher ↔ Weather API
- Forecast module consumes historical data + weather features → returns predictions
- GeoJSON used by frontend or backend to render station locations on map

##### Architectural Patterns & Design Principles
- Layered architecture: Ingestion → Processing/Business Logic → API layer → Client
- Separation of concerns:
– Crawler modules isolated from Flask routes
– Forecast logic decoupled (forcast.py)
– Notebooks used for EDA, not part of runtime path
- Stateless REST API: each request returns fresh status or forecast
- Extensibility: You could swap ARIMA for another model without touching Flask app

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    subgraph "External Services"
        direction TB
        YB_API["YouBike Open API"]:::external
        W_API["Weather Open Data API"]:::external
        MAP_SVC["Map Service (Tiles/Google Maps)"]:::external
    end

    %% Data Ingestion Layer
    subgraph "Data Ingestion" 
        direction TB
        CRAWLER["YouBike Data Crawler"]:::ingestion
        WEATHER_FETCH["Weather Data Fetcher"]:::ingestion
        RAW_YB["Raw YouBike Data"]:::datastore
        RAW_WEATHER["Raw Weather Data"]:::datastore
    end

    %% Processing & Modeling
    subgraph "Processing & Modeling"
        direction TB
        UB_EDA["YouBike Data EDA Notebook"]:::eda
        W_EDA["Weather Data EDA Notebook"]:::eda
        FORECAST["Forecast Engine (ARIMA)"]:::processing
        PREP_DATA["Preprocessed Datasets / Model Artifacts"]:::datastore
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        FLASK["Flask Server"]:::api
        NGROK["ngrok Tunnel"]:::api
    end

    %% Client Layer
    subgraph "Client"
        direction TB
        APP["App Inventor Mobile App"]:::client
        GEOJSON["GeoJSON Station Locations"]:::datastore
    end

    %% Connections
    YB_API -->|"HTTP/JSON"| CRAWLER
    W_API -->|"HTTP/JSON"| WEATHER_FETCH
    CRAWLER -->|"CSV/JSON"| RAW_YB
    WEATHER_FETCH -->|"CSV/JSON"| RAW_WEATHER
    RAW_YB -->|Feeds| UB_EDA
    RAW_WEATHER -->|Feeds| W_EDA
    RAW_YB -->|History| FORECAST
    RAW_WEATHER -->|Features| FORECAST
    FORECAST -->|"Model Artifacts"| PREP_DATA
    PREP_DATA -->|Used by| FLASK
    FLASK -->|"REST API"| NGROK
    NGROK -->|"HTTPS"| APP
    FLASK -->|"GeoJSON"| APP
    GEOJSON -->|Loaded by| APP
    APP -->|"API Calls"| FLASK
    MAP_SVC -->|"Tiles"| APP

    %% Click Events
    click CRAWLER "https://github.com/colachiang/youbike-opendata-explorer/blob/main/ubike_data_crawler.py"
    click WEATHER_FETCH "https://github.com/colachiang/youbike-opendata-explorer/blob/main/C-B0024-001.json"
    click W_EDA "https://github.com/colachiang/youbike-opendata-explorer/blob/main/weather.ipynb"
    click UB_EDA "https://github.com/colachiang/youbike-opendata-explorer/blob/main/_ubike_static (1).ipynb"
    click FORECAST "https://github.com/colachiang/youbike-opendata-explorer/blob/main/forcast.py"
    click GEOJSON "https://github.com/colachiang/youbike-opendata-explorer/blob/main/geojson_Taipei.json"
    click FLASK "https://github.com/colachiang/youbike-opendata-explorer/blob/main/requirements.txt"
    click NGROK "https://github.com/colachiang/youbike-opendata-explorer/blob/main/README.md"
    click APP "https://github.com/colachiang/youbike-opendata-explorer/blob/main/test.py"
    click RAW_WEATHER "https://github.com/colachiang/youbike-opendata-explorer/blob/main/天氣資料概述.docx"
    click W_EDA "https://github.com/colachiang/youbike-opendata-explorer/blob/main/第五組-YouBike資料分析應用設計報告.pdf"

    %% Styles
    classDef external fill:#e0e0e0,stroke:#999,stroke-width:1px
    classDef ingestion fill:#aed6f1,stroke:#3498db,stroke-width:1px
    classDef datastore fill:#d5dbdb,stroke:#7f8c8d,stroke-width:1px,stroke-dasharray: 5 5
    classDef processing fill:#abebc6,stroke:#27ae60,stroke-width:1px
    classDef eda fill:#f9e79f,stroke:#f1c40f,stroke-width:1px
    classDef api fill:#f5cba7,stroke:#d35400,stroke-width:1px
    classDef client fill:#d2b4de,stroke:#8e44ad,stroke-width:1px
```
