# ajkhattak/cfe architecture

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

- Interactive diagram: https://gitdiagram.com/ajkhattak/cfe
- Repository: https://github.com/ajkhattak/cfe

## Overview

##### Project type and purpose
- This is a scientific hydrological model (“Conceptual Functional Equivalent” or CFE) implemented in C/C++ with a BMI (Basic Model Interface) wrapper for coupling to external frameworks.
- It can run in standalone mode (reading CSV forcings), in pseudo‐framework mode (coupled via BMI to AORC weather data and PET modules), or in a next-gen framework mode.

##### File structure
- Top-level: CMakeLists.txt, build configs, submodules (extern), scripts (run_cfe.sh, run_unittest.sh), docs.
- src/: core code → bmi_cfe.c (BMI entrypoints), cfe.c (core model logic), conceptual_reservoir.c, giuh.c, nash_cascade.c, plus main_*.c/.cxx drivers for different runtimes.
- /: public headers for BMI and component interfaces.
- configs/: parameter files to drive model behavior.
- forcings/: sample CSV time series.
- extern/: submodules providing AORC BMI forcing and evapotranspiration modules.
- test/: unit tests and harness.
- original_author_code/: legacy reference implementation, not BMI-compatible.

##### Key insights from README
- CFE implements a simplified equivalent of the National Water Model in modular steps (reservoir, GIUH, Nash cascade).
- BMI interface is the coupling layer.
- Build via CMake, run five example modes.

##### Detail
- Build artifact path: CMake → libcfebmi.so, driver executables, test binaries.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Data Layer
    subgraph "Data Layer"
        ConfigMgr["Configuration Manager"]:::data
        CSVReader["Standalone CSV Reader"]:::data
        AORCSource["BMI Data Source (AORC)"]:::data
        EvapoSource["BMI Data Source (Evapotranspiration)"]:::data
    end

    %% Model Core
    subgraph "Model Core"
        StateContainer["Initialization & State Container"]:::core
        Reservoir["Conceptual Reservoir Module"]:::core
        GIUH["GIUH Module"]:::core
        Nash["Nash Cascade Module"]:::core
    end

    %% Interface Layer
    subgraph "Interface Layer"
        BMIWrapper["BMI Wrapper Interface"]:::interface
    end

    %% Execution Layer
    subgraph "Execution Layer"
        StandaloneDriver["Standalone Driver"]:::exec
        CSVDriver["CSV‐Forcing Driver"]:::exec
        AORCDriver["AORC+PET Driver"]:::exec
        NextGenDriver["AORC+PET+RZ‐AET Driver"]:::exec
        Scripts["Orchestration Scripts"]:::exec
    end

    %% External Modules
    subgraph "External Modules"
        AORCSource2["AORC BMI Module"]:::ext
        EvapoSource2["Evapotranspiration BMI Module"]:::ext
    end

    %% Testing
    subgraph "Testing"
        UnitTest["Unit Test Harness"]:::test
        TestScript["Test Orchestration Script"]:::test
    end

    %% Build & Deployment
    subgraph "Build & Deployment"
        CMake["CMake Build Config"]:::build
    end

    %% Connections
    StandaloneDriver -->|"loads"| ConfigMgr
    StandaloneDriver -->|"loads"| CSVReader
    CSVDriver -->|"loads"| ConfigMgr
    CSVDriver -->|"loads"| CSVReader
    AORCDriver -->|"loads"| ConfigMgr
    AORCDriver -->|"loads"| BMIWrapper
    NextGenDriver -->|"loads"| ConfigMgr
    NextGenDriver -->|"loads"| BMIWrapper
    Scripts -->|"invoke"| StandaloneDriver
    Scripts -->|"invoke"| CSVDriver
    Scripts -->|"invoke"| AORCDriver
    Scripts -->|"invoke"| NextGenDriver

    ConfigMgr -->|"config data"| StateContainer
    CSVReader -->|"forcings[T]"| StateContainer
    BMIWrapper -->|"initialize()/update()"| StateContainer

    BMIWrapper -->|"BMI calls"| AORCSource2
    BMIWrapper -->|"BMI calls"| EvapoSource2

    StateContainer -->|"state vars"| Reservoir
    Reservoir -->|"reservoir flux"| GIUH
    GIUH -->|"GIUH flux"| Nash
    Nash -->|"runoff flux"| BMIWrapper

    StateContainer -->|"state vars"| UnitTest
    BMIWrapper -->|"API calls"| UnitTest

    CMake -->|"build libs/exes"| StandaloneDriver
    CMake -->|"build libs/exes"| CSVDriver
    CMake -->|"build libs/exes"| AORCDriver
    CMake -->|"build libs/exes"| NextGenDriver
    CMake -->|"build libs"| BMIWrapper
    CMake -->|"build libs"| UnitTest

    %% Click Events
    click ConfigMgr "https://github.com/ajkhattak/cfe/tree/master/configs/"
    click CSVReader "https://github.com/ajkhattak/cfe/tree/master/forcings/"
    click AORCSource "https://github.com/ajkhattak/cfe/tree/master/extern/aorc_bmi/"
    click EvapoSource "https://github.com/ajkhattak/cfe/tree/master/extern/evapotranspiration/"
    click StateContainer "https://github.com/ajkhattak/cfe/blob/master/src/cfe.c"
    click Reservoir "https://github.com/ajkhattak/cfe/blob/master/src/conceptual_reservoir.c"
    click GIUH "https://github.com/ajkhattak/cfe/blob/master/src/giuh.c"
    click Nash "https://github.com/ajkhattak/cfe/blob/master/src/nash_cascade.c"
    click BMIWrapper "https://github.com/ajkhattak/cfe/blob/master/src/bmi_cfe.c"
    click StandaloneDriver "https://github.com/ajkhattak/cfe/blob/master/src/main.c"
    click CSVDriver "https://github.com/ajkhattak/cfe/blob/master/src/main_pass_forcings.c"
    click AORCDriver "https://github.com/ajkhattak/cfe/blob/master/src/main_cfe_aorc_pet.c"
    click NextGenDriver "https://github.com/ajkhattak/cfe/blob/master/src/main_cfe_aorc_pet_rz_aet.cxx"
    click Scripts "https://github.com/ajkhattak/cfe/blob/master/run_cfe.sh"
    click UnitTest "https://github.com/ajkhattak/cfe/blob/master/test/main_unit_test.c"
    click TestScript "https://github.com/ajkhattak/cfe/blob/master/test/run_unittest.sh"
    click CMake "https://github.com/ajkhattak/cfe/blob/master/CMakeLists.txt"

    %% Styles
    classDef data fill:#D0E6FB,stroke:#003366
    classDef core fill:#D0FBD0,stroke:#336600
    classDef interface fill:#FBE8A6,stroke:#997300
    classDef exec fill:#FDD0D8,stroke:#660000
    classDef ext fill:#E8E8E8,stroke:#666666
    classDef test fill:#E0E0E0,stroke:#333333
    classDef build fill:#F0E0FB,stroke:#663366
```
