# worldfishcenter/coasts architecture

> Architecture diagram of the GitHub repository worldfishcenter/coasts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/worldfishcenter/coasts
- Repository: https://github.com/worldfishcenter/coasts

## Overview

##### Project Type and Purpose
- This is a static, single-page geospatial visualization app built with React (via Vite) that fetches time-series/grid data from MongoDB (via a GitHub Actions workflow) and renders it on a Mapbox GL map. It uses “isomorphic-i18n” to provide internationalization support both at build and runtime.

##### High-Level Architecture Components
A. Data Pipeline
- GitHub Actions workflow (`.github/workflows/fetch-mongodb-data.yml`) connects to MongoDB using `MONGODB_URI`, runs `scripts/data/fetchMongoData.js`, and writes JSON into `public/data/`.
- Static JSON files (`pds_grids.json`, `wio_map.json`, `time_series.json`) are served with the built app.

B. Data Service Layer
- `src/services/dataService.js`: abstracts fetch calls to `/data/*.json`.
- `src/utils/pdsDataProcessor.js` & `src/utils/metricCalculations.js`: transform raw JSON into formats suitable for charting and analysis.

C. State & Logic (Hooks)
- `useMapData`: loads and caches raw + processed data.
- `useMapLayers`: configures Mapbox layers using `src/utils/gridLayerConfig.js`.
- `useMapTooltip`: manages hover/click tooltip state.

D. Presentation / UI Components
1. Root
- `src/main.jsx` & `src/App.jsx`: bootstraps React, wraps the app in the isomorphic-i18n provider, global CSS, and renders `<App />`.
2. Layout
- `Header.jsx`: top navigation and title (i18n-aware text).
- `Sidebar.jsx`: container for control panels.
3. Area
- `Map.jsx`: Mapbox canvas, integrates layers & tooltips.
- `<DistributionHistogram/>`: histogram overlay for selected grid cells
- `<GridInfoPanel/>`: detailed info on hovered cell
- `<MapStyleToggle/>`: switch between Mapbox styles
4. Control Panels (in Sidebar)
- `SelectionPanel.jsx`: UI controls (filters, date pickers) to adjust data scope
- `AnalysisPanel.jsx`: displays derived metrics, charts
5. Shared UI
- `ui/button.jsx`: reusable button component for forms/controls

E. Configuration & Build
- `vite.config.js`, `postcss.config.js`, `tailwind.config.js`: build-time configs.
- `vercel.json`: deployment settings.
- `jsconfig.json`, `eslint.config.js`: dev tooling.

##### External Services & Integrations
- MongoDB (via GitHub Actions scheduled fetch)
- Mapbox (requires `VITE_MAPBOX_TOKEN`)
- isomorphic-i18n (handles translation files and runtime locale resolution)

##### Component Function & Structure
- UI component with its core responsibility (e.g., “SelectionPanel – manages filter state and invokes hook to update map”).
- How isomorphic-i18n wraps the entire React tree and injects translated strings into Header, Sidebar, panels, and buttons.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    gha["GitHub Actions"]:::external
    mapbox["Mapbox API"]:::external

    %% Data Pipeline
    subgraph "Data Pipeline"
        workflow["fetch-mongodb-data.yml"]:::service
        script["fetchMongoData.js"]:::service
        pds["pds_grids.json"]:::static
        timeSeries["time_series.json"]:::static
        wio["wio_map.json"]:::static
    end

    gha -->|"triggers"| workflow
    workflow -->|"runs"| script
    script -->|"writesJSON"| pds
    script -->|"writesJSON"| timeSeries
    script -->|"writesJSON"| wio

    %% Browser Container
    subgraph "Browser (React SPA)"
        direction TB
        main["main.jsx\n(Bootstrap+i18n)"]:::service
        app["App.jsx"]:::service

        subgraph "i18n Provider"
            style i18n fill:#e0f7fa,stroke:#006064
        end

        subgraph "Data Services & Utils"
            direction TB
            dataService["dataService.js"]:::service
            pdsProc["pdsDataProcessor.js"]:::service
            metrics["metricCalculations.js"]:::service
            gridConfig["gridLayerConfig.js"]:::service
        end

        subgraph "Hooks (Logic Layer)"
            direction TB
            useMapData["useMapData"]:::logic
            useMapLayers["useMapLayers"]:::logic
            useMapTooltip["useMapTooltip"]:::logic
        end

        subgraph "UI Components"
            direction TB
            header["Header.jsx"]:::ui
            sidebar["Sidebar.jsx"]:::ui
            selection["SelectionPanel.jsx"]:::ui
            analysis["AnalysisPanel.jsx"]:::ui
            Map["Map.jsx"]:::ui
            distHist["DistributionHistogram.jsx"]:::ui
            gridInfo["GridInfoPanel.jsx"]:::ui
            styleToggle["MapStyleToggle.jsx"]:::ui
            legend["UnifiedLegend.jsx"]:::ui
            button["button.jsx"]:::ui
        end
    end

    %% Build Connections
    pds -->|"servedAsStatic"| dataService
    timeSeries -->|"servedAsStatic"| dataService
    wio -->|"servedAsStatic"| dataService

    main -->|"bootstraps"| app
    app -->|"wrapsWith"| i18n
    app -->|"renders"| header
    app -->|"renders"| sidebar
    app -->|"renders"| Map

    sidebar -->|"contains"| selection
    sidebar -->|"contains"| analysis

    Map -->|"usesHook"| useMapData
    Map -->|"usesHook"| useMapLayers
    Map -->|"usesHook"| useMapTooltip
    Map -->|"includes"| distHist
    Map -->|"includes"| gridInfo
    Map -->|"includes"| styleToggle
    Map -->|"includes"| legend
    Map -->|"rendersButton"| button

    useMapData -->|"calls"| dataService
    useMapData -->|"processesWith"| pdsProc
    useMapData -->|"processesWith"| metrics

    useMapLayers -->|"configuresWith"| gridConfig

    styleToggle -->|"callsAPI"| mapbox
    Map -->|"loadsTilesFrom"| mapbox

    %% Click Events
    click workflow "https://github.com/worldfishcenter/coasts/blob/main/.github/workflows/fetch-mongodb-data.yml"
    click script "https://github.com/worldfishcenter/coasts/blob/main/scripts/data/fetchMongoData.js"
    click pds "https://github.com/worldfishcenter/coasts/blob/main/public/data/pds_grids.json"
    click timeSeries "https://github.com/worldfishcenter/coasts/blob/main/public/data/time_series.json"
    click wio "https://github.com/worldfishcenter/coasts/blob/main/public/data/wio_map.json"
    click dataService "https://github.com/worldfishcenter/coasts/blob/main/src/services/dataService.js"
    click pdsProc "https://github.com/worldfishcenter/coasts/blob/main/src/utils/pdsDataProcessor.js"
    click metrics "https://github.com/worldfishcenter/coasts/blob/main/src/utils/metricCalculations.js"
    click gridConfig "https://github.com/worldfishcenter/coasts/blob/main/src/utils/gridLayerConfig.js"
    click useMapData "https://github.com/worldfishcenter/coasts/blob/main/src/hooks/useMapData.js"
    click useMapLayers "https://github.com/worldfishcenter/coasts/blob/main/src/hooks/useMapLayers.js"
    click useMapTooltip "https://github.com/worldfishcenter/coasts/blob/main/src/hooks/useMapTooltip.js"
    click main "https://github.com/worldfishcenter/coasts/blob/main/src/main.jsx"
    click app "https://github.com/worldfishcenter/coasts/blob/main/src/App.jsx"
    click header "https://github.com/worldfishcenter/coasts/blob/main/src/components/Header.jsx"
    click sidebar "https://github.com/worldfishcenter/coasts/blob/main/src/components/Sidebar.jsx"
    click Map "https://github.com/worldfishcenter/coasts/blob/main/src/components/Map.jsx"
    click distHist "https://github.com/worldfishcenter/coasts/blob/main/src/components/map/DistributionHistogram.jsx"
    click gridInfo "https://github.com/worldfishcenter/coasts/blob/main/src/components/map/GridInfoPanel.jsx"
    click styleToggle "https://github.com/worldfishcenter/coasts/blob/main/src/components/map/MapStyleToggle.jsx"
    click legend "https://github.com/worldfishcenter/coasts/blob/main/src/components/map/UnifiedLegend.jsx"
    click selection "https://github.com/worldfishcenter/coasts/blob/main/src/components/panels/SelectionPanel.jsx"
    click analysis "https://github.com/worldfishcenter/coasts/blob/main/src/components/panels/AnalysisPanel.jsx"
    click button "https://github.com/worldfishcenter/coasts/blob/main/src/components/ui/button.jsx"

    %% Styles
    classDef external fill:#ffe0b2,stroke:#e65100
    classDef static fill:#eceff1,stroke:#90a4ae
    classDef service fill:#bbdefb,stroke:#0d47a1
    classDef logic fill:#c8e6c9,stroke:#1b5e20
    classDef ui fill:#fff9c4,stroke:#f57f17
    classDef i18n fill:#e0f7fa,stroke:#006064 titled
```
