# ciroh-ua/ngiab-cloudinfra architecture

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

- Interactive diagram: https://gitdiagram.com/ciroh-ua/ngiab-cloudinfra
- Repository: https://github.com/ciroh-ua/ngiab-cloudinfra

## Overview

##### Main Components
- Docker Container Environment: The “docker” directory holds the Dockerfile and startup scripts that bundle the model’s runtime environment.
- Configuration Files & Data: The “config” directory and the “docs” provide the necessary model configuration and documentation. Additionally, the “ngen-run” directory structure (as explained in the README) is central to the modeling run – containing subfolders like config, forcings, outputs, lakeout, metadata, and restart.
- Infrastructure Management: The “terraform” directory with subdirectories for “network” and “user” implies that certain network and user-related infrastructures are managed via Terraform.
- GitHub CI/CD and Automation: The “.github” directory (workflows, templates, dependabot configuration) shows use of GitHub Actions for building, testing, and actions such as pushing Docker images and sending notifications (e.g., to Slack).
- Auxiliary Scripts and Tools: Scripts like guide.sh, viewOnTethys.sh, and runTeehr.sh provide automation for starting up the process, running visualizations, and possibly integrating evaluation tools (TEEHR).

##### Relationships and Interactions
- User Interaction: The user downloads or clones the repository, sets up the NextGen run directory structure, and then triggers the guide script.
- Docker/Containerization: The Dockerfile builds the container image that encapsulates the NextGen runtime. The container then interacts with the run directory (ngen-run) – reading configuration files, processing input data, and managing outputs.
- Data Flow:
- Input data is downloaded (from external S3 sources as defined in the Quick Start Guide) and placed into the run directory.
- Within the container, configuration, forcing, and hydrofabric files (e.g., geopackage used for the NextGen run) are used to execute the model.
- Outputs are generated, which are later visualized either through the built-in visualization tools or via additional scripts.
- Infrastructure Automation: Terraform scripts configure networking and user settings needed for cloud deployments or for local simulation of network conditions.
- Continuous Integration/Deployment: GitHub workflows automate building and testing the Docker environment, keeping the container images updated.

##### Architectural Patterns and Principles
- Containerization: Encapsulation of the model runtime environment inside Docker ensures reproducibility and consistency.
- Infrastructure as Code: Use of Terraform streamlines the creation and management of the required infrastructure.
- Modular Run Directory: The separation of configuration, inputs (forcings), and outputs (with optional metadata) enforces the separation of concerns and aids in debugging and future scalability.
- Automation Pipelines: CI/CD via GitHub Actions automates testing and deployment, which is crucial for maintaining an open-source framework.

##### Relevant Technologies, Frameworks, and Libraries
- Docker (container image creation and runtime)
- Terraform (infrastructure provisioning)
- GitHub Actions (CI/CD pipelines for build & test, Docker builds, etc.)
- Bash/Shell Scripting (guide.sh, viewOnTethys.sh, etc.)
- Visualization tools integrated within the containerized environment
- JSON, YAML, and possibly other configuration formats for model configurations

##### Elements
- Clear labels for each component:
- “User/Local Machine” initiating the process.
- “Docker Engine/Container” representing the runtime environment built from docker/Dockerfile.
- “NGI Run Directory” with subfolders (config, forcings, outputs, etc.).
- “Terraform Modules” for network and user configuration.
- “Continuous Integration” elements (GitHub Actions pipelines).
- Data flow from user actions (e.g., downloading sample data) to the container’s execution process.
- Interaction between GitHub workflows and Docker builds.
- Dependencies from the NextGen configuration to the modeling outputs.
- Rectangles for components (e.g., Docker container, Terraform modules).

- Off to the side, illustrate Terraform-managed resources to show how network/user infra is set up.
- Optionally, add the visualization tool invocation (viewOnTethys.sh) as a separate process that fetches output data and displays results.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["User/Local Machine"]:::user
    B["GitHub Repository (Source Code)"]:::repo
    C["GitHub Actions (CI/CD)"]:::ci
    
    subgraph "Docker Build Process"
        D["Dockerfile"]:::build
        E["HelloNGEN.sh"]:::build
    end

    F["Docker Container Environment"]:::container
    G["NGI Run Directory<br/>(config, forcings, outputs, lakeout, metadata, restart)"]:::run

    subgraph "Configuration & Data"
        H1["Configuration Files"]:::config
        H2["Documentation"]:::config
    end

    subgraph "Terraform Modules"
        I1["Network"]:::infra
        I2["User"]:::infra
    end

    subgraph "Auxiliary Scripts and Tools"
        J["guide.sh"]:::scripts
        K["viewOnTethys.sh"]:::scripts
        L["runTeehr.sh"]:::scripts
    end

    %% Connections
    A -->|"clones"| B
    A -->|"triggers"| J
    B -->|"CI/CD triggers"| C
    C -->|"build-image"| D
    C -->|"build-image"| E
    D -->|"compose"| F
    E -->|"compose"| F
    I1 -->|"provisions"| F
    I2 -->|"provisions"| F
    F -->|"executes-model"| G
    H1 -->|"provides-config"| G
    H2 -->|"provides-docs"| G
    J -->|"runs-model"| G
    K -->|"visualizes-output"| G
    L -->|"evaluates-model"| G

    %% Click Events
    click D "https://github.com/ciroh-ua/ngiab-cloudinfra/tree/main/docker/Dockerfile"
    click E "https://github.com/ciroh-ua/ngiab-cloudinfra/blob/main/docker/HelloNGEN.sh"
    click H1 "https://github.com/ciroh-ua/ngiab-cloudinfra/blob/main/config/awi_simplified_realization.json"
    click H2 "https://github.com/ciroh-ua/ngiab-cloudinfra/blob/main/docs/Specification.md"
    click I1 "https://github.com/ciroh-ua/ngiab-cloudinfra/tree/main/terraform/network"
    click I2 "https://github.com/ciroh-ua/ngiab-cloudinfra/tree/main/terraform/user"
    click C "https://github.com/ciroh-ua/ngiab-cloudinfra/blob/main/.github"
    click J "https://github.com/ciroh-ua/ngiab-cloudinfra/blob/main/guide.sh"
    click K "https://github.com/ciroh-ua/ngiab-cloudinfra/blob/main/viewOnTethys.sh"
    click L "https://github.com/ciroh-ua/ngiab-cloudinfra/blob/main/runTeehr.sh"

    %% Styles
    classDef user fill:#f9d5bb,stroke:#e67700,stroke-width:2px;
    classDef repo fill:#d5f5e3,stroke:#196f3d,stroke-width:2px;
    classDef ci fill:#d6eaf8,stroke:#2874a6,stroke-width:2px;
    classDef build fill:#e8f8f5,stroke:#138d75,stroke-width:2px;
    classDef container fill:#fcf3cf,stroke:#b7950b,stroke-width:2px;
    classDef run fill:#f5eef8,stroke:#af7ac5,stroke-width:2px;
    classDef config fill:#fadbd8,stroke:#c0392b,stroke-width:2px;
    classDef infra fill:#e8daef,stroke:#884ea0,stroke-width:2px;
    classDef scripts fill:#d6eaf8,stroke:#1f618d,stroke-width:2px;
```
