How cywhale/gebco works
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