# elalish/manifold architecture

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

- Interactive diagram: https://gitdiagram.com/elalish/manifold
- Repository: https://github.com/elalish/manifold

## Overview

##### Main Components
- Core Library (C++): Represent the “src” directory which houses the fundamental algorithms (mesh boolean operations, smoothing, triangulation, mesh imports/exports, etc.) and utility code.
- Bindings Layer: Package the “bindings” directory into subcomponents that expose the core functionality to different languages:
- C binding (“bindings/c”)
- Python binding (“bindings/python”) – additionally noting that nanobind is used.
- WASM/JavaScript binding (“bindings/wasm”) – intended for use in web applications.
- Build & Configuration: Reflect the use of CMake (multiple CMakeLists.txt files in the root, “bindings/”, “samples”, and “cmake” directories) which serves to configure builds, optional dependency flags, and integration of optional functionalities.
- Optional Dependencies and External Services: Create nodes for external libraries such as TBB (for parallel acceleration), Clipper2 (for 2D cross-section support), Assimp (for mesh I/O), and testing frameworks (GTest, Tracy). Also include how the project provides self-built paths such as built-in versions via FETCHCONTENT.
- Examples & Tests: Identify the “samples” and “test” directories that show usage examples and ensure functionality of the algorithms.
- Documentation and Support Tools: Include components for documentation (Doxyfile, docs directory, and README links), and supporting tools/scripts (like formatting, profiling scripts, and CI files in “.github”).

##### Relationships and Interactions
- Flow from API to Core: Illustrate how language-specific bindings (Python, JavaScript, C) serve as an interface to invoke core functionalities implemented in C++.
- Build Process: Represent how CMake scripts (located in various directories) coordinate the build configuration of the core library and bindings. Include the optional flags (like MANIFOLD_PAR for TBB and MANIFOLD_CROSS_SECTION for Clipper2) to show dependency injection.
- Testing and Examples: Show the role of the “test” and “extras” directories in validating core functionalities and the bindings.

##### Architectural Patterns and Key Design Principles
- Modularity: The separation of core algorithms (in “src”) from language-specific bindings (in “bindings”), ensuring that the library can be reused in diverse environments.
- Extensibility: A clear separation between optional dependencies (TBB, Clipper2, Assimp, etc.) and core functionality. This allows tailoring the build for performance or additional features.
- Portability & Flexibility: The use of CMake and the clear division between build components for native, WASM, and Python environments.

- Components like:
- “Core Mesh Operations” (resulting from files in “src” such as manifold.cpp, boolean operations, and polygon/triangulation algorithms).
- “API Bindings” pointing to the “bindings/c”, “bindings/python”, and “bindings/wasm” folders.
- “Parallel and I/O Libraries” nodes for TBB, Clipper2, and Assimp.
- “Build System” block showing CMake’s orchestration, along with CI integrations in the “.github” workflows.
- “Examples & Testing” block from the “samples” and “test” directories.

##### Detailed Components and Their Interactions
- Begin at the top with “User Applications” (e.g., npm package, Python scripts, and even web interfaces like ManifoldCAD.org).
- “Bindings Layer” as an abstraction layer converting user commands to calls into the “Core Engine” written in C++.
- High-level functions (like mesh boolean operations, smoothing, and triangulation) within the “Core Engine” block.
- That optional libraries (TBB for multi-threading, Clipper2, etc.) are integrated into the core but can be toggled via CMake flags.
- Also, denote support for input/output transformation through components like “Mesh IO” (via Assimp, etc.) and the “gltf-io.ts” in the WASM examples.
- Finally, include “Testing & Examples” as separate blocks ensuring reliability and as a demonstration of how clients use the library.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U["User Applications"]:::user

    subgraph "Bindings Layer"
        CBind["C Binding"]:::binding
        PyBind["Python Binding (nanobind)"]:::binding
        WasmBind["WASM/JS Binding"]:::binding
    end

    Core["Core C++ Engine"]:::core
    Build["CMake Build & Configuration"]:::build
    Optional["Optional Dependencies & External Services"]:::optional
    Examples["Examples"]:::example
    Testing["Testing"]:::test
    Docs["Documentation & Support Tools"]:::docs

    U --> CBind
    U --> PyBind
    U --> WasmBind

    CBind --> Core
    PyBind --> Core
    WasmBind --> Core

    Build --> Core
    Build --> CBind
    Build --> PyBind
    Build --> WasmBind
    Build --> Docs

    Core --> Optional
    Core --> Examples
    Core --> Testing

    click Core "https://github.com/elalish/manifold/tree/master/src"
    click CBind "https://github.com/elalish/manifold/tree/master/bindings/c"
    click PyBind "https://github.com/elalish/manifold/tree/master/bindings/python"
    click WasmBind "https://github.com/elalish/manifold/tree/master/bindings/wasm"
    click Build "https://github.com/elalish/manifold/blob/master/CMakeLists.txt"
    click Optional "https://github.com/elalish/manifold/blob/master/cmake/manifoldDeps.cmake"
    click Examples "https://github.com/elalish/manifold/tree/master/samples"
    click Testing "https://github.com/elalish/manifold/tree/master/test"
    click Docs "https://github.com/elalish/manifold/tree/master/.github/workflows/"

    classDef user fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef binding fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef core fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef build fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef optional fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef example fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef test fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef docs fill:#fefefe,stroke:#6c757d,stroke-width:2px;
```
