# ncar/ccpp-framework architecture

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

- Interactive diagram: https://gitdiagram.com/ncar/ccpp-framework
- Repository: https://github.com/ncar/ccpp-framework

## Overview

##### Main Components

- Core CCPP Framework:
- Located under the “src” directory, this is where the main Fortran modules reside (e.g., ccpp_types.F90, ccpp_constituent_prop_mod.F90). This layer contains the core infrastructure that bridges the physics schemes with a host model interface.

- Stand-Alone Tools and Utilities:
- Found largely in the “scripts” directory, these Python scripts (such as ccpp_capgen.py, metadata_parser.py, fortran_tools, parse_tools, etc.) handle tasks like metadata extraction, code generation, prebuild configuration, variable tracking, and file conversion. These tools form the automation and integration backbone that supports code consistency and host model preparation.

- Host Model / Stub Interface:

- Testing Framework:
- A significant portion of the file tree is dedicated to “test” (and “test_prebuild”). These directories include unit tests, integration tests, and Fortran-based tests that validate components such as capgen, metadata parsing, and host model functionality. They serve as a verification layer and also hint at the modular structure.

- Documentation and Build Configuration:
- The “doc” folder and various top-level files (e.g., CMakeLists.txt) illustrate the integration of build systems and developer documentation. They are key for understanding project configuration and build pipelines.

##### Relationships and Interactions

- Data and Control Flow:

- Modular and Layered Architecture:

- Build and Deployment Processes:
- Build system via CMake configurations (both in “src”, “doc”, “stub”, etc.) and continuous integration tools (.github/workflows, .travis.yml). This shows how code, tests, and documentation are automatically built and validated.

##### Architectural Patterns and Design Principles

- Separation of Concerns:
- Clearly distinguish the roles: physics scheme integration (core framework), automation and metadata processing (scripts/tools), and host model demonstration (stub). This separation aids in maintaining a clean architecture.

- Metadata-Driven Code Generation:

- Testing as a First-Class Citizen:
- Since there is an extensive “test” hierarchy, include a dedicated testing component that interacts with both the core framework and the automation layer. Show that tests are responsible for validating data flow, integrity, and integration.

##### Technologies, Frameworks, and Libraries

- Fortran: Core language used for physics schemes and host model integration.
- Python: Used extensively in the toolset for tasks such as metadata parsing, code generation (e.g., ccpp_capgen.py), and state management.
- CMake: Utilized for building the Fortran source code (with top-level CMakeLists.txt and specific ones in “doc”, “src”, “stub”).
- Continuous Integration: GitHub Actions workflows (.github/workflows) and Travis CI (.travis.yml) for CI/CD.
- XML/XSD: Used in metadata and suite descriptions (e.g., schema/suite_v1_0.xsd, various XML files in tests).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Input
    metadata("Metadata/Schema"):::metadata

    %% Core Framework Layer
    subgraph "Core CCPP Framework"
        core("CCPP Core Modules"):::fortran
    end

    %% Stand-Alone Tools and Utilities Layer
    subgraph "Stand-Alone Tools and Utilities"
        tools("Metadata Parser & Code Generator (Python)"):::python
    end

    %% Host Model / Stub Interface Layer
    subgraph "Host Model / Stub Interface"
        host("Host Model Interface"):::host
    end

    %% Testing Framework Layer
    subgraph "Testing Framework"
        test("Testing & Validation"):::testing
    end

    %% Documentation and Build Configuration Layer
    subgraph "Documentation and Build Configuration"
        doc("Documentation & Build Config"):::doc
    end

    %% Connections and Data Flow
    metadata -->|"reads_metadata"| tools
    tools -->|"generates_code"| core
    tools -->|"generates_interface"| host
    core -->|"integrates_with"| host
    doc -->|"builds_core"| core
    doc -->|"builds_host"| host
    test -->|"validates_core"| core
    test -->|"validates_tools"| tools

    %% Click Events
    click core "https://github.com/ncar/ccpp-framework/tree/main/src"
    click tools "https://github.com/ncar/ccpp-framework/tree/main/scripts"
    click host "https://github.com/ncar/ccpp-framework/tree/main/stub"
    click test "https://github.com/ncar/ccpp-framework/tree/main/test"
    click doc "https://github.com/ncar/ccpp-framework/tree/main/doc"

    %% Styles
    classDef fortran fill:#AED6F1,stroke:#2E86C1,stroke-width:2px;
    classDef python fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef host fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef testing fill:#F5CBA7,stroke:#E67E22,stroke-width:2px;
    classDef doc fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef metadata fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
```
