# cywhale/tide architecture

> Architecture diagram of the GitHub repository cywhale/tide, 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/cywhale/tide
- Repository: https://github.com/cywhale/tide

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Clients and Gateway
    Client["HTTP Clients\n(browser, curl, APIverse)"]:::external
    LB["API Gateway / Load Balancer\n(NGINX or Cloud LB)"]:::external

    Client -->|HTTP Request| LB
    LB -->|forwards request| APIServer

    %% API Server Layer
    subgraph "API Server" 
        direction TB
        APIServer["API Server\n(tide_app.py)"]:::stateless
        Routes["Routes/Controllers\n/api/tide, /api/tide/const"]:::stateless
    end

    LB -->|HTTP Request| APIServer
    APIServer -->|calls| Routes

    %% Business Logic Layer
    subgraph "Business Logic" 
        direction TB
        Config["Config Loader\n(src/config.py)"]:::stateless
        ModelExtract["Tide Model Extraction\n(src/model_extract.py)"]:::stateless
        PyTMD["Harmonic Constituents Interface\n(src/pytmd_utils.py)"]:::stateless
        ModelUtils["General Model Utilities\n(src/model_utils.py)"]:::stateless
        ModelPlot["Model Plotting Utilities\n(src/model_plot.py)"]:::stateless
    end

    Routes -->|load settings| Config
    Routes -->|invoke extraction| ModelExtract
    ModelExtract -->|use pyTMD| PyTMD
    Routes -->|use utils| ModelUtils
    Routes -->|generate plots| ModelPlot

    %% Compute Layer
    subgraph "Compute Cluster (Dask)" 
        direction TB
        DaskManager["Dask Client Manager\n(src/dask_client_manager.py)"]:::compute
        Scheduler["Dask Scheduler"]:::compute
        Workers["Dask Workers"]:::compute
    end

    ModelExtract -->|RPC via Dask Client| DaskManager
    DaskManager --> Scheduler
    Scheduler --> Workers

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        TPXO["TPXO9 Model Files\n(NetCDF/Zarr)"]:::storage
        ObjectStorage["Object Storage\n(S3/GCS)"]:::storage
    end

    ModelExtract -->|read files| TPXO
    ModelExtract -->|read/write| ObjectStorage

    %% External Libraries
    subgraph "External Libraries"
        direction TB
        PyTMDLib["pyTMD Library"]:::external
    end
    PyTMD -->|imports| PyTMDLib

    %% Deployment & Operations
    subgraph Operations
        direction TB
        Ecosystem["PM2 Config\n(conf/ecosystem.config.js)"]:::operations
        StartScript["Start Script\n(conf/start_app.sh)"]:::operations
        SimuScript["Simulation Script\n(conf/simu.sh)"]:::operations
    end

    %% Packaging & Dev/Test Support
    subgraph Support & Packaging
        direction TB
        Setup["setup.py"]:::support
        Pipfile["Pipfile"]:::support
        Requirements["requirements.txt"]:::support
        Dev["Development Notebooks & Scripts\ndev/"]:::support
        Examples["Example Notebooks\nexamples/"]:::support
        Tests["Automated Tests & Fixtures\ntest/"]:::support
    end

    %% Click Events
    click APIServer "https://github.com/cywhale/tide/blob/main/tide_app.py"
    click Config "https://github.com/cywhale/tide/blob/main/src/config.py"
    click DaskManager "https://github.com/cywhale/tide/blob/main/src/dask_client_manager.py"
    click ModelExtract "https://github.com/cywhale/tide/blob/main/src/model_extract.py"
    click PyTMD "https://github.com/cywhale/tide/blob/main/src/pytmd_utils.py"
    click ModelUtils "https://github.com/cywhale/tide/blob/main/src/model_utils.py"
    click ModelPlot "https://github.com/cywhale/tide/blob/main/src/model_plot.py"
    click Setup "https://github.com/cywhale/tide/blob/main/setup.py"
    click Pipfile "https://github.com/cywhale/tide/tree/main/Pipfile"
    click Requirements "https://github.com/cywhale/tide/blob/main/requirements.txt"
    click Ecosystem "https://github.com/cywhale/tide/blob/main/conf/ecosystem.config.js"
    click StartScript "https://github.com/cywhale/tide/blob/main/conf/start_app.sh"
    click SimuScript "https://github.com/cywhale/tide/blob/main/conf/simu.sh"
    click Dev "https://github.com/cywhale/tide/tree/main/dev/"
    click Examples "https://github.com/cywhale/tide/tree/main/examples/"
    click Tests "https://github.com/cywhale/tide/tree/main/test/"

    %% Styles
    classDef stateless fill:#a8e6cf,stroke:#379683,stroke-width:2px
    classDef compute fill:#d0e1f9,stroke:#1e3a8a,stroke-width:2px
    classDef storage fill:#ffd3b6,stroke:#ff8c00,stroke-width:2px
    classDef external fill:#f6ccd9,stroke:#c72c41,stroke-width:2px
    classDef operations fill:#e0e0e0,stroke:#616161,stroke-width:2px
    classDef support fill:#ffffff,stroke:#888888,stroke-width:1px,stroke-dasharray: 5 5
```
