# thatopen/engine_web-ifc architecture

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

- Interactive diagram: https://gitdiagram.com/thatopen/engine_web-ifc
- Repository: https://github.com/thatopen/engine_web-ifc

## Overview

##### Project Type and Purpose
- This is an open-source, cross-platform library (“web-ifc”) for reading and writing IFC (Industry Foundation Classes) BIM files at native (C++/WASM) speeds from JavaScript/TypeScript environments (browser and Node.js).
- Purpose: Provide a high-performance core (in C++) compiled to WebAssembly, plus JS/TS wrappers and schema generators to let web and Node applications load, parse, query, and export IFC data.

##### File Structure Analysis
- Top-level:
- Dockerfile, CI/CD configs (.github/workflows), Node configs (package.json, tsconfig.json), LICENSE, README.
- examples/ – usage demos in Node.js, browser viewer, TypeScript samples.
- src/ – three main subfolders:
– cpp/ – the C++ codebase organized into parsing, schema, model management, geometry, boolean ops, and Wasm entrypoints.
– schema-generator/ – TS scripts that generate schema interfaces/types from IFC EXPRESS files.
– ts/ – public TypeScript wrapper (web-ifc-api.ts) and helper modules (log, properties).
- dist/ (output after build) contains .wasm binaries and JS wrappers.
- tests/ – unit, functional, regression tests using Jest and custom scripts.

##### README Insights
- Build pipeline:
– Requires Node, NPM, Emscripten, CMake (and optional MinGW on Windows).
– npm scripts: setup-env, build-release/debug, dev server, regression tests.
– Outputs: web-ifc.wasm/.mt/.node, web-ifc-api.js/.d.ts, helpers, schema typings, worker script.
- Usage flow:
– JS/TS code calls IfcAPI.Init(), OpenModel, geometry/property fetch, CloseModel.

a. Main Components
1. Development Environment
- Node.js + NPM
- Emscripten & CMake toolchain
- TypeScript compiler (tsc)
2. Build Pipeline
- schema-generator TS scripts → generates IFC schema TS definitions
- CMake + Emscripten → compiles C++ core → multiple WASM binaries
- Wrappers bundling → web-ifc-api.js, web-ifc-api-node.js, worker scripts
3. Core Library at Runtime
- JavaScript/TypeScript Layer
- web-ifc-api.js (browser)
- web-ifc-api-node.js (Node)
- WebAssembly Layer
- web-ifc.wasm (single-thread)
- web-ifc-mt.wasm + web-ifc-mt.worker.js (multithread)
- web-ifc-node.wasm
- C++ Modules inside WASM
- Parsing (IfcLoader, token streams)
- Model Manager (ModelManager)
- Geometry Processor & Loader
- Schema Manager (IfcSchemaManager)
- Boolean & geometry utility operations
4. Consumers and Integrations
- Examples (Node script, browser viewer)
- Third-party libs (e.g., web-ifc-three)
- Tests (functional & regression feeding IFC files)
- CI/CD pipeline running build, tests, publish.

b. Relationships & Data Flow
- Developer invokes `npm run build` → schema-generator & CMake/Emscripten → produces WASM + JS wrappers.
- At runtime: App code → web-ifc-api.js → loads appropriate WASM (via dynamic import or worker) → calls into C++ modules → returns geometry/properties to JS.
- Tests & examples drive the API similarly, feeding IFC files (binary) into OpenModel and consuming outputs.

c. Architectural Patterns
- Layered architecture: TS/JS API layer on top of WASM layer, on top of C++ core modules.
- Build-time code generation (schema-generator) to derive types and interfaces.
- Multi-build targets (browser, node, multithread).
- Modular C++: separation between parsing, schema, model management, geometry operations.

d. Key Technologies & Frameworks
- Emscripten + CMake (WASM build)
- TypeScript (schema-generator, API)
- Jest (testing)
- npm scripts for orchestration
- Web Workers (multithreading in browser)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build-Time Components
    subgraph "Build Pipeline" 
        direction TB
        SG["Schema Generator"]:::build
        CMake["CMake/Emscripten"]:::build
        TSComp["TypeScript Compiler"]:::build
        SG -->|"generate .d.ts"| TSComp
        TSComp -->|"compile TS to JS"| Wrappers
        CMake -->|"compile to WASM"| WASMBins
    end

    %% Runtime Components
    subgraph "Runtime" 
        direction TB
        subgraph "Consumer Apps" 
            direction TB
            Examples["Examples/Tests/Third-Party"]:::consumer
        end
        subgraph "JS/TS Layer"
            direction TB
            Wrappers["JS/TS Wrappers"]:::api
            Wrappers -->|"load WASM"| WASMBins
        end
        subgraph "WebAssembly Layer"
            direction TB
            WASMBins["WASM Binaries"]:::wasm
            WASMBins -->|"invoke"| Core
        end
        subgraph "C++ Core Modules"
            direction TB
            Parsing["Parsing Module"]:::cpp
            Geometry["Geometry Module"]:::cpp
            ModelMgr["Model Manager"]:::cpp
            SchemaMgr["Schema Manager"]:::cpp
            BooleanOps["Boolean Operations"]:::cpp
        end
        Examples -->|"OpenModel(IFC data)"| Wrappers
        Core["Core Entry Point"]:::cpp
        WASMBins -->|"entry point"| Core
        Core --> Parsing
        Core --> ModelMgr
        Core --> SchemaMgr
        Core --> Geometry
        Geometry --> BooleanOps
        Parsing -->|"tokens"| ModelMgr
        ScheRetrn["Results"]:::data
        BooleanOps --> ScheRetrn
        ModelMgr --> ScheRetrn
        ScheRetrn --> Wrappers
        Wrappers --> Examples
    end

    %% CI/CD Pipeline
    subgraph "CI/CD" 
        direction TB
        CI["CI/CD Workflows"]:::ci
        Docker["Docker Environment"]:::ci
        CI -->|"run build/test"| SG
        CI -->|"publish artifacts"| Wrappers
        Docker --> CI
    end

    %% Artifacts Nodes
    WASMBins -->|"artifacts"| Dist["dist/ (wasm + js)"]:::artifact
    Wrappers -->|"artifacts"| Dist

    %% Click Events
    click SG "https://github.com/thatopen/engine_web-ifc/tree/main/src/schema-generator/"
    click Parsing "https://github.com/thatopen/engine_web-ifc/tree/main/src/cpp/web-ifc/parsing/"
    click Geometry "https://github.com/thatopen/engine_web-ifc/tree/main/src/cpp/web-ifc/geometry/"
    click ModelMgr "https://github.com/thatopen/engine_web-ifc/blob/main/src/cpp/web-ifc/modelmanager/ModelManager.cpp"
    click ModelMgr "https://github.com/thatopen/engine_web-ifc/blob/main/src/cpp/web-ifc/modelmanager/ModelManager.h"
    click SchemaMgr "https://github.com/thatopen/engine_web-ifc/blob/main/src/cpp/web-ifc/schema/IfcSchemaManager.cpp"
    click SchemaMgr "https://github.com/thatopen/engine_web-ifc/blob/main/src/cpp/web-ifc/schema/IfcSchemaManager.h"
    click BooleanOps "https://github.com/thatopen/engine_web-ifc/tree/main/src/cpp/web-ifc/geometry/operations/boolean-utils/"
    click Core "https://github.com/thatopen/engine_web-ifc/blob/main/src/cpp/wasm/web-ifc-wasm.cpp"
    click CMake "https://github.com/thatopen/engine_web-ifc/blob/main/src/cpp/CMakeLists.txt"
    click Wrappers "https://github.com/thatopen/engine_web-ifc/blob/main/src/ts/web-ifc-api.ts"
    click ScheRetrn "https://github.com/thatopen/engine_web-ifc/blob/main/src/ts/ifc-schema.ts"
    click Docker "https://github.com/thatopen/engine_web-ifc/tree/main/Dockerfile"
    click Examples "https://github.com/thatopen/engine_web-ifc/tree/main/examples/"
    click CI "https://github.com/thatopen/engine_web-ifc/blob/main/.github/workflows/build_test.yml"
    click CI "https://github.com/thatopen/engine_web-ifc/blob/main/.github/workflows/publish.yml"

    %% Styles
    classDef build fill:#f9f,stroke:#333,stroke-width:1px
    classDef api fill:#9cf,stroke:#036,stroke-width:1px
    classDef wasm fill:#fc9,stroke:#963,stroke-width:1px
    classDef cpp fill:#cfc,stroke:#393,stroke-width:1px
    classDef consumer fill:#ffe,stroke:#993,stroke-width:1px
    classDef ci fill:#eef,stroke:#336,stroke-width:1px
    classDef artifact fill:#ddd,stroke:#666,stroke-width:1px
    classDef data fill:#dfd,stroke:#484,stroke-width:1px
```
