# wfp-vam/prism-app architecture

> Architecture diagram of the GitHub repository wfp-vam/prism-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wfp-vam/prism-app
- Repository: https://github.com/wfp-vam/prism-app

## Overview

##### Project type and purpose
- This is a full-stack, multi-service mapping and data-visualization platform (WFP PRISM).
- It consists of three core services:
- Frontend (React + MapLibre, deployed as a static site)
- API service (Python/Flask or FastAPI for data ingestion, raster/vector processing)
- Alerting service (Node/TypeScript microservice with cron jobs, sends email alerts)
- A shared “common” library holds reusable code (e.g., OWS parsers).

##### File structure
- Top-level directories:
- frontend: CRA-based React app, Redux Toolkit, MapLibre, hosted on Firebase/CDN.
- api: Python app (uwsgi, pytest, STAC & WMS clients, Postgres via TypeORM equivalent).
- alerting: Node/TypeScript service with TypeORM migrations, email templates, cron scripts.
- common: TypeScript utilities for OWS (WMS/WFS/WCS), shared across services.
- Config, Dockerfiles, compose files, CI workflows (.github/workflows) span services.
- Deployment scripts: docker-compose, Firebase deploy, server_setup.sh, cron scripts.

##### README for additional insights
- Frontend README details configuration files (prism.json, layers.json, tables.json),
environment variables (REACT_APP_COUNTRY, map settings, OAuth, Sentry, Mapbox),
and build/deploy commands (yarn start/build, lint, CI/CD to Firebase channels).
- Highlights how the static site fetches geojson, WMS layers, CSV, point data via API calls.

##### Main components & interactions (to include
A. Frontend
- React app served from Firebase/CDN
- Uses Redux store slices for map state, layers, alerts
- Fetches:
- REST endpoints on API service (e.g., `/api/alerts`, `/api/geotiff`, `/api/raster-utils`)
- External WMS servers (Geonode GeoServer, Earthobservation VAM WPS)
- Point-data APIs (Kobo forms via Prism API)
- Common library functions (client-side HTTP utilities)

B. API service
- Python app with:
- Database layer (Postgres via SQLAlchemy or similar)
- Endpoints for STAC data, raster processing (zonal stats), caching, authentication
- Utilizes:
– geoTIFF/STAC clients
– Google Floods & Kobo clients
– Caching (Redis or in-memory)
- Exposes REST/JSON API consumed by frontend

C. Alerting service
- TypeScript Node service
- Scheduled cron jobs (`cron_alert_run.sh`, `cron_aa_storm_alert_run.sh`)
- TypeORM migrations and entities for alerts table
- Workers process storm & anticipatory action alerts
- Sends emails via templates (EJS)

D. Shared library
- NPM package under common/
- Provides OWS parsers (WMS/WFS/WCS), XML utils, bbox utilities
- Versioned and consumed by frontend & alerting

E. Database
- Postgres (hosted or containerized)
- Schemas for users, alerts, anticipatory_action_alerts
- Accessed by API & alerting service

F. External services
- GeoServer WMS endpoints
- Humanitarian Data Cube WCS/WFS
- STAC API endpoints
- Kobo/form API
- Sentry for monitoring
- Firebase Hosting & Channels for frontend

##### Architectural patterns & design principles
- Microservice pattern: three loosely-coupled services
- Shared library for DRY code (common)
- Cron-driven event processing in alerting
- Static site generation + SPA with external API calls
- Layered architecture in API (controllers → services → data access)
- Redux for client state separation (map, layers, alerts)

- Clear, concise labels (e.g., “MapLibre SPA”, “/alerts endpoint”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (React + MapLibre SPA)" 
        direction TB
        FE_DIR["frontend/"]:::internal
        FE_MapView["MapView Component"]:::internal
        FE_Config["Config Files (prism.json, layers.json)"]:::internal
        FE_Public["Public Static Data"]:::internal
        FE_DOCKER["frontend/Dockerfile"]:::internal
        FE_DIR --> FE_MapView
        FE_DIR --> FE_Config
        FE_DIR --> FE_Public
        FE_DIR --> FE_DOCKER
    end

    %% API Service Layer
    subgraph "API Service (Python/Flask)" 
        direction TB
        API_DIR["api/"]:::internal
        API_Main["app/main.py"]:::internal
        API_Auth["app/auth.py"]:::internal
        API_Raster["app/raster_utils.py"]:::internal
        API_Zonal["app/zonal_stats.py"]:::internal
        API_GeoTIFF["app/geotiff_from_stac_api.py"]:::internal
        API_GFlood["app/googleflood.py"]:::internal
        API_Kobo["app/kobo.py"]:::internal
        API_DBModels["app/database/"]:::internal
        API_Cache["app/caching.py"]:::internal
        API_DOCKER["api/Dockerfile"]:::internal
        API_DIR --> API_Main
        API_DIR --> API_Auth
        API_DIR --> API_Raster
        API_DIR --> API_Zonal
        API_DIR --> API_GeoTIFF
        API_DIR --> API_GFlood
        API_DIR --> API_Kobo
        API_DIR --> API_DBModels
        API_DIR --> API_Cache
        API_DIR --> API_DOCKER
    end

    %% Alerting Service Layer
    subgraph "Alerting Service (Node/TypeScript)" 
        direction TB
        AL_DIR["alerting/"]:::internal
        AL_Worker["src/alert-worker.ts"]:::internal
        AL_Cron1["cron_alert_run.sh"]:::internal
        AL_Cron2["cron_aa_storm_alert_run.sh"]:::internal
        AL_StormRunner["src/aa-storm-alert-runner.ts"]:::internal
        AL_Entities1["src/entities/alerts.entity.ts"]:::internal
        AL_Entities2["src/entities/anticipatoryActionAlerts.entity.ts"]:::internal
        AL_Templates["src/templates/storm-alert.ejs"]:::internal
        AL_ORM["ormconfig.ts"]:::internal
        AL_DOCKER["alerting/Dockerfile"]:::internal
        AL_DIR --> AL_Worker
        AL_DIR --> AL_Cron1
        AL_DIR --> AL_Cron2
        AL_DIR --> AL_StormRunner
        AL_DIR --> AL_Entities1
        AL_DIR --> AL_Entities2
        AL_DIR --> AL_Templates
        AL_DIR --> AL_ORM
        AL_DIR --> AL_DOCKER
    end

    %% Common Library
    subgraph "Common Library (OWS Parsers & Utilities)" 
        direction TB
        CM_DIR["common/"]:::library
        CM_OWS["src/ows/"]:::library
        CM_WMS["src/wms/"]:::library
        CM_WFS["src/wfs/"]:::library
        CM_WCS["src/wcs/"]:::library
        CM_UTILS["src/utils/"]:::library
        CM_BASE["src/base/"]:::library
        CM_TYPES["src/types/anticipatory-action-storm"]:::library
        CM_PKG["common/package.json"]:::library
        CM_DIR --> CM_OWS
        CM_DIR --> CM_WMS
        CM_DIR --> CM_WFS
        CM_DIR --> CM_WCS
        CM_DIR --> CM_UTILS
        CM_DIR --> CM_BASE
        CM_DIR --> CM_TYPES
        CM_DIR --> CM_PKG
    end

    %% Database
    DB["Postgres Database"]:::db

    %% External Services
    subgraph "External Services" 
        direction TB
        EXT_WMS["GeoServer WMS"]:::external
        EXT_DWC["Humanitarian Data Cube WCS/WFS"]:::external
        EXT_STAC["STAC API"]:::external
        EXT_KOBO["Kobo Forms API"]:::external
        EXT_EMAIL["SMTP / Email Service"]:::external
        EXT_SENTRY["Sentry"]:::external
        EXT_FIREBASE["Firebase Hosting & CDN"]:::external
    end

    %% Relationships
    FE_DIR -->|HTTP JSON /api| API_DIR
    FE_DIR -->|Fetch WMS| EXT_WMS
    FE_DIR -->|Fetch WCS/WFS| EXT_DWC
    FE_DIR -->|Fetch STAC| EXT_STAC
    FE_DIR -->|Fetch Kobo Data| EXT_KOBO
    FE_DIR -->|Hosted on| EXT_FIREBASE
    FE_DIR -->|Uses Common Library| CM_DIR

    API_DIR -->|ORM / SQL| DB
    API_DIR -->|HTTP to WMS| EXT_WMS
    API_DIR -->|HTTP to STAC| EXT_STAC
    API_DIR -->|HTTP to Kobo| EXT_KOBO
    API_DIR -->|Errors & Logs| EXT_SENTRY

    AL_DIR -->|ORM / SQL| DB
    AL_DIR -->|SMTP| EXT_EMAIL
    AL_DIR -->|Uses Common Library| CM_DIR

    %% Click Events
    click FE_DIR "https://github.com/wfp-vam/prism-app/tree/master/frontend/"
    click FE_MapView "https://github.com/wfp-vam/prism-app/tree/master/frontend/src/components/MapView"
    click FE_Config "https://github.com/wfp-vam/prism-app/tree/master/frontend/src/config/"
    click FE_Public "https://github.com/wfp-vam/prism-app/tree/master/frontend/public/"
    click FE_DOCKER "https://github.com/wfp-vam/prism-app/tree/master/frontend/Dockerfile"

    click API_DIR "https://github.com/wfp-vam/prism-app/tree/master/api/"
    click API_Main "https://github.com/wfp-vam/prism-app/blob/master/api/app/main.py"
    click API_Auth "https://github.com/wfp-vam/prism-app/blob/master/api/app/auth.py"
    click API_Raster "https://github.com/wfp-vam/prism-app/blob/master/api/app/raster_utils.py"
    click API_Zonal "https://github.com/wfp-vam/prism-app/blob/master/api/app/zonal_stats.py"
    click API_GeoTIFF "https://github.com/wfp-vam/prism-app/blob/master/api/app/geotiff_from_stac_api.py"
    click API_GFlood "https://github.com/wfp-vam/prism-app/blob/master/api/app/googleflood.py"
    click API_Kobo "https://github.com/wfp-vam/prism-app/blob/master/api/app/kobo.py"
    click API_DBModels "https://github.com/wfp-vam/prism-app/tree/master/api/app/database/"
    click API_Cache "https://github.com/wfp-vam/prism-app/blob/master/api/app/caching.py"
    click API_DOCKER "https://github.com/wfp-vam/prism-app/tree/master/api/Dockerfile"

    click AL_DIR "https://github.com/wfp-vam/prism-app/tree/master/alerting/"
    click AL_Worker "https://github.com/wfp-vam/prism-app/blob/master/alerting/src/alert-worker.ts"
    click AL_Cron1 "https://github.com/wfp-vam/prism-app/blob/master/alerting/cron_alert_run.sh"
    click AL_Cron2 "https://github.com/wfp-vam/prism-app/blob/master/alerting/cron_aa_storm_alert_run.sh"
    click AL_StormRunner "https://github.com/wfp-vam/prism-app/blob/master/alerting/src/aa-storm-alert-runner.ts"
    click AL_Entities1 "https://github.com/wfp-vam/prism-app/blob/master/alerting/src/entities/alerts.entity.ts"
    click AL_Entities2 "https://github.com/wfp-vam/prism-app/blob/master/alerting/src/entities/anticipatoryActionAlerts.entity.ts"
    click AL_Templates "https://github.com/wfp-vam/prism-app/blob/master/alerting/src/templates/storm-alert.ejs"
    click AL_ORM "https://github.com/wfp-vam/prism-app/blob/master/alerting/ormconfig.ts"
    click AL_DOCKER "https://github.com/wfp-vam/prism-app/tree/master/alerting/Dockerfile"

    click CM_DIR "https://github.com/wfp-vam/prism-app/tree/master/common/"
    click CM_OWS "https://github.com/wfp-vam/prism-app/tree/master/common/src/ows/"
    click CM_WMS "https://github.com/wfp-vam/prism-app/tree/master/common/src/wms/"
    click CM_WFS "https://github.com/wfp-vam/prism-app/tree/master/common/src/wfs/"
    click CM_WCS "https://github.com/wfp-vam/prism-app/tree/master/common/src/wcs/"
    click CM_UTILS "https://github.com/wfp-vam/prism-app/tree/master/common/src/utils/"
    click CM_BASE "https://github.com/wfp-vam/prism-app/tree/master/common/src/base/"
    click CM_TYPES "https://github.com/wfp-vam/prism-app/tree/master/common/src/types/anticipatory-action-storm"
    click CM_PKG "https://github.com/wfp-vam/prism-app/blob/master/common/package.json"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366d6,stroke-width:2px
    classDef db fill:#DFFFD6,stroke:#228B22,stroke-width:2px
    classDef external fill:#F2F2F2,stroke:#666666,stroke-width:1px,stroke-dasharray: 5 5
    classDef library fill:#FFF4D6,stroke:#D9A300,stroke-width:2px
```
