# heitzmann/gdstk architecture

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

- Interactive diagram: https://gitdiagram.com/heitzmann/gdstk
- Repository: https://github.com/heitzmann/gdstk

## Overview

##### Main Components
a. Core C++ Library:
- Files under “src” (primary source code for various layout operations such as cell creation, polygon manipulations, curve and flexpath operations, etc.).
- Header files under “include” that define the API (e.g., cell.hpp, flexpath.hpp, polygon.hpp).
b. Python Module/Bindings:
- The “python” directory contains the binding code (with CMakeLists.txt and wrapping CPP files) that links Python calls to the core C++ library.
c. External Dependencies:
- External libraries such as zlib, Qhull, and the clipper module (found under “external/clipper” and referenced within the C++ source).
d. Documentation and Examples:
- “docs” directory documents the API, usage examples, and includes Sphinx configurations along with demo files.
e. Benchmarks and Performance Testing:
- “benchmarks” directory, which contains various Python scripts to measure performance gains.
f. Testing and CI/CD:
- “tests” directory for unit tests.
- GitHub workflows (in “.github/workflows”) that automate testing, documentation publishing, and package releases.
g. Build and Configuration:
- CMake configuration files (at the root, in “python” and “docs/cpp”) and the Makefile that orchestrate building the library and wrappers.
- Supporting scripts like CMakeLists.txt in the root and “pyproject.toml” for Python packaging.

##### Relationships and Interactions
- The Python module layer depends on the core C++ library, acting as a thin wrapper/binding so that Python users can leverage the high-performance C++ routines.
- The core C++ library interacts with external libraries (zlib, Qhull, and Clipper) to perform complex computations like polygon booleans, offsets, and geometry operations.
- Documentation is generated from the source code (both C++ and Python) and lives separately in the “docs” folder; it is also integrated into the CI/CD pipeline.
- Benchmark scripts call into both the Python interface and possibly directly into the C++ functions, illustrating performance differences.
- Tests exercise both the C++ logic (likely indirectly via the Python bindings) and integration aspects, triggered through automated workflows.

##### Architectural Patterns/Design Principles
- Layered Architecture: The design clearly separates the low-level geometric processing (core C++ logic) from the higher-level language bindings (Python module). This separation enables modular development and easier testing.
- Build Abstraction: The use of CMake and accompanying build scripts abstracts hardware/platform-specific details.
- Extensibility: The library components are designed to be used directly (as a C++ static library) or via Python, emphasizing modularity and reusability.
- Testing and Continuous Integration: Automated tests (via Python’s pytest or similar framework) and CI workflows demonstrate a commitment to robust, quality-assured design.

##### Technologies and Frameworks to Note
- C++ for the core implementation.
- Python for the wrapper module.
- CMake and Makefile for build automation.
- Sphinx (with relevant themes and plugins) for generating documentation.
- External libraries: zlib, Qhull, and Clipper.

##### Elements
– “Core C++ Library (src/include)”
– “Python Bindings/Module”
– “External Dependencies (zlib, Qhull, Clipper)”
– “Documentation (Sphinx, docs)”
– “Benchmarks (Performance Scripts)”
– “Tests (Unit Tests & CI/CD Workflows)”
– Data and function calling from Python to the C++ library.
– Interactions between the core library and external dependencies.
– The flow of the build process from CMake/Makefile to the final binaries and wheels.
– Core system components (e.g., libraries) versus auxiliary tools (e.g., documentation, tests).
– Programming language layers (C++ vs. Python).

##### Additional Recommendations
- Annotations explaining key architectural decisions (e.g., “This layer abstracts all geometry operations for high efficiency”, or “This binding layer exposes the API to Python users”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Layer: C++ Library
    subgraph "Core Layer: C++ Library"
        core_src["Core C++ Source (src)"]:::core
        core_include["API Headers (include/gdstk)"]:::core
    end

    %% External Dependencies
    subgraph "External Dependencies"
        clipper["Clipper (external/clipper)"]:::external
        qhull["Qhull (cmake_modules/FindQhull.cmake)"]:::external
        zlib["zlib"]:::external
    end

    %% Python Bindings
    subgraph "Python Bindings"
        py_module["Binding Source (python)"]:::python
        py_package["Python Package (__init__.py)"]:::python
    end

    %% Auxiliary Components
    subgraph "Auxiliary Components"
        docs["Documentation (docs)"]:::aux
        benchmarks["Benchmarks (benchmarks)"]:::aux
        tests["Unit Tests (tests)"]:::aux
        ci["CI/CD Workflows (.github/workflows)"]:::aux
    end

    %% Build & Configuration
    subgraph "Build & Configuration"
        root_build["Root Build (CMakeLists.txt & Makefile)"]:::build
        py_build["Python Build (python/CMakeLists.txt)"]:::build
        docs_build["Docs Build (docs/cpp/CMakeLists.txt)"]:::build
        py_pack["Python Packaging (pyproject.toml)"]:::build
    end

    %% Relationships

    %% Python Bindings invoke Core C++ Library
    py_module -->|"calls"| core_src
    py_module -->|"calls"| core_include
    py_package -->|"exposes API"| py_module

    %% Core C++ Library uses External Dependencies
    core_src -->|"uses"| clipper
    core_src -->|"uses"| qhull
    core_src -->|"uses"| zlib
    core_include -->|"defines API for"| core_src

    %% Documentation is generated from Core and Python layers
    core_src -->|"documented by"| docs
    py_module -->|"documented by"| docs

    %% Benchmarks test performance of Core and Python
    benchmarks -->|"measures"| core_src
    benchmarks -->|"measures"| py_module

    %% Testing validates Core and Python layers
    tests -->|"validates"| core_src
    tests -->|"validates"| py_module
    ci -->|"triggers"| tests

    %% Build and Configuration orchestrates the build process
    root_build -->|"builds"| core_src
    root_build -->|"builds"| core_include
    root_build -->|"builds"| py_module
    py_build -->|"configures"| py_module
    docs_build -->|"builds docs for"| docs
    py_pack -->|"packages"| py_module

    %% Click Events
    click core_src "https://github.com/heitzmann/gdstk/tree/main/src"
    click core_include "https://github.com/heitzmann/gdstk/tree/main/include/gdstk"
    click py_module "https://github.com/heitzmann/gdstk/tree/main/python"
    click py_package "https://github.com/heitzmann/gdstk/blob/main/gdstk/__init__.py"
    click clipper "https://github.com/heitzmann/gdstk/tree/main/external/clipper"
    click docs "https://github.com/heitzmann/gdstk/tree/main/docs"
    click benchmarks "https://github.com/heitzmann/gdstk/tree/main/benchmarks"
    click tests "https://github.com/heitzmann/gdstk/tree/main/tests"
    click ci "https://github.com/heitzmann/gdstk/tree/main/.github/workflows"
    click root_build "https://github.com/heitzmann/gdstk/blob/main/CMakeLists.txt"
    click py_build "https://github.com/heitzmann/gdstk/blob/main/python/CMakeLists.txt"
    click docs_build "https://github.com/heitzmann/gdstk/blob/main/docs/cpp/CMakeLists.txt"
    click py_pack "https://github.com/heitzmann/gdstk/blob/main/pyproject.toml"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef python fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef aux fill:#FAD7A0,stroke:#D68910,stroke-width:2px;
    classDef build fill:#D5DBDB,stroke:#566573,stroke-width:2px;
```
