# usepa/mywaterway architecture

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

- Interactive diagram: https://gitdiagram.com/usepa/mywaterway
- Repository: https://github.com/usepa/mywaterway

## Overview

##### Main Components
- Frontend Client: Located under app/client, this is a React/TypeScript application with a rich set of UI components (pages, shared components, maps, widgets, etc.). It includes assets, styles, configuration files, and environment variable definitions.
- Backend Server: Found under app/server, this is the Node.js/Express server code (with routes, middleware, utilities, server configuration, and tasks). It handles API endpoints for data requests, static asset serving (e.g., the EPA template files), and proxying requests.
- Data Sources & External Services: The application connects to multiple data sources via EPA web services and other external APIs to collate information on water quality.
- Testing & CI/CD: There are extensive testing directories with Cypress end-to-end test scripts and Jest unit tests on the server. Additionally, GitHub workflow configurations (.github/workflows) and other CI/CD files (e.g., gitlab-ci.yml) indicate an automated deployment and testing pipeline.
- Documentation and Widgets: The docs directory, along with standalone widgets (in the widgets directory), provide supporting material and ways to use the application’s components.

##### Relationships and Interactions
- The Frontend communicates with the Backend via RESTful API calls. The API endpoints, defined in the server’s routes (e.g., api.js, index.js, proxy.js), serve as the bridge between the UI and the underlying data.
- The Backend not only responds to API calls from the frontend but also “pulls” or proxies data from external sources and web services.
- The CI/CD pipelines, represented by GitHub Actions workflows and other manifest files, integrate the testing suites (Jest and Cypress) and deployment configurations across multiple environments (development, staging, production).
- Static assets including those for mapping, EPA templates, images, fonts, etc., are served by both the client and server components.

##### Architectural Patterns and Design Principles
- Separation of concerns is evident as the frontend and backend are clearly separated, enabling a full-stack architecture.
- The client-side is built using component-based design (React components, contexts for state management, dedicated shared component libraries).
- The server application appears to follow a modular design (with distinct folders for routes, utilities, configurations, and tasks).
- Usage of configuration files for proxy routing and environment-specific settings (e.g., manifest files and .env files) indicates environment-based configuration management.
- The testing architecture promotes continuous integration with unit and end-to-end tests, ensuring that both client and server logic are validated.

##### Relevant Technologies and Frameworks
- Frontend: React, TypeScript, Vite as a bundler, ESLint, Prettier.
- Backend: Node.js/Express, with supporting libraries for logging and S3 (for file storage or static asset management).
- Testing: Cypress (end-to-end testing), Jest (for backend tests).
- CI/CD: GitHub Actions (workflows in .github/workflows) and possibly GitLab CI (given the presence of gitlab-ci.yml).
- Other: Various utility libraries for mapping (e.g., Esri configuration and map functionalities) and proxy services.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Layer
    subgraph "Client Layer"
        FC["Frontend Client (React/TypeScript)"]:::client
        CET["Client EPA Templates"]:::support
    end

    %% Server Layer
    subgraph "Server Layer"
        BS["Backend Server (Node.js/Express)"]:::backend
        SET["Server EPA Templates"]:::support
    end

    %% External Data Sources
    subgraph "External Data Sources"
        EPA["EPA Web Services & External APIs"]:::external
    end

    %% CI/CD and Testing
    subgraph "CI/CD & Testing"
        GA["GitHub Actions"]:::cicd
        GLC["GitLab CI"]:::cicd
        CT["Cypress Tests"]:::testing
        JT["Jest Tests"]:::testing
    end

    %% Support
    subgraph "Support"
        DOC["Documentation"]:::support
        WID["Widgets"]:::support
    end

    %% Connections between layers
    FC -->|"REST_API"| BS
    BS -->|"fetches_data"| EPA
    FC -->|"loads_assets"| CET
    BS -->|"serves_assets"| SET
    FC -->|"build_deploy"| GA
    BS -->|"build_deploy"| GA
    FC -->|"build_deploy"| GLC
    BS -->|"build_deploy"| GLC
    GA -->|"triggers"| CT
    GA -->|"triggers"| JT
    GLC -->|"triggers"| CT
    GLC -->|"triggers"| JT
    FC -->|"uses"| WID

    %% Click Events
    click FC "https://github.com/usepa/mywaterway/tree/develop/app/client"
    click BS "https://github.com/usepa/mywaterway/tree/develop/app/server"
    click CET "https://github.com/usepa/mywaterway/tree/develop/app/client/public/epa-template-files"
    click SET "https://github.com/usepa/mywaterway/tree/develop/app/server/app/public/epa-template-files"
    click CT "https://github.com/usepa/mywaterway/tree/develop/app/cypress"
    click JT "https://github.com/usepa/mywaterway/tree/develop/app/server/tests"
    click GA "https://github.com/usepa/mywaterway/tree/develop/.github/workflows"
    click GLC "https://github.com/usepa/mywaterway/blob/develop/gitlab-ci.yml"
    click DOC "https://github.com/usepa/mywaterway/tree/develop/docs"
    click WID "https://github.com/usepa/mywaterway/tree/develop/widgets"

    %% Styles
    classDef client fill:#bbf,stroke:#333,stroke-width:2px;
    classDef backend fill:#f9c,stroke:#333,stroke-width:2px;
    classDef external fill:#cfc,stroke:#333,stroke-width:2px;
    classDef cicd fill:#fc9,stroke:#333,stroke-width:2px;
    classDef testing fill:#cff,stroke:#333,stroke-width:2px;
    classDef support fill:#ddd,stroke:#333,stroke-width:2px;
```
