Repository: PowerGridModel/power-grid-model
Pull request #969: Documentation: high-level design PGM
Author: login: mgovers
Labels: name: documentation
description: Improvements or additions to documentation
Created: 2025-04-25T08:31:23Z | Merged: 2025-04-29T08:03:06Z

Basic documentation regarding high-level package design + contributing new packages


Diff:
diff --git a/docs/advanced_documentation/high-level-design.md b/docs/advanced_documentation/high-level-design.md
new file mode 100644
index 0000000000..47b54dddea
--- /dev/null
+++ b/docs/advanced_documentation/high-level-design.md
@@ -0,0 +1,131 @@
+<!--
+SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+
+SPDX-License-Identifier: MPL-2.0
+-->
+
+# High-level design
+
+The power-grid-model follows a typical dynamic/shared library approach, in which the user
+interface is separated from the core implementation using a strict system boundary. Depending
+on the use case and programming language used by the user to call the interface, the user can
+opt to interface with the C API in different ways.
+
+## Layers of abstraction
+
+For the sake of explanation, we consider the
+following layers of abstraction, in increasing order of ease-of-use and abstraction.
+
+* Raw system interface
+  * System symbols only
+  * Everything is handled by the user, including which symbols are supported
+* Exposition-only
+  * Exposes the supported symbols in a language supported by the user
+  * Memory management and error handling is the responsibility of the user
+* Simple wrapper
+  * Wraps the interface in a language supported by the user
+  * Handles memory management, basic error handling and type conversions
+  * Contains no additional features except maybe some basic utility tools
+* The feature-rich layer
+  * Extensive wrapper around the interface with easy functionality exposure and utility functions
+  * Extensive type checks
+
+## Existing library interfaces
+
+The following library interfaces are currently included in the power-grid-model.
+
+| Interface type | Status       | Layer              | Explanation                                                     | Supported by                                        |
+| -------------- | ------------ | ------------------ | --------------------------------------------------------------- | --------------------------------------------------- |
+| C API          | Stable       | Raw interface      | Shared object / DLL that contains the core implementation       | All programming languages with dynamic load support |
+| C headers      | Stable       | Exposition-only    | Exposition-only library using dynamic linking                   | C and C++                                           |
+| C++ headers    | Experimental | Wrapper            | Handles memory management and basic error handling              | C++                                                 |
+| Python library | Stable       | Feature-rich layer | Library with useful functions, conversions and extensive checks | Python                                              |
+
+Note that the Python library in turn also follows the pattern of a feature-rich library that uses a
+module-internal wrapper layer core module, that wraps the exposition-only core module, that exposes
+the raw interface.
+
+This can be visualized graphically as follows.
+
+```{mermaid}
+    :title: Full design
+
+flowchart TD
+    classDef user_node fill:#9f6,stroke:#333,stroke-width:2px
+    classDef public_interface fill:#69f,stroke:#333,stroke-width:2px
+    classDef experimental_interface fill:#99b,stroke:#333,stroke-width:2px
+    classDef private_interface fill:#999,stroke:#333,stroke-width:2px
+    classDef inclusion_method fill:#ddd,stroke:#fff,stroke-width:2px
+
+    subgraph User
+        any_language_user(["Any language user"]):::user_node
+        c_user(["C user"]):::user_node
+        cpp_user(["C++ user"]):::user_node
+        python_user(["Python user"]):::user_node
+    end
+
+    dynamic_loading{ }:::inclusion_method
+    c_includes{ }:::inclusion_method
+
+    subgraph Raw interface
+        power_grid_model_c_dll("power_grid_model_c<br>(shared library)"):::public_interface
+    end
+
+    subgraph Exposition
+        power_grid_model_c("power_grid_model_c<br>(C library)"):::public_interface
+        power_grid_core_python("power_grid_model._core<br>.power_grid_core.py<br>(exposition-only<br>Python module)"):::private_interface
+    end
+
+    subgraph Wrapper
+        power_grid_model_cpp("power_grid_model_cpp<br>(experimental,<br>C++ library)"):::experimental_interface
+        power_grid_model_core_python("power_grid_model._core<br>(Python wrapper library)"):::private_interface
+    end
+
+    subgraph Feature-rich library
+        power_grid_model_python("power_grid_model<br>(Python library)"):::public_interface
+    end
+
+    any_language_user --> dynamic_loading
+    c_includes --> dynamic_loading
+    dynamic_loading -->|dynamic loading| power_grid_model_c_dll
+    c_user --> c_includes
+    cpp_user --> c_includes
+    c_includes -->|links +<br>includes| power_grid_model_c -->|dynamic linking| power_grid_model_c_dll
+    cpp_user -->|experimental<br>links +<br>includes| power_grid_model_cpp -->|links +<br>includes| power_grid_model_c
+    python_user -->|import| power_grid_model_python -->|internal import| power_grid_model_core_python -->|internal import| power_grid_core_python -->|"CDLL<br>(dynamic loading)"| power_grid_model_c_dll
+```
+
+## Creating a custom library or interface
+
+We seek to provide an optimal user experience, but with the sheer amount of programming languages and
+features, it would be impossible to provide a full feature-rich library for every single one. We,
+being a {{ "[community-driven]({}/GOVERNANCE.md)".format(pgm_project_contribution) }} project strongly in
+favor of modern software engineering practices, therefore encourage people to create their own
+libraries and interfaces to improve their own experience. There are several possible reasons a user
+may want to create their own library or interface, e.g.:
+
+* Support for a new programming language
+* Extending library support for a specific programming language
+* A custom wrapper that provides extra features or useful commands for specific custom requirements
+
+In all cases, it is recommended that the user determines their own desired
+[layer of abstraction](#layers-of-abstraction) and then creates internal wrappers for all
+lower-level ones, following the same pattern as the power-grid-model
+[uses internally](#existing-library-interfaces) for the custom interfaces.
+
+### Hosting a custom library or interface
+
+The Power Grid Model organization supports people creating and hosting custom libraries and
+interfaces. If you are doing so and are willing to notify us, please create an item on our
+[discussion board](https://github.com/orgs/PowerGridModel/discussions) on GitHub. The Power Grid
+Model organization will review your item and we may decide to mention your custom library on our
+project website and documentation.
+
+### Contributing a custom library or interface
+
+When a custom library or interface becomes mature enough and the circumstances allow making it
+publicly available, please consider contributing it to the Power Grid Model organization. If you are
+considering contributing your custom library or interface, please read and follow our
+{{ "[contributing guidelines]({}/CONTRIBUTING.md)".format(pgm_project_contribution) }} and open an
+item on our [discussion board](https://github.com/orgs/PowerGridModel/discussions) on GitHub. The
+Power Grid Model organization will review your item and contact you accordingly.
diff --git a/docs/conf.py b/docs/conf.py
index aa44d9edfc..94fecf87e7 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -25,9 +25,13 @@
     commit_version = git.Repo(search_parent_directories=True).head.object.hexsha
     link_head_gh_blob = link_head_gh + "blob/" + commit_version
     link_head_gh_tree = link_head_gh + "tree/" + commit_version
+    pgm_project_root = ""
+    pgm_project_contribution = pgm_project_root + "/contribution"
 else:
     link_head_gh_blob = ""
     link_head_gh_tree = ""
+    pgm_project_root = "https://github.com/PowerGridModel/.github/blob/main"
+    pgm_project_contribution = pgm_project_root
 
 
 # -- General configuration ---------------------------------------------------
@@ -78,6 +82,8 @@
 myst_substitutions = {
     "gh_link_head_blob": link_head_gh_blob,
     "gh_link_head_tree": link_head_gh_tree,
+    "pgm_project_root": pgm_project_root,
+    "pgm_project_contribution": pgm_project_contribution,
 }
 
 
diff --git a/docs/index.md b/docs/index.md
index e15fb5dca8..f465e4a54b 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -108,6 +108,7 @@ algorithms/lu-solver
 advanced_documentation/native-data-interface
 advanced_documentation/build-guide
 advanced_documentation/c-api
+advanced_documentation/high-level-design
 advanced_documentation/core-design
 advanced_documentation/python-wrapper-design
 ```


Reviews:
user: login: figueroa1395
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-28T05:56:17Z
user: login: figueroa1395
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-28T05:57:14Z
user: login: mgovers
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-28T06:26:33Z
user: login: mgovers
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-28T06:27:18Z
user: login: petersalemink95
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-28T09:37:26Z
user: login: TonyXiang8787
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-29T06:50:45Z
user: login: mgovers
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-29T06:54:12Z
user: login: TonyXiang8787
state: APPROVED
author_association: MEMBER
submitted_at: 2025-04-29T07:45:31Z
user: login: figueroa1395
state: APPROVED
author_association: MEMBER
submitted_at: 2025-04-29T07:47:53Z

Review comments:
diff_hunk: @@ -25,9 +25,13 @@
     commit_version = git.Repo(search_parent_directories=True).head.object.hexsha
     link_head_gh_blob = link_head_gh + "blob/" + commit_version
     link_head_gh_tree = link_head_gh + "tree/" + commit_version
+    pgm_project_root = ""
+    pgm_project_contribution = pgm_project_root + "/contribution"
path: docs/conf.py
user: login: figueroa1395
body: Could you quickly explain the reason for these changes and below?
created_at: 2025-04-28T05:50:17Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,180 @@
+<!--
+SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+
+SPDX-License-Identifier: MPL-2.0
+-->
+
+# High-level design
+
+The power-grid-model follows a typical dynamic/shared library approach, in which the user
+interface is separated from the core implementation using a strict system boundary. Depending
+on the use case and programming language used by the user to call the interface, the user can
+opt to interface with the C API in different ways.
+
+## Layers of abstraction
+
+For the sake of explanation, we consider the
+following layers of abstraction, in increasing order of ease-of-use and abstraction.
+
+* Raw system interface
+  * System symbols only
+  * Everything is handled by the user, including which symbols are supported
+* Exposition-only
+  * Exposes the supported symbols in a language supported by the user
+  * Memory management and error handling is the responsibility of the user
+* Simple wrapper
+  * Wraps the interface in a language supported by the user
+  * Handles memory management, basic error handling and type conversions
+  * Contains no additional features except maybe some basic utility tools
+* The feature-rich layer
+  * Extensive wrapper around the interface with easy functionality exposure and utility functions
+  * Extensive type checks
+
+## Existing library interfaces
+
+The following library interfaces are currently included in the power-grid-model.
+
+| Interface type | Status       | Layer              | Explanation                                                     | Supported by                                        |
+| -------------- | ------------ | ------------------ | --------------------------------------------------------------- | --------------------------------------------------- |
+| C API          | Stable       | Raw interface      | Shared object / DLL that contains the core implementation       | All programming languages with dynamic load support |
+| C headers      | Stable       | Exposition-only    | Exposition-only library using dynamic linking                   | C and C++                                           |
+| C++ headers    | Experimental | Wrapper            | Handles memory management and basic error handling              | C++                                                 |
+| Python library | Stable       | Feature-rich layer | Library with useful functions, conversions and extensive checks | Python                                              |
+
+Note that the Python library in turn also follows the pattern of a feature-rich library that uses a
+module-internal wrapper layer core module, that wraps the exposition-only core module, that exposes
+the raw interface.
+
+This can be visualized graphically as follows.
+
+```{mermaid}
+    :title: Public interfaces
+
+flowchart TD
+    classDef user_node fill:#9f6,stroke:#333,stroke-width:2px
+    classDef public_interface fill:#69f,stroke:#333,stroke-width:2px
+    classDef experimental_interface fill:#99b,stroke:#333,stroke-width:2px
+    classDef inclusion_method fill:#ddd,stroke:#fff,stroke-width:2px
+
+    subgraph User
+        any_language_user(["Any language user"]):::user_node
+        c_user(["C user"]):::user_node
+        cpp_user(["C++ user"]):::user_node
+        python_user(["Python user"]):::user_node
+    end
+
+    dynamic_loading{ }:::inclusion_method
+    c_includes{ }:::inclusion_method
+
+    subgraph Raw interface
+        power_grid_model_c_dll("power_grid_model_c<br>(shared library)"):::public_interface
+    end
+
+    subgraph Exposition
+        power_grid_model_c("power_grid_model_c<br>(C library)"):::public_interface
+    end
+
+    subgraph Wrapper
+        power_grid_model_cpp("power_grid_model_cpp<br>(experimental,<br>C++ library)"):::experimental_interface
+    end
+
+    subgraph Feature-rich library
+        power_grid_model_python("power_grid_model<br>(Python library)"):::public_interface
+    end
+
+    any_language_user --> dynamic_loading
+    c_includes --> dynamic_loading
+    dynamic_loading -->|dynamic loading| power_grid_model_c_dll
+    c_user --> c_includes
+    cpp_user --> c_includes
+    c_includes -->|links +<br>includes| power_grid_model_c -->|dynamic linking| power_grid_model_c_dll
+    cpp_user -->|experimental<br>links +<br>includes| power_grid_model_cpp -->|links +<br>includes| power_grid_model_c
+    python_user -->|import| power_grid_model_python -->|"CDLL<br>(dynamic loading)"| power_grid_model_c_dll
+```
+
+## Full high-level design
+
+This can be visualized graphically as follows.
+
+```{mermaid}
+    :title: Full design
path: docs/advanced_documentation/high-level-design.md
user: login: figueroa1395
body: I know this is still a draft, but I wanted to take a look anyway. I would say that probably one of the two graphs should go, which II would say should be the first.
created_at: 2025-04-28T05:56:17Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,180 @@
+<!--
+SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+
+SPDX-License-Identifier: MPL-2.0
+-->
+
+# High-level design
+
+The power-grid-model follows a typical dynamic/shared library approach, in which the user
+interface is separated from the core implementation using a strict system boundary. Depending
+on the use case and programming language used by the user to call the interface, the user can
+opt to interface with the C API in different ways.
+
+## Layers of abstraction
+
+For the sake of explanation, we consider the
+following layers of abstraction, in increasing order of ease-of-use and abstraction.
+
+* Raw system interface
+  * System symbols only
+  * Everything is handled by the user, including which symbols are supported
+* Exposition-only
+  * Exposes the supported symbols in a language supported by the user
+  * Memory management and error handling is the responsibility of the user
+* Simple wrapper
+  * Wraps the interface in a language supported by the user
+  * Handles memory management, basic error handling and type conversions
+  * Contains no additional features except maybe some basic utility tools
+* The feature-rich layer
+  * Extensive wrapper around the interface with easy functionality exposure and utility functions
+  * Extensive type checks
+
+## Existing library interfaces
+
+The following library interfaces are currently included in the power-grid-model.
+
+| Interface type | Status       | Layer              | Explanation                                                     | Supported by                                        |
+| -------------- | ------------ | ------------------ | --------------------------------------------------------------- | --------------------------------------------------- |
+| C API          | Stable       | Raw interface      | Shared object / DLL that contains the core implementation       | All programming languages with dynamic load support |
+| C headers      | Stable       | Exposition-only    | Exposition-only library using dynamic linking                   | C and C++                                           |
+| C++ headers    | Experimental | Wrapper            | Handles memory management and basic error handling              | C++                                                 |
+| Python library | Stable       | Feature-rich layer | Library with useful functions, conversions and extensive checks | Python                                              |
+
+Note that the Python library in turn also follows the pattern of a feature-rich library that uses a
+module-internal wrapper layer core module, that wraps the exposition-only core module, that exposes
+the raw interface.
+
+This can be visualized graphically as follows.
+
+```{mermaid}
+    :title: Public interfaces
+
+flowchart TD
+    classDef user_node fill:#9f6,stroke:#333,stroke-width:2px
+    classDef public_interface fill:#69f,stroke:#333,stroke-width:2px
+    classDef experimental_interface fill:#99b,stroke:#333,stroke-width:2px
+    classDef inclusion_method fill:#ddd,stroke:#fff,stroke-width:2px
+
+    subgraph User
+        any_language_user(["Any language user"]):::user_node
+        c_user(["C user"]):::user_node
+        cpp_user(["C++ user"]):::user_node
+        python_user(["Python user"]):::user_node
+    end
+
+    dynamic_loading{ }:::inclusion_method
+    c_includes{ }:::inclusion_method
+
+    subgraph Raw interface
+        power_grid_model_c_dll("power_grid_model_c<br>(shared library)"):::public_interface
+    end
+
+    subgraph Exposition
+        power_grid_model_c("power_grid_model_c<br>(C library)"):::public_interface
+    end
+
+    subgraph Wrapper
+        power_grid_model_cpp("power_grid_model_cpp<br>(experimental,<br>C++ library)"):::experimental_interface
+    end
+
+    subgraph Feature-rich library
+        power_grid_model_python("power_grid_model<br>(Python library)"):::public_interface
+    end
+
+    any_language_user --> dynamic_loading
+    c_includes --> dynamic_loading
+    dynamic_loading -->|dynamic loading| power_grid_model_c_dll
+    c_user --> c_includes
+    cpp_user --> c_includes
+    c_includes -->|links +<br>includes| power_grid_model_c -->|dynamic linking| power_grid_model_c_dll
+    cpp_user -->|experimental<br>links +<br>includes| power_grid_model_cpp -->|links +<br>includes| power_grid_model_c
+    python_user -->|import| power_grid_model_python -->|"CDLL<br>(dynamic loading)"| power_grid_model_c_dll
+```
+
+## Full high-level design
+
+This can be visualized graphically as follows.
+
+```{mermaid}
+    :title: Full design
+
+flowchart TD
+    classDef user_node fill:#9f6,stroke:#333,stroke-width:2px
+    classDef public_interface fill:#69f,stroke:#333,stroke-width:2px
+    classDef experimental_interface fill:#99b,stroke:#333,stroke-width:2px
+    classDef private_interface fill:#999,stroke:#333,stroke-width:2px
+    classDef inclusion_method fill:#ddd,stroke:#fff,stroke-width:2px
+
+    subgraph User
+        any_language_user(["Any language user"]):::user_node
+        c_user(["C user"]):::user_node
+        cpp_user(["C++ user"]):::user_node
+        python_user(["Python user"]):::user_node
+    end
+
+    dynamic_loading{ }:::inclusion_method
+    c_includes{ }:::inclusion_method
+
+    subgraph Raw interface
+        power_grid_model_c_dll("power_grid_model_c<br>(shared library)"):::public_interface
+    end
+
+    subgraph Exposition
+        power_grid_model_c("power_grid_model_c<br>(C library)"):::public_interface
+        power_grid_core_python("power_grid_model._core<br>.power_grid_core.py<br>(exposition-only<br>Python module)"):::private_interface
+    end
+
+    subgraph Wrapper
+        power_grid_model_cpp("power_grid_model_cpp<br>(experimental,<br>C++ library)"):::experimental_interface
+        power_grid_model_core_python("power_grid_model._core<br>(Python wrapper library)"):::private_interface
+    end
+
+    subgraph Feature-rich library
+        power_grid_model_python("power_grid_model<br>(Python library)"):::public_interface
+    end
+
+    any_language_user --> dynamic_loading
+    c_includes --> dynamic_loading
+    dynamic_loading -->|dynamic loading| power_grid_model_c_dll
+    c_user --> c_includes
+    cpp_user --> c_includes
+    c_includes -->|links +<br>includes| power_grid_model_c -->|dynamic linking| power_grid_model_c_dll
+    cpp_user -->|experimental<br>links +<br>includes| power_grid_model_cpp -->|links +<br>includes| power_grid_model_c
+    python_user -->|import| power_grid_model_python -->|internal import| power_grid_model_core_python -->|internal import| power_grid_core_python -->|"CDLL<br>(dynamic loading)"| power_grid_model_c_dll
+```
+
+## Creating a custom library or interface
+
+We seek to provide an optimal user experience, but with sheer amount of programming languages and
path: docs/advanced_documentation/high-level-design.md
user: login: figueroa1395
body: ```suggestion
We seek to provide an optimal user experience, but with the sheer amount of programming languages and
```
created_at: 2025-04-28T05:57:14Z
author_association: MEMBER
diff_hunk: @@ -25,9 +25,13 @@
     commit_version = git.Repo(search_parent_directories=True).head.object.hexsha
     link_head_gh_blob = link_head_gh + "blob/" + commit_version
     link_head_gh_tree = link_head_gh + "tree/" + commit_version
+    pgm_project_root = ""
+    pgm_project_contribution = pgm_project_root + "/contribution"
path: docs/conf.py
user: login: mgovers
body: it's a combination of factors:

* up til now, we haven't had any links to the downloaded markdown files from the `PowerGridModel/.github` repo. This is the first time we add those
* up til now, we haven't enforced broken links to be fixed. if you don't download the files manually (which is done in `.readthedocs.yml`), they do not exist, resulting in broken links

this PR adds support for referencing those downloaded external markdown files by linking to the github version when it's a local build, and by referencing the actual path where the files are downloaded in the readthedocs build
created_at: 2025-04-28T06:26:33Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,180 @@
+<!--
+SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+
+SPDX-License-Identifier: MPL-2.0
+-->
+
+# High-level design
+
+The power-grid-model follows a typical dynamic/shared library approach, in which the user
+interface is separated from the core implementation using a strict system boundary. Depending
+on the use case and programming language used by the user to call the interface, the user can
+opt to interface with the C API in different ways.
+
+## Layers of abstraction
+
+For the sake of explanation, we consider the
+following layers of abstraction, in increasing order of ease-of-use and abstraction.
+
+* Raw system interface
+  * System symbols only
+  * Everything is handled by the user, including which symbols are supported
+* Exposition-only
+  * Exposes the supported symbols in a language supported by the user
+  * Memory management and error handling is the responsibility of the user
+* Simple wrapper
+  * Wraps the interface in a language supported by the user
+  * Handles memory management, basic error handling and type conversions
+  * Contains no additional features except maybe some basic utility tools
+* The feature-rich layer
+  * Extensive wrapper around the interface with easy functionality exposure and utility functions
+  * Extensive type checks
+
+## Existing library interfaces
+
+The following library interfaces are currently included in the power-grid-model.
+
+| Interface type | Status       | Layer              | Explanation                                                     | Supported by                                        |
+| -------------- | ------------ | ------------------ | --------------------------------------------------------------- | --------------------------------------------------- |
+| C API          | Stable       | Raw interface      | Shared object / DLL that contains the core implementation       | All programming languages with dynamic load support |
+| C headers      | Stable       | Exposition-only    | Exposition-only library using dynamic linking                   | C and C++                                           |
+| C++ headers    | Experimental | Wrapper            | Handles memory management and basic error handling              | C++                                                 |
+| Python library | Stable       | Feature-rich layer | Library with useful functions, conversions and extensive checks | Python                                              |
+
+Note that the Python library in turn also follows the pattern of a feature-rich library that uses a
+module-internal wrapper layer core module, that wraps the exposition-only core module, that exposes
+the raw interface.
+
+This can be visualized graphically as follows.
+
+```{mermaid}
+    :title: Public interfaces
+
+flowchart TD
+    classDef user_node fill:#9f6,stroke:#333,stroke-width:2px
+    classDef public_interface fill:#69f,stroke:#333,stroke-width:2px
+    classDef experimental_interface fill:#99b,stroke:#333,stroke-width:2px
+    classDef inclusion_method fill:#ddd,stroke:#fff,stroke-width:2px
+
+    subgraph User
+        any_language_user(["Any language user"]):::user_node
+        c_user(["C user"]):::user_node
+        cpp_user(["C++ user"]):::user_node
+        python_user(["Python user"]):::user_node
+    end
+
+    dynamic_loading{ }:::inclusion_method
+    c_includes{ }:::inclusion_method
+
+    subgraph Raw interface
+        power_grid_model_c_dll("power_grid_model_c<br>(shared library)"):::public_interface
+    end
+
+    subgraph Exposition
+        power_grid_model_c("power_grid_model_c<br>(C library)"):::public_interface
+    end
+
+    subgraph Wrapper
+        power_grid_model_cpp("power_grid_model_cpp<br>(experimental,<br>C++ library)"):::experimental_interface
+    end
+
+    subgraph Feature-rich library
+        power_grid_model_python("power_grid_model<br>(Python library)"):::public_interface
+    end
+
+    any_language_user --> dynamic_loading
+    c_includes --> dynamic_loading
+    dynamic_loading -->|dynamic loading| power_grid_model_c_dll
+    c_user --> c_includes
+    cpp_user --> c_includes
+    c_includes -->|links +<br>includes| power_grid_model_c -->|dynamic linking| power_grid_model_c_dll
+    cpp_user -->|experimental<br>links +<br>includes| power_grid_model_cpp -->|links +<br>includes| power_grid_model_c
+    python_user -->|import| power_grid_model_python -->|"CDLL<br>(dynamic loading)"| power_grid_model_c_dll
+```
+
+## Full high-level design
+
+This can be visualized graphically as follows.
+
+```{mermaid}
+    :title: Full design
path: docs/advanced_documentation/high-level-design.md
user: login: mgovers
body: peter originally requested both (based on the distinction between the user-picture and the dev-picture) but let's see what his opinion is
created_at: 2025-04-28T06:27:17Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,180 @@
+<!--
+SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+
+SPDX-License-Identifier: MPL-2.0
+-->
+
+# High-level design
+
+The power-grid-model follows a typical dynamic/shared library approach, in which the user
+interface is separated from the core implementation using a strict system boundary. Depending
+on the use case and programming language used by the user to call the interface, the user can
+opt to interface with the C API in different ways.
+
+## Layers of abstraction
+
+For the sake of explanation, we consider the
+following layers of abstraction, in increasing order of ease-of-use and abstraction.
+
+* Raw system interface
+  * System symbols only
+  * Everything is handled by the user, including which symbols are supported
+* Exposition-only
+  * Exposes the supported symbols in a language supported by the user
+  * Memory management and error handling is the responsibility of the user
+* Simple wrapper
+  * Wraps the interface in a language supported by the user
+  * Handles memory management, basic error handling and type conversions
+  * Contains no additional features except maybe some basic utility tools
+* The feature-rich layer
+  * Extensive wrapper around the interface with easy functionality exposure and utility functions
+  * Extensive type checks
+
+## Existing library interfaces
+
+The following library interfaces are currently included in the power-grid-model.
+
+| Interface type | Status       | Layer              | Explanation                                                     | Supported by                                        |
+| -------------- | ------------ | ------------------ | --------------------------------------------------------------- | --------------------------------------------------- |
+| C API          | Stable       | Raw interface      | Shared object / DLL that contains the core implementation       | All programming languages with dynamic load support |
+| C headers      | Stable       | Exposition-only    | Exposition-only library using dynamic linking                   | C and C++                                           |
+| C++ headers    | Experimental | Wrapper            | Handles memory management and basic error handling              | C++                                                 |
+| Python library | Stable       | Feature-rich layer | Library with useful functions, conversions and extensive checks | Python                                              |
+
+Note that the Python library in turn also follows the pattern of a feature-rich library that uses a
+module-internal wrapper layer core module, that wraps the exposition-only core module, that exposes
+the raw interface.
+
+This can be visualized graphically as follows.
+
+```{mermaid}
+    :title: Public interfaces
+
+flowchart TD
+    classDef user_node fill:#9f6,stroke:#333,stroke-width:2px
+    classDef public_interface fill:#69f,stroke:#333,stroke-width:2px
+    classDef experimental_interface fill:#99b,stroke:#333,stroke-width:2px
+    classDef inclusion_method fill:#ddd,stroke:#fff,stroke-width:2px
+
+    subgraph User
+        any_language_user(["Any language user"]):::user_node
+        c_user(["C user"]):::user_node
+        cpp_user(["C++ user"]):::user_node
+        python_user(["Python user"]):::user_node
+    end
+
+    dynamic_loading{ }:::inclusion_method
+    c_includes{ }:::inclusion_method
+
+    subgraph Raw interface
+        power_grid_model_c_dll("power_grid_model_c<br>(shared library)"):::public_interface
+    end
+
+    subgraph Exposition
+        power_grid_model_c("power_grid_model_c<br>(C library)"):::public_interface
+    end
+
+    subgraph Wrapper
+        power_grid_model_cpp("power_grid_model_cpp<br>(experimental,<br>C++ library)"):::experimental_interface
+    end
+
+    subgraph Feature-rich library
+        power_grid_model_python("power_grid_model<br>(Python library)"):::public_interface
+    end
+
+    any_language_user --> dynamic_loading
+    c_includes --> dynamic_loading
+    dynamic_loading -->|dynamic loading| power_grid_model_c_dll
+    c_user --> c_includes
+    cpp_user --> c_includes
+    c_includes -->|links +<br>includes| power_grid_model_c -->|dynamic linking| power_grid_model_c_dll
+    cpp_user -->|experimental<br>links +<br>includes| power_grid_model_cpp -->|links +<br>includes| power_grid_model_c
+    python_user -->|import| power_grid_model_python -->|"CDLL<br>(dynamic loading)"| power_grid_model_c_dll
+```
+
+## Full high-level design
+
+This can be visualized graphically as follows.
+
+```{mermaid}
+    :title: Full design
path: docs/advanced_documentation/high-level-design.md
user: login: petersalemink95
body: I agree that only the second (extensive) graph would suffice here 
created_at: 2025-04-28T09:37:26Z
author_association: MEMBER
path: docs/advanced_documentation/high-level-design.md
user: login: TonyXiang8787
body: @mgovers  the two diagrams are almost identical? What is the reason to have two?
created_at: 2025-04-29T06:50:45Z
author_association: MEMBER
path: docs/advanced_documentation/high-level-design.md
user: login: mgovers
body: i already had removed one of them locally but i had forgotten to push 🤦 
created_at: 2025-04-29T06:54:12Z
author_association: MEMBER

PR comments:
user: login: mgovers
created_at: 2025-04-28T12:49:10Z
body: cfr. conceptual approval from @petersalemink95: OK for review as-is
author_association: MEMBER
user: login: sonarqubecloud[bot]
created_at: 2025-04-29T07:21:32Z
body: ## [![Quality Gate Passed](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/checks/QualityGateBadge/qg-passed-20px.png 'Quality Gate Passed')](https://sonarcloud.io/dashboard?id=PowerGridModel_power-grid-model&pullRequest=969) **Quality Gate passed**  
Issues  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0 New issues](https://sonarcloud.io/project/issues?id=PowerGridModel_power-grid-model&pullRequest=969&issueStatuses=OPEN,CONFIRMED&sinceLeakPeriod=true)  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/accepted-16px.png '') [0 Accepted issues](https://sonarcloud.io/project/issues?id=PowerGridModel_power-grid-model&pullRequest=969&issueStatuses=ACCEPTED)

Measures  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0 Security Hotspots](https://sonarcloud.io/project/security_hotspots?id=PowerGridModel_power-grid-model&pullRequest=969&issueStatuses=OPEN,CONFIRMED&sinceLeakPeriod=true)  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0.0% Coverage on New Code](https://sonarcloud.io/component_measures?id=PowerGridModel_power-grid-model&pullRequest=969&metric=new_coverage&view=list)  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0.0% Duplication on New Code](https://sonarcloud.io/component_measures?id=PowerGridModel_power-grid-model&pullRequest=969&metric=new_duplicated_lines_density&view=list)  
  
[See analysis details on SonarQube Cloud](https://sonarcloud.io/dashboard?id=PowerGridModel_power-grid-model&pullRequest=969)


author_association: NONE