# kovacsv/online3dviewer architecture

> Architecture diagram of the GitHub repository kovacsv/online3dviewer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kovacsv/online3dviewer
- Repository: https://github.com/kovacsv/online3dviewer

## Overview

#### Purpose and Deliverables
Online 3D Viewer is a browser-based 3D model viewer and reusable JavaScript library. It imports many CAD/mesh formats, builds a normalized model representation, renders and explores it in the browser, and exports selected formats. The deployable site is rooted at `website/index.html`; the reusable engine’s public aggregation point is `source/engine/main.js`.

#### Entry Points and Product Layers
The website application boots through `source/website/index.js` and coordinates UI/application state in `source/website/website.js`. Embeddable integrations are a distinct surface via `source/website/embed.js` and engine viewer API `source/engine/viewer/embeddedviewer.js`. Static deployment assets and sample models reside under `website/`.

#### Import Pipeline
`source/engine/import/importer.js` selects format-specific importers and manages import flow; `source/engine/import/importerfiles.js` handles file sets and related resources. Individual parsers, such as `source/engine/import/importergltf.js`, `source/engine/import/importerifc.js`, and `source/engine/import/importerocct.js`, form the format boundary. Input can originate from local files, URLs, archives, and dependent files; importers resolve these before producing the common model.

#### Canonical Model and Geometry
The engine isolates format parsing from rendering through its internal scene/model representation: `source/engine/model/model.js`, `source/engine/model/mesh.js`, and `source/engine/model/node.js`. Meshes, materials, instances, properties, topology, and transforms are normalized here. Foundational math and spatial operations are under `source/engine/geometry/`, including `source/engine/geometry/transformation.js` and `source/engine/geometry/octree.js`. `source/engine/model/modelfinalization.js` is the likely post-import boundary for making models renderable and queryable.

#### Rendering and Interaction
`source/engine/threejs/threeconverter.js` bridges the canonical model into Three.js objects; `source/engine/threejs/threemodelloader.js` loads that converted scene. Rendering state and interaction are owned by `source/engine/viewer/viewer.js`, `source/engine/viewer/viewermodel.js`, `source/engine/viewer/camera.js`, and `source/engine/viewer/navigation.js`. This separates browser/WebGL rendering from file-format and model logic.

#### Website UI Orchestration
The application UI wraps the engine viewer with loading, navigation, inspection, settings, sharing, snapshots, and export. The central model-loading UI adapter is `source/website/threemodelloaderui.js`; hierarchical model/material/mesh browsing is split across `source/website/navigator.js`, `source/website/navigatoritems.js`, and panel modules. URL hash state is managed at `source/website/hashhandler.js`, enabling URL-based model loading and shareable views.

#### Export and External Runtime Boundaries
`source/engine/export/exporter.js` dispatches export, while `source/engine/export/exportermodel.js` serializes the canonical model through format exporters such as `source/engine/export/exportergltf.js` and `source/engine/export/exporterobj.js`. Browser-oriented binary/text/file utilities are centralized in `source/engine/io/`. Material external dependencies include Three.js for rendering; fflate/Draco for compressed assets; rhino3dm, web-ifc, and occt-import-js for specialized CAD imports. The project is Node/npm-built and published, with CI/release workflows in `.github/workflows/`.

Main entry points: [`source/website/website.js`](https://github.com/kovacsv/online3dviewer/blob/master/source/website/website.js) (Website coordinator), [`source/engine/import/importer.js`](https://github.com/kovacsv/online3dviewer/blob/master/source/engine/import/importer.js) (Import dispatcher), [`source/engine/model/model.js`](https://github.com/kovacsv/online3dviewer/blob/master/source/engine/model/model.js) (Canonical model), [`source/engine/main.js`](https://github.com/kovacsv/online3dviewer/blob/master/source/engine/main.js) (Engine public API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_website["Website App"]
  node_site["Deployable site<br/>static site<br/>[index.html]"]
  node_website_boot["Website bootstrap<br/>browser entry<br/>[index.js]"]
  node_website_app["Website coordinator<br/>application state<br/>[website.js]"]
  node_loader_ui["Model loader UI<br/>UI adapter"]
  node_navigator["Model navigator<br/>inspection UI<br/>[navigator.js]"]
  node_hash["URL hash state<br/>share state<br/>[hashhandler.js]"]
  node_embed["Embed API<br/>browser entry<br/>[embed.js]"]
end

subgraph group_import["Import Pipeline"]
  node_importer["Import dispatcher<br/>import orchestration<br/>[importer.js]"]
  node_import_files["File-set resolver<br/>resource resolution<br/>[importerfiles.js]"]
  node_format_importers["Format parsers<br/>format boundary<br/>[importergltf.js]"]
end

subgraph group_model["Model &amp; Geometry"]
  node_model[("Canonical model<br/>scene model<br/>[model.js]")]
  node_finalization["Model finalization<br/>post-import processing"]
  node_geometry["Geometry &amp; spatial ops<br/>math layer"]
end

subgraph group_render["Viewer &amp; Rendering"]
  node_engine_api["Engine public API<br/>library entry<br/>[main.js]"]
  node_converter["Three.js converter<br/>render bridge<br/>[threeconverter.js]"]
  node_viewer["Viewer runtime<br/>WebGL interaction<br/>[viewer.js]"]
  node_embedded_viewer["Embedded viewer<br/>viewer API<br/>[embeddedviewer.js]"]
end

subgraph group_export["Export Pipeline"]
  node_exporter["Export dispatcher<br/>export orchestration<br/>[exporter.js]"]
  node_export_model["Model serializer<br/>format serialization<br/>[exportermodel.js]"]
end

subgraph group_external["External Boundaries"]
  node_io["Browser I/O<br/>file utilities"]
  node_threejs["Three.js<br/>render dependency"]
  node_cad_runtimes["CAD import runtimes<br/>import dependencies"]
end

node_site -->|"loads"| node_website_boot
node_website_boot -->|"boots"| node_website_app
node_website_app -->|"uses"| node_loader_ui
node_website_app -->|"drives"| node_navigator
node_website_app -->|"syncs"| node_hash
node_hash -->|"URL model load"| node_loader_ui
node_loader_ui -->|"imports"| node_importer
node_embed -->|"creates"| node_embedded_viewer
node_engine_api -->|"exports"| node_importer
node_engine_api -->|"exports"| node_embedded_viewer
node_engine_api -->|"exports"| node_exporter
node_importer -->|"resolves inputs"| node_import_files
node_importer -->|"dispatches"| node_format_importers
node_import_files -->|"reads resources"| node_io
node_format_importers -->|"uses"| node_cad_runtimes
node_format_importers -->|"produces"| node_model
node_model -->|"post-processes"| node_finalization
node_geometry -->|"supports"| node_finalization
node_finalization -->|"supplies"| node_converter
node_converter -->|"creates objects for"| node_threejs
node_converter -->|"loads scene"| node_viewer
node_viewer -->|"renders with"| node_threejs
node_website_app -->|"controls"| node_viewer
node_navigator -.->|"inspects"| node_model
node_exporter -->|"dispatches"| node_export_model
node_export_model -->|"serializes"| node_model

click node_site "https://github.com/kovacsv/online3dviewer/blob/master/website/index.html"
click node_website_boot "https://github.com/kovacsv/online3dviewer/blob/master/source/website/index.js"
click node_website_app "https://github.com/kovacsv/online3dviewer/blob/master/source/website/website.js"
click node_loader_ui "https://github.com/kovacsv/online3dviewer/blob/master/source/website/threemodelloaderui.js"
click node_navigator "https://github.com/kovacsv/online3dviewer/blob/master/source/website/navigator.js"
click node_hash "https://github.com/kovacsv/online3dviewer/blob/master/source/website/hashhandler.js"
click node_embed "https://github.com/kovacsv/online3dviewer/blob/master/source/website/embed.js"
click node_engine_api "https://github.com/kovacsv/online3dviewer/blob/master/source/engine/main.js"
click node_importer "https://github.com/kovacsv/online3dviewer/blob/master/source/engine/import/importer.js"
click node_import_files "https://github.com/kovacsv/online3dviewer/blob/master/source/engine/import/importerfiles.js"
click node_format_importers "https://github.com/kovacsv/online3dviewer/blob/master/source/engine/import/importergltf.js"
click node_model "https://github.com/kovacsv/online3dviewer/blob/master/source/engine/model/model.js"
click node_finalization "https://github.com/kovacsv/online3dviewer/blob/master/source/engine/model/modelfinalization.js"
click node_converter "https://github.com/kovacsv/online3dviewer/blob/master/source/engine/threejs/threeconverter.js"
click node_viewer "https://github.com/kovacsv/online3dviewer/blob/master/source/engine/viewer/viewer.js"
click node_embedded_viewer "https://github.com/kovacsv/online3dviewer/blob/master/source/engine/viewer/embeddedviewer.js"
click node_exporter "https://github.com/kovacsv/online3dviewer/blob/master/source/engine/export/exporter.js"
click node_export_model "https://github.com/kovacsv/online3dviewer/blob/master/source/engine/export/exportermodel.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_site,node_website_boot,node_website_app,node_loader_ui,node_navigator,node_hash,node_embed toneBlue
class node_importer,node_import_files,node_format_importers toneAmber
class node_model,node_finalization,node_geometry toneMint
class node_engine_api,node_converter,node_viewer,node_embedded_viewer toneRose
class node_exporter,node_export_model toneIndigo
class node_io,node_threejs,node_cad_runtimes toneTeal
```

## Components

### Website App

Browser-facing application and embed surface.

- [Deployable site](https://github.com/kovacsv/online3dviewer/blob/master/website/index.html): static site · Hosts the viewer and sample assets. · `website/index.html`
- [Website bootstrap](https://github.com/kovacsv/online3dviewer/blob/master/source/website/index.js): browser entry · `source/website/index.js`
- [Website coordinator](https://github.com/kovacsv/online3dviewer/blob/master/source/website/website.js): application state · Coordinates UI state and viewer workflows. · `source/website/website.js`
- [Model loader UI](https://github.com/kovacsv/online3dviewer/blob/master/source/website/threemodelloaderui.js): UI adapter · Connects loading progress and results to the application. · `source/website/threemodelloaderui.js`
- [Model navigator](https://github.com/kovacsv/online3dviewer/blob/master/source/website/navigator.js): inspection UI · Browses model, material, and mesh hierarchy. · `source/website/navigator.js`
- [URL hash state](https://github.com/kovacsv/online3dviewer/blob/master/source/website/hashhandler.js): share state · Loads models and views from shareable URLs. · `source/website/hashhandler.js`
- [Embed API](https://github.com/kovacsv/online3dviewer/blob/master/source/website/embed.js): browser entry · `source/website/embed.js`

### Import Pipeline

Format ingestion and resource resolution.

- [Import dispatcher](https://github.com/kovacsv/online3dviewer/blob/master/source/engine/import/importer.js): import orchestration · Selects importers and manages import flow. · `source/engine/import/importer.js`
- [File-set resolver](https://github.com/kovacsv/online3dviewer/blob/master/source/engine/import/importerfiles.js): resource resolution · Resolves dependent files and related resources. · `source/engine/import/importerfiles.js`
- [Format parsers](https://github.com/kovacsv/online3dviewer/blob/master/source/engine/import/importergltf.js): format boundary · Includes glTF, IFC, OCCT, and other format importers. · `source/engine/import/importergltf.js`

### Model & Geometry

Normalized engine representation.

- [Canonical model](https://github.com/kovacsv/online3dviewer/blob/master/source/engine/model/model.js): scene model · Normalizes meshes, materials, instances, properties, and transforms. · `source/engine/model/model.js`
- [Model finalization](https://github.com/kovacsv/online3dviewer/blob/master/source/engine/model/modelfinalization.js): post-import processing · Makes imported models renderable and queryable. · `source/engine/model/modelfinalization.js`
- **Geometry & spatial ops**: math layer · Provides transformations and octree-based spatial operations.

### Viewer & Rendering

Three.js conversion, rendering, and interaction.

- [Engine public API](https://github.com/kovacsv/online3dviewer/blob/master/source/engine/main.js): library entry · `source/engine/main.js`
- [Three.js converter](https://github.com/kovacsv/online3dviewer/blob/master/source/engine/threejs/threeconverter.js): render bridge · Converts the canonical model into Three.js objects. · `source/engine/threejs/threeconverter.js`
- [Viewer runtime](https://github.com/kovacsv/online3dviewer/blob/master/source/engine/viewer/viewer.js): WebGL interaction · Owns rendering state, camera, navigation, and viewer model. · `source/engine/viewer/viewer.js`
- [Embedded viewer](https://github.com/kovacsv/online3dviewer/blob/master/source/engine/viewer/embeddedviewer.js): viewer API · `source/engine/viewer/embeddedviewer.js`

### Export Pipeline

Canonical-model serialization.

- [Export dispatcher](https://github.com/kovacsv/online3dviewer/blob/master/source/engine/export/exporter.js): export orchestration · `source/engine/export/exporter.js`
- [Model serializer](https://github.com/kovacsv/online3dviewer/blob/master/source/engine/export/exportermodel.js): format serialization · Serializes canonical models through glTF, OBJ, and other exporters. · `source/engine/export/exportermodel.js`

### External Boundaries

- **Browser I/O**: file utilities · Centralizes browser binary, text, and file handling.
- **Three.js**: render dependency
- **CAD import runtimes**: import dependencies · rhino3dm, web-ifc, and occt-import-js support specialized imports.

## Connections

- Deployable site → Website bootstrap: loads
- Website bootstrap → Website coordinator: boots
- Website coordinator → Model loader UI: uses
- Website coordinator → Model navigator: drives
- Website coordinator → URL hash state: syncs
- URL hash state → Model loader UI: URL model load
- Model loader UI → Import dispatcher: imports
- Embed API → Embedded viewer: creates
- Engine public API → Import dispatcher: exports
- Engine public API → Embedded viewer: exports
- Engine public API → Export dispatcher: exports
- Import dispatcher → File-set resolver: resolves inputs
- Import dispatcher → Format parsers: dispatches
- File-set resolver → Browser I/O: reads resources
- Format parsers → CAD import runtimes: uses
- Format parsers → Canonical model: produces
- Canonical model → Model finalization: post-processes
- Geometry & spatial ops → Model finalization: supports
- Model finalization → Three.js converter: supplies
- Three.js converter → Three.js: creates objects for
- Three.js converter → Viewer runtime: loads scene
- Viewer runtime → Three.js: renders with
- Website coordinator → Viewer runtime: controls
- Model navigator → Canonical model: inspects
- Export dispatcher → Model serializer: dispatches
- Model serializer → Canonical model: serializes
