# gridappsd/cimhub architecture

> Architecture diagram of the GitHub repository gridappsd/cimhub, 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/gridappsd/cimhub
- Repository: https://github.com/gridappsd/cimhub

## Overview

##### Main Components
- Converter Engine – This encapsulates the conversion modules that translate between OpenDSS, CIM, GridLAB-D, and CSV formats. There are separate conversion scripts in Java (found under “cimhub/src” and Maven-based builds) and in Python (in “src_python/cimhub”).
- Input/Output Modules – Multiple directories (for IEEE test cases, BES, OEDI, CPYDAR, ecP, etc.) provide inputs (raw or test circuit files) and expect outputs (converted files in various formats). “example”, “tutorial”, and “tests” are key directories that receive/process these files.
- Command-line/Script Interfaces – There are various shell scripts, batch files (e.g., start.sh, stop.sh, onestep.py), and Docker-related files (e.g., Dockerfile, docker-compose.yml) which show that the system supports a CLI-based workflow as well as container-based deployment.
- External Dependencies/Third-Party Tools – Include references to external converters such as OpenDSSCmd and GridLAB-D, as well as dependencies like SparkQLWrapper (for Python) and Apache Maven for building Java code.

##### Relationships and Data Flow
- Bidirectional interactions between the converter modules and the Blazegraph triple-store (using SPARQL queries for both input retrieval and database population).
- For Java-based processing (the “cimhub/src” module) and Python-based processing (in “src_python/cimhub”), indicate that they use their respective dependencies to perform operations like CIM import, conversion, and export.
- From the converter engine outputs, show separate flows to external tools like GridLAB-D and OpenDSS (also to CSV generation) which are validated through automated test suites (shown under the “tests” directory) and example pipelines.
- If desired, highlight that the Docker orchestration binds volumes (e.g., “/data” for persistent storage and “/platform” for host integration) and encapsulates the runtime environment for the system.

##### Architectural Patterns/Principles
- Modularity – The system is segmented into various conversion, testing, input handling, and output generation components, each developed in separate directories or even languages (Java vs. Python).
- Separation of Concerns – The design naturally separates data storage (Blazegraph), conversion logic (CIMHub Java/Python converters), and utility/testing scripts.
- Docker Integration – Illustrate the containerization strategy to encapsulate dependencies and ease deployment across different platforms (Linux, Windows, Mac).

##### Details on Technologies and Frameworks
- Java (OpenJDK 11, Apache Maven, and associated build scripts such as build.gradle, gradlew) for core conversion modules.
- Python (version 3.8+ along with SPARQLWrapper and other libraries available in “src_python/cimhub”) for scripting and automation.
- Blazegraph as the triple-store for CIM data.
- Docker for containerizing the runtime environment.
- External tools like OpenDSSCmd and GridLAB-D which interact with the converted outputs.
- Git LFS (for handling large CIM and test case files).

##### Recommended Elements
- Each component should be clearly labeled.
- Optionally, annotate version information or dependencies (e.g., Java 11, Python 3.8+), and include Docker as an encapsulation layer if the deployment architecture is intended to cover that aspect.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Files Subgraph
    subgraph "Input Files"
        FI1["Example Files"]:::file
        FI2["Tutorial Files"]:::file
        FI3["Test Suites"]:::file
    end

    %% CLI & Script Interfaces Subgraph
    subgraph "CLI & Script Interfaces"
        CLI1["start.sh"]:::cli
        CLI2["stop.sh"]:::cli
        CLI3["Deploy Script (sh)"]:::cli
        CLI4["Deploy Script (bat)"]:::cli
    end

    %% Core Converter Engines Subgraph
    subgraph "Converter Engines"
        JConv["Converter Engine (Java)"]:::java
        PConv["Converter Engine (Python)"]:::python
    end

    %% Data Storage
    DB["Blazegraph Triple-Store"]:::db

    %% External Tools and Outputs
    EX["Exports (OpenDSS,GridLAB-D,CSV)"]:::ext

    %% Docker Environment and Configurations Subgraph
    subgraph "Docker Environment"
        DockerEnv["Docker Environment"]:::docker
        DF["Dockerfile"]:::docker
        DC["docker-compose.yml"]:::docker
    end

    %% Data Flow Connections
    %% File I/O to Converter Engines
    FI1 -->|"input"| JConv
    FI1 -->|"input"| PConv
    FI2 -->|"input"| JConv
    FI2 -->|"input"| PConv
    FI3 -->|"input"| JConv
    FI3 -->|"input"| PConv

    %% CLI Scripts trigger Converter Engines
    CLI1 -->|"executes"| JConv
    CLI1 -->|"executes"| PConv
    CLI2 -->|"executes"| JConv
    CLI2 -->|"executes"| PConv
    CLI3 -->|"executes"| JConv
    CLI3 -->|"executes"| PConv
    CLI4 -->|"executes"| JConv
    CLI4 -->|"executes"| PConv

    %% Converter Engines interact with Blazegraph Triple-Store (bidirectional)
    JConv <-->|"CIM data"| DB
    PConv <-->|"CIM data"| DB

    %% Converter Engines output to External Tools
    JConv -->|"export"| EX
    PConv -->|"export"| EX

    %% Docker Environment encapsulates core components
    DockerEnv --- JConv
    DockerEnv --- PConv
    DockerEnv --- DB
    DF -->|"configures"| DockerEnv
    DC -->|"configures"| DockerEnv

    %% Styles
    classDef java fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef python fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef db fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef file fill:#FDEBD0,stroke:#CA6F1E,stroke-width:2px;
    classDef cli fill:#E8DAEF,stroke:#884EA0,stroke-width:2px;
    classDef docker fill:#D6EAF8,stroke:#2874A6,stroke-width:2px;
    classDef ext fill:#F5B7B1,stroke:#943126,stroke-width:2px;

    %% Click Events for Component Mappings
    click JConv "https://github.com/gridappsd/cimhub/tree/master/cimhub/src/main/java/gov/pnnl/gridappsd/cimhub"
    click PConv "https://github.com/gridappsd/cimhub/tree/master/src_python/cimhub"
    click DB "https://github.com/gridappsd/cimhub/tree/master/blazegraph"
    click FI1 "https://github.com/gridappsd/cimhub/tree/master/example"
    click FI2 "https://github.com/gridappsd/cimhub/tree/master/tutorial"
    click FI3 "https://github.com/gridappsd/cimhub/tree/master/tests"
    click CLI1 "https://github.com/gridappsd/cimhub/blob/master/start.sh"
    click CLI2 "https://github.com/gridappsd/cimhub/blob/master/stop.sh"
    click CLI3 "https://github.com/gridappsd/cimhub/blob/master/cimhub/deploy.sh"
    click CLI4 "https://github.com/gridappsd/cimhub/blob/master/deploy.bat"
    click DF "https://github.com/gridappsd/cimhub/tree/master/Dockerfile"
    click DC "https://github.com/gridappsd/cimhub/blob/master/docker-compose.yml"
```
