# deneb-viz/deneb architecture

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

- Interactive diagram: https://gitdiagram.com/deneb-viz/deneb
- Repository: https://github.com/deneb-viz/deneb

## Overview

##### Project type and purpose
- This is a monorepo for an open-source Power BI custom visual (“Deneb”) that uses the Vega/Vega-Lite grammar to render declarative charts inside Power BI.
- It bundles multiple npm packages (core utilities, JSON processors, ESLint configs, TypeScript configs, Web Worker helpers, a Monaco JSON editor integration, and the Power BI integration layer) and a React/TypeScript front-end visual.

##### Top-level components in the file tree
- Monorepo orchestrator (turbo.json, package.json, config/, bin/, scripts)
- `packages/…` workspace packages:
- core-dependencies: shared types, constants, utilities
- integration-powerbi: glue to Power BI host APIs, property pane settings, field tracking
- json-processing: dataset & spec validation, formatting logic
- monaco-custom: JSON editor worker + integration
- template-usermeta-schema: schema generator
- worker-common, worker-dataset-viewer, worker-spec-json-processing: Web Worker bundles for dataset viewing & Vega spec processing
- jest-presets, eslint-config, typescript-config: developer tooling
- Visual project in `src/…`: entrypoint (Deneb.ts), React UI, feature modules, state store, core services, utils

##### External dependencies
- Power BI host (pbiviz.json defines manifests)
- Vega & Vega-Lite libraries (npm, loaded in plugin)
- Monaco Editor (JSON editing)
- Web Workers (in-browser parallel processing)

##### Architectural patterns & data flow
- Monorepo / package-per-concern: each package publishes a narrowly scoped library
- Flux/Redux-style store under `src/store/…` for application state
- Feature modules (in `src/features/…`) that connect UI components (React) to the store and core services
- Web Worker model: heavy tasks (dataset transforms, spec tokenization, remapping, JSON validation) run off the UI thread
- Host integration: `integration-powerbi` layer exposes Power BI property pane & dataView API, forwards data to core services
- Vega rendering: processed Vega JSON is fed into `vega-embed`/runtime in `src/features/vega-output` and rendered in a React container

##### Capturing essential architectural elements
- Don’t overcomplicate – group related sub-packages into a single “Shared Libraries” cluster, and group feature folders under “UI & Features.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems" 
        direction TB
        PBHost["Power BI Host"]:::external
        VegaLib["Vega/Vega-Lite"]:::external
        MonacoAPI["Monaco Editor API"]:::external
    end

    %% Monorepo Build & Tooling
    subgraph "Monorepo Build & Tooling" 
        direction TB
        Turbo["Turbo (turbo.json)"]:::build
        PNPM["package.json"]:::build
        BinScripts["bin scripts"]:::build
        ConfigFiles["config files"]:::build
        ESLintCfg["eslint.config.mjs"]:::build
        JestPresets["jest-presets"]:::build
        ESLintPkg["eslint-config"]:::build
        TSConfigPkg["typescript-config"]:::build
    end

    %% Shared Libraries
    subgraph "Shared Libraries" 
        direction TB
        CoreDeps["core-dependencies"]:::shared
        JSONProc["json-processing"]:::shared
        UserMeta["template-usermeta-schema"]:::shared
        WorkerCommon["worker-common"]:::shared
    end

    %% Integration Layer
    subgraph "Integration Layer" 
        direction TB
        PowerBIInt["integration-powerbi"]:::integration
        MonacoInt["monaco-custom"]:::integration
    end

    %% Web Workers
    subgraph "Web Workers" 
        direction TB
        WorkerData["worker-dataset-viewer"]:::worker
        WorkerSpec["worker-spec-json-processing"]:::worker
    end

    %% Plugin Front-End
    subgraph "Plugin Front-End" 
        direction TB
        Entry["Deneb.ts (entry)"]:::ui
        Components["React Components"]:::ui
        CoreServices["Core Services"]:::ui
        Features["Feature Modules"]:::ui
        Store["State Store"]:::ui
        Constants["Shared Constants"]:::ui
        Utils["Utility Functions"]:::ui
        Manifest["pbiviz.json"]:::ui
        VegaOutput["Vega Runtime & Renderer"]:::ui
    end

    %% Build flow
    Developer["Developer"]:::external -->|invokes| Turbo
    Turbo -->|builds packages| CoreDeps
    Turbo --> JSONProc
    Turbo --> UserMeta
    Turbo --> WorkerCommon
    Turbo --> PowerBIInt
    Turbo --> MonacoInt
    Turbo --> WorkerData
    Turbo --> WorkerSpec
    Turbo --> JestPresets
    Turbo --> ESLintPkg
    Turbo --> TSConfigPkg
    Turbo -->|bundles plugin| Entry

    %% Host load
    PBHost -->|loads plugin via pbiviz.json| Manifest
    Manifest --> PowerBIInt

    %% Data flow
    PowerBIInt -->|forwards DataView| CoreServices
    CoreServices -->|dispatch| Store
    Store -->|connect| Features
    Features -->|render UI| Components

    %% UI actions
    Components -->|dispatch actions| Store

    %% Worker offload
    Store -->|postMessage→dataset| WorkerData
    Store -->|postMessage→spec| WorkerSpec
    WorkerData -->|message→results| Store
    WorkerSpec -->|message→results| Store

    %% Vega rendering
    Store -->|spec JSON| VegaOutput
    VegaOutput -->|render call| Components

    %% Monaco editor integration
    MonacoAPI --> MonacoInt
    MonacoInt -->|mounts editor| Components
    Components -->|dispatch edits| Store

    %% External libs usage
    VegaLib --> VegaOutput

    %% Click Events
    click Turbo "https://github.com/deneb-viz/deneb/blob/main/turbo.json"
    click PNPM "https://github.com/deneb-viz/deneb/blob/main/package.json"
    click BinScripts "https://github.com/deneb-viz/deneb/blob/main/bin/package-custom.ts"
    click ESLintCfg "https://github.com/deneb-viz/deneb/blob/main/bin/validate-config-for-commit.ts"
    click ConfigFiles "https://github.com/deneb-viz/deneb/blob/main/config/index.ts"
    click ConfigFiles "https://github.com/deneb-viz/deneb/blob/main/config/features.json"
    click ConfigFiles "https://github.com/deneb-viz/deneb/blob/main/config/package-custom.json"
    click ESLintCfg "https://github.com/deneb-viz/deneb/blob/main/eslint.config.mjs"
    click JestPresets "https://github.com/deneb-viz/deneb/tree/main/packages/jest-presets"
    click ESLintPkg "https://github.com/deneb-viz/deneb/tree/main/packages/eslint-config"
    click TSConfigPkg "https://github.com/deneb-viz/deneb/tree/main/packages/typescript-config"
    click CoreDeps "https://github.com/deneb-viz/deneb/tree/main/packages/core-dependencies"
    click JSONProc "https://github.com/deneb-viz/deneb/tree/main/packages/json-processing"
    click UserMeta "https://github.com/deneb-viz/deneb/tree/main/packages/template-usermeta-schema"
    click WorkerCommon "https://github.com/deneb-viz/deneb/tree/main/packages/worker-common"
    click PowerBIInt "https://github.com/deneb-viz/deneb/tree/main/packages/integration-powerbi"
    click MonacoInt "https://github.com/deneb-viz/deneb/tree/main/packages/monaco-custom"
    click WorkerData "https://github.com/deneb-viz/deneb/tree/main/packages/worker-dataset-viewer"
    click WorkerSpec "https://github.com/deneb-viz/deneb/tree/main/packages/worker-spec-json-processing"
    click Entry "https://github.com/deneb-viz/deneb/blob/main/src/Deneb.ts"
    click Components "https://github.com/deneb-viz/deneb/tree/main/src/components/"
    click CoreServices "https://github.com/deneb-viz/deneb/tree/main/src/core/"
    click Store "https://github.com/deneb-viz/deneb/tree/main/src/store/"
    click Constants "https://github.com/deneb-viz/deneb/tree/main/src/constants/"
    click Utils "https://github.com/deneb-viz/deneb/tree/main/src/utils/"
    click Manifest "https://github.com/deneb-viz/deneb/blob/main/pbiviz.json"

    %% Styles
    classDef build fill:#cccccc,stroke:#333,stroke-width:1px
    classDef shared fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef integration fill:#90EE90,stroke:#333,stroke-width:1px
    classDef worker fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef ui fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#ffffff,stroke:#666,stroke-dasharray: 5 5,stroke-width:1px
```
