How cywhale/tide works
Project type and purpose
• This is a Python-based backend API service (no frontend) that serves tidal height and current predictions from the TPXO9-v5 model.
• It exposes HTTP endpoints (/api/tide and /api/tide/const) for external clients (e.g., Ocean APIverse demo, direct HTTP users).
File structure
• Top-level scripts:
• tide_app.py – application entrypoint (defines routes, starts server).
• setup.py, Pipfile, requirements.txt – packaging/dependency declarations.
• Configuration and deployment:
• conf/ecosystem.config.js – PM2 (Node) process manager config.
• conf/start_app.sh, conf/simu.sh – shell scripts to launch the API or run simulations.
• Core logic in src/:
• config.py – loads environment variables and settings.
• dask_client_manager.py – initializes or connects to a Dask cluster for parallel computation.
• model_extract.py, pytmd_utils.py – implement the tide-model data extraction and interfacing with the pyTMD library.
• model_utils.py, model_plot.py – utility functions and plotting.
• Development and testing support:
• dev/ and examples/ – Jupyter notebooks and scripts for data prep, extraction, plotting.
• test/ – unit tests, notebooks, JSON fixtures.
README for insights
• Confirms the two main endpoint groups: tidal height/current queries and harmonic constituents queries.
• Mentions pyTMD as a core external library for tide calculations.
• Shows that the service is containerizable/deployable behind an HTTP gateway.
Main components and their interactions
a. Client(s)
– Any HTTP consumer (browser, curl, Ocean APIverse).
b. API Gateway / Load Balancer (optional)
– Could be NGINX or cloud-managed LB in production.
c. Tide API Server
• tide_app.py / framework (e.g., Flask or FastAPI).
• Routes/Controllers for /api/tide and /api/tide/const.
d. Business Logic Layer
• Config loader (config.py)
• Extraction modules (model_extract.py, pytmd_utils.py)
• Utility modules (model_utils.py, model_plot.py)
e. Compute Layer (Dask Cluster)
• Manager (dask_client_manager.py)
• Worker nodes performing parallel extraction or fill-na operations on Zarr/NetCDF data
f. Data Layer
• Local or network-mounted TPXO9 model files (NetCDF, exposed via Zarr).
• Intermediate Zarr stores if used.
g. External Libraries/Services
• pyTMD for harmonic constituent computations.
• Possibly object storage (S3/GCS) if data is remote.
h. Deployment & Operations
• PM2 (via ecosystem.config.js) or systemd/Docker to run tide_app.py.
• Shell scripts (start_app.sh) for environment setup.
• Logging & monitoring (not in repo but recommended: Prometheus, Grafana).
Architectural patterns and design principles
• Clear separation of concerns: routing vs. business logic vs. compute vs. data access.
• Horizontal scalability of compute through Dask.
• Config-driven deployment (all settings in config.py, environment variables).
• Modular Python packaging (setup.py), enabling installation as a library.