# cywhale/gebco architecture

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

## Overview

##### Project Type and Purpose
- This is a microservice-style backend application built with Python’s FastAPI framework.
- Purpose: Expose HTTP endpoints for GEBCO bathymetry data (z-profiles, polygon sampling, point sampling) at 15-arcsec resolution, backed by GEBCO grid files.

##### High-Level File Structure Analysis
- Top-level:
- gebco_app.py – FastAPI application entrypoint
- Pipfile, requirements.txt, setup.py – dependency & packaging
- conf/ – deployment & configuration (ecosystem.config.js for PM2, JSON for GEBCO grid metadata, shell scripts)
- data_src/ – raw GEBCO documentation PDFs
- simu/ – sample CSV & HTML outputs (three.js demos, mesh previews)
- dev/ – exploratory Jupyter notebooks & scripts
- src/ – core Python modules (config.py, polyhandler.py, xmeridian.py, zprofile.py)

##### README Insights
- Exposes three main modes: “row” (z-profile + distances), “point” (endpoints), “zonly” (depth only) for both line and polygon (GeoJSON) inputs.
- Provides Swagger UI for interactive testing.
- Cites GEBCO 2023 grid as static data source.

##### Identifying Main Components
a. Clients
– Web browsers, CLI tools, other services calling REST API
b. API Layer (FastAPI)
– gebco_app.py initializes FastAPI
– Uvicorn/Gunicorn/PM2 hosts the app
– Swagger/OpenAPI auto-doc endpoint
c. Business Logic Modules
– config.py: loads JSON grid metadata, sampling parameters
– xmeridian.py: computes geodesic distances along rows
– zprofile.py: retrieves bathymetric depths at grid points
– polyhandler.py: processes GeoJSON polygons & sampling
d. Data Layer
– GEBCO JSON grid files (`conf/gebco_v1.json`)
– (Optional) flat-file outputs written to simu/ for demos
e. External Integrations
– Swagger UI (built into FastAPI)
– Downstream visualization apps (e.g., Plotly on APIverse)

##### Component Interactions and Data Flow
- Client → HTTP Request → FastAPI Endpoints
- FastAPI parses path/query parameters (lon, lat, mode, jsonsrc) via Pydantic
- Request dispatched to appropriate module:
- Line modes → xmeridian + zprofile
- Polygon modes → polyhandler (which may call zprofile)
- Modules read static grid JSON (conf/gebco_v1.json)
- Modules return Python data structures → FastAPI serializes to JSON
- JSON Response → Client
- (For demos) data written to simu/ and rendered in three.js HTML

##### Architectural Patterns and Design Principles
- Separation of Concerns: API layer vs. domain logic vs. data source
- Modular design: small, testable Python modules
- Configurable via external JSON and ecosystem config
- Stateless HTTP service (no in-memory session or DB)

##### Technologies, Frameworks, Libraries
- Python 3.x, FastAPI, Uvicorn (or PM2+Node wrapper), Pydantic
- Standard library (json, pathlib) + numpy/geopandas (if used in modules)
- Three.js & HTML for client-side 3D demos (in simu/)

##### Key Takeaway
Capture:
- The stateless HTTP interface (FastAPI)
- Clear separation between request handling, domain logic, and static data
- Core modules and their call relationships
- Configuration and deployment artifacts

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "External Clients"
        Browser["Web Browser"]:::external
        CLI["CLI & Other Services"]:::external
    end

    Browser -->|HTTP/JSON| FastAPI["FastAPI App"]:::api
    CLI -->|HTTP/JSON| FastAPI

    subgraph "API Layer"
        FastAPI
        Swagger["Swagger UI"]:::api
    end

    FastAPI -->|"OpenAPI Docs"| Swagger

    subgraph "Business Logic Modules"
        Config["Sampling Config\n(config.py)"]:::module
        Xmeridian["Geodesic Distance\n(xmeridian.py)"]:::module
        Zprofile["Depth Retrieval\n(zprofile.py)"]:::module
        Polyhandler["Polygon Sampling\n(polyhandler.py)"]:::module
    end

    FastAPI -->|dispatch| Config
    FastAPI -->|row/point/zonly| Xmeridian
    FastAPI -->|row/point/zonly| Zprofile
    FastAPI -->|polygon| Polyhandler
    Polyhandler -->|calls| Zprofile

    subgraph "Data Layer"
        GridJSON["Grid Metadata\n(gebco_v1.json)"]:::data
    end

    Config -->|reads| GridJSON
    Xmeridian -->|reads| GridJSON
    Zprofile -->|reads| GridJSON
    Polyhandler -->|reads| GridJSON

    subgraph "Deployment & Config"
        Ecosystem["Process Config\n(ecosystem.config.js)"]:::data
    end

    Ecosystem --> FastAPI

    subgraph "Demos & Extras"
        Simu["Demo Outputs\n(simu/)"]:::external
        DataSrc["Raw Docs\n(data_src/)"]:::external
        Dev["Notebooks & Scripts\n(dev/)"]:::external
    end

    FastAPI -->|writes CSV/HTML| Simu

    click FastAPI "https://github.com/cywhale/gebco/blob/main/gebco_app.py"
    click Config "https://github.com/cywhale/gebco/blob/main/src/config.py"
    click Xmeridian "https://github.com/cywhale/gebco/blob/main/src/xmeridian.py"
    click Zprofile "https://github.com/cywhale/gebco/blob/main/src/zprofile.py"
    click Polyhandler "https://github.com/cywhale/gebco/blob/main/src/polyhandler.py"
    click GridJSON "https://github.com/cywhale/gebco/blob/main/conf/gebco_v1.json"
    click Ecosystem "https://github.com/cywhale/gebco/blob/main/conf/ecosystem.config.js"
    click Simu "https://github.com/cywhale/gebco/tree/main/simu/"
    click DataSrc "https://github.com/cywhale/gebco/tree/main/data_src/"
    click Dev "https://github.com/cywhale/gebco/tree/main/dev/"

    classDef api fill:#8FBC8F,stroke:#333,stroke-width:1px;
    classDef module fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef data fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
