# qlik-oss/nebula.js architecture

> Architecture diagram of the GitHub repository qlik-oss/nebula.js, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qlik-oss/nebula.js
- Repository: https://github.com/qlik-oss/nebula.js

## Overview

NebulaJS is a collection of libraries and tools for building visualizations and integrating them into applications backed by Qlik’s Associative Engine. The principal workflow is to connect an application to an engine, define or edit visualization data properties, and expose the resulting visualization through Stardust and Nucleus UI components. Supporting branches include selection/listbox behavior, theme resolution, and property conversion. Edges are limited to README claims and relationships visible in the supplied excerpts or SOURCE INDEX; unsampled connections are omitted or dashed.

Main entry points: [`apis/supernova/src/handler/hypercube-handler.js`](https://github.com/qlik-oss/nebula.js/blob/main/apis/supernova/src/handler/hypercube-handler.js) (Visualization property API), [`apis/theme/src/index.js`](https://github.com/qlik-oss/nebula.js/blob/main/apis/theme/src/index.js) (Theme API), [`commands/serve/web/components/Hub/SelectEngine/SelectEngine.jsx`](https://github.com/qlik-oss/nebula.js/blob/main/commands/serve/web/components/Hub/SelectEngine/SelectEngine.jsx) (Engine connection UI), [`apis/supernova/src/handler/data-property-handler.js`](https://github.com/qlik-oss/nebula.js/blob/main/apis/supernova/src/handler/data-property-handler.js) (Dimension and measure properties)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Engine Integration"]
  node_connection["Engine connection UI<br/>[SelectEngine.jsx]"]
  node_connection_form["Connection form<br/>[FormManager.jsx]"]
  node_local_storage[("Browser connection storage<br/>[storage.js]")]
end

subgraph group_properties["Visualization Properties"]
  node_supernova["Visualization property API"]
  node_data_properties["Dimension and measure properties"]
  node_field_helpers["Field helpers<br/>[field-utils.js]"]
  node_cube_helpers["Hypercube helpers<br/>[hypercube-utils.js]"]
  node_conversion["Property conversion<br/>[array-util.js]"]
end

subgraph group_runtime["Visualization Runtime"]
  node_stardust["Stardust APIs<br/>[index.js]"]
  node_nucleus["Visualization components<br/>[index.js]"]
  node_onfly_model["On-the-fly list model"]
  node_session_model["Session model hook<br/>[useSessionModel.js]"]
  node_model_store["Model store hook<br/>[useModelStore.js]"]
  node_instance_context["Instance context<br/>[InstanceContext.js]"]
end

subgraph group_presentation["UI and Theming"]
  node_listbox["Listbox rendering"]
  node_listbox_selection["Listbox selections"]
  node_theme["Theme API<br/>[index.js]"]
  node_palette["Palette resolution"]
  node_style["Style resolution<br/>[style-resolver.js]"]
  node_color["Color utilities<br/>[color.js]"]
end

node_developer(("Visualization developer"))
node_engine(("Associative Engine"))

node_developer -->|"build or embed"| node_stardust
node_engine -.->|"connect through"| node_connection
node_connection -->|"renders"| node_connection_form
node_connection_form -->|"routes connection"| node_engine
node_stardust -.->|"configure properties"| node_supernova
node_supernova -->|"extends"| node_data_properties
node_supernova -->|"initializes fields"| node_field_helpers
node_supernova -->|"manages hypercube"| node_cube_helpers
node_supernova -->|"uses utilities"| node_conversion
node_data_properties -->|"uses field helpers"| node_field_helpers
node_data_properties -->|"uses cube utilities"| node_cube_helpers
node_nucleus -.->|"provides UI"| node_listbox
node_onfly_model -->|"requests model"| node_session_model
node_session_model -->|"uses stores"| node_model_store
node_model_store -->|"reads context"| node_instance_context
node_onfly_model -->|"uses defaults"| node_listbox
node_theme -->|"creates resolver"| node_palette
node_theme -->|"creates resolver"| node_style
node_theme -->|"uses color utilities"| node_color
node_connection -.->|"uses persisted state"| node_local_storage

click node_connection "https://github.com/qlik-oss/nebula.js/blob/main/commands/serve/web/components/Hub/SelectEngine/SelectEngine.jsx"
click node_connection_form "https://github.com/qlik-oss/nebula.js/blob/main/commands/serve/web/components/Hub/SelectEngine/FormManager.jsx"
click node_local_storage "https://github.com/qlik-oss/nebula.js/blob/main/commands/serve/web/storage.js"
click node_stardust "https://github.com/qlik-oss/nebula.js/blob/main/apis/stardust/src/index.js"
click node_supernova "https://github.com/qlik-oss/nebula.js/blob/main/apis/supernova/src/handler/hypercube-handler.js"
click node_data_properties "https://github.com/qlik-oss/nebula.js/blob/main/apis/supernova/src/handler/data-property-handler.js"
click node_field_helpers "https://github.com/qlik-oss/nebula.js/blob/main/apis/supernova/src/handler/utils/field-helper/field-utils.js"
click node_cube_helpers "https://github.com/qlik-oss/nebula.js/blob/main/apis/supernova/src/handler/utils/hypercube-helper/hypercube-utils.js"
click node_conversion "https://github.com/qlik-oss/nebula.js/blob/main/apis/conversion/src/array-util.js"
click node_nucleus "https://github.com/qlik-oss/nebula.js/blob/main/apis/nucleus/src/index.js"
click node_listbox "https://github.com/qlik-oss/nebula.js/blob/main/apis/nucleus/src/components/listbox/default-properties.js"
click node_listbox_selection "https://github.com/qlik-oss/nebula.js/blob/main/apis/nucleus/src/components/listbox/hooks/selections/listbox-selections.js"
click node_onfly_model "https://github.com/qlik-oss/nebula.js/blob/main/apis/nucleus/src/components/listbox/hooks/useOnTheFlyModel.jsx"
click node_session_model "https://github.com/qlik-oss/nebula.js/blob/main/apis/nucleus/src/hooks/useSessionModel.js"
click node_model_store "https://github.com/qlik-oss/nebula.js/blob/main/apis/nucleus/src/hooks/useModelStore.js"
click node_instance_context "https://github.com/qlik-oss/nebula.js/blob/main/apis/nucleus/src/contexts/InstanceContext.js"
click node_theme "https://github.com/qlik-oss/nebula.js/blob/main/apis/theme/src/index.js"
click node_palette "https://github.com/qlik-oss/nebula.js/blob/main/apis/theme/src/palette-resolver.js"
click node_style "https://github.com/qlik-oss/nebula.js/blob/main/apis/theme/src/style-resolver.js"
click node_color "https://github.com/qlik-oss/nebula.js/blob/main/apis/theme/src/utils/color/color.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_connection,node_connection_form,node_local_storage toneBlue
class node_supernova,node_data_properties,node_field_helpers,node_cube_helpers,node_conversion toneAmber
class node_stardust,node_nucleus,node_onfly_model,node_session_model,node_model_store,node_instance_context toneMint
class node_listbox,node_listbox_selection,node_theme,node_palette,node_style,node_color toneRose
class node_developer,node_engine toneIndigo
```

## Components

### Engine Integration

- [Engine connection UI](https://github.com/qlik-oss/nebula.js/blob/main/commands/serve/web/components/Hub/SelectEngine/SelectEngine.jsx): `commands/serve/web/components/Hub/SelectEngine/SelectEngine.jsx`
- [Connection form](https://github.com/qlik-oss/nebula.js/blob/main/commands/serve/web/components/Hub/SelectEngine/FormManager.jsx): `commands/serve/web/components/Hub/SelectEngine/FormManager.jsx`
- [Browser connection storage](https://github.com/qlik-oss/nebula.js/blob/main/commands/serve/web/storage.js): `commands/serve/web/storage.js`

### Visualization Properties

- [Visualization property API](https://github.com/qlik-oss/nebula.js/blob/main/apis/supernova/src/handler/hypercube-handler.js): `apis/supernova/src/handler/hypercube-handler.js`
- [Dimension and measure properties](https://github.com/qlik-oss/nebula.js/blob/main/apis/supernova/src/handler/data-property-handler.js): `apis/supernova/src/handler/data-property-handler.js`
- [Field helpers](https://github.com/qlik-oss/nebula.js/blob/main/apis/supernova/src/handler/utils/field-helper/field-utils.js): `apis/supernova/src/handler/utils/field-helper/field-utils.js`
- [Hypercube helpers](https://github.com/qlik-oss/nebula.js/blob/main/apis/supernova/src/handler/utils/hypercube-helper/hypercube-utils.js): `apis/supernova/src/handler/utils/hypercube-helper/hypercube-utils.js`
- [Property conversion](https://github.com/qlik-oss/nebula.js/blob/main/apis/conversion/src/array-util.js): `apis/conversion/src/array-util.js`

### Visualization Runtime

- [Stardust APIs](https://github.com/qlik-oss/nebula.js/blob/main/apis/stardust/src/index.js): `apis/stardust/src/index.js`
- [Visualization components](https://github.com/qlik-oss/nebula.js/blob/main/apis/nucleus/src/index.js): `apis/nucleus/src/index.js`
- [On-the-fly list model](https://github.com/qlik-oss/nebula.js/blob/main/apis/nucleus/src/components/listbox/hooks/useOnTheFlyModel.jsx): `apis/nucleus/src/components/listbox/hooks/useOnTheFlyModel.jsx`
- [Session model hook](https://github.com/qlik-oss/nebula.js/blob/main/apis/nucleus/src/hooks/useSessionModel.js): `apis/nucleus/src/hooks/useSessionModel.js`
- [Model store hook](https://github.com/qlik-oss/nebula.js/blob/main/apis/nucleus/src/hooks/useModelStore.js): `apis/nucleus/src/hooks/useModelStore.js`
- [Instance context](https://github.com/qlik-oss/nebula.js/blob/main/apis/nucleus/src/contexts/InstanceContext.js): `apis/nucleus/src/contexts/InstanceContext.js`

### UI and Theming

- [Listbox rendering](https://github.com/qlik-oss/nebula.js/blob/main/apis/nucleus/src/components/listbox/default-properties.js): `apis/nucleus/src/components/listbox/default-properties.js`
- [Listbox selections](https://github.com/qlik-oss/nebula.js/blob/main/apis/nucleus/src/components/listbox/hooks/selections/listbox-selections.js): `apis/nucleus/src/components/listbox/hooks/selections/listbox-selections.js`
- [Theme API](https://github.com/qlik-oss/nebula.js/blob/main/apis/theme/src/index.js): `apis/theme/src/index.js`
- [Palette resolution](https://github.com/qlik-oss/nebula.js/blob/main/apis/theme/src/palette-resolver.js): `apis/theme/src/palette-resolver.js`
- [Style resolution](https://github.com/qlik-oss/nebula.js/blob/main/apis/theme/src/style-resolver.js): `apis/theme/src/style-resolver.js`
- [Color utilities](https://github.com/qlik-oss/nebula.js/blob/main/apis/theme/src/utils/color/color.js): `apis/theme/src/utils/color/color.js`

### Other components

- **Visualization developer**
- **Associative Engine**

## Connections

- Visualization developer → Stardust APIs: build or embed
- Associative Engine → Engine connection UI: connect through
- Engine connection UI → Connection form: renders (evidence: `commands/serve/web/components/Hub/SelectEngine/SelectEngine.jsx`)
- Connection form → Associative Engine: routes connection (evidence: `commands/serve/web/components/Hub/SelectEngine/FormManager.jsx`)
- Stardust APIs → Visualization property API: configure properties
- Visualization property API → Dimension and measure properties: extends (evidence: `apis/supernova/src/handler/hypercube-handler.js`)
- Visualization property API → Field helpers: initializes fields (evidence: `apis/supernova/src/handler/hypercube-handler.js`)
- Visualization property API → Hypercube helpers: manages hypercube (evidence: `apis/supernova/src/handler/hypercube-handler.js`)
- Visualization property API → Property conversion: uses utilities (evidence: `apis/supernova/src/handler/hypercube-handler.js`)
- Dimension and measure properties → Field helpers: uses field helpers (evidence: `apis/supernova/src/handler/data-property-handler.js`)
- Dimension and measure properties → Hypercube helpers: uses cube utilities (evidence: `apis/supernova/src/handler/data-property-handler.js`)
- Visualization components → Listbox rendering: provides UI
- On-the-fly list model → Session model hook: requests model (evidence: `apis/nucleus/src/components/listbox/hooks/useOnTheFlyModel.jsx`)
- Session model hook → Model store hook: uses stores (evidence: `apis/nucleus/src/hooks/useSessionModel.js`)
- Model store hook → Instance context: reads context (evidence: `apis/nucleus/src/hooks/useModelStore.js`)
- On-the-fly list model → Listbox rendering: uses defaults (evidence: `apis/nucleus/src/components/listbox/hooks/useOnTheFlyModel.jsx`)
- Theme API → Palette resolution: creates resolver (evidence: `apis/theme/src/index.js`)
- Theme API → Style resolution: creates resolver (evidence: `apis/theme/src/index.js`)
- Theme API → Color utilities: uses color utilities (evidence: `apis/theme/src/index.js`)
- Engine connection UI → Browser connection storage: uses persisted state
