# nicolaskruchten/pivottable architecture

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

- Interactive diagram: https://gitdiagram.com/nicolaskruchten/pivottable
- Repository: https://github.com/nicolaskruchten/pivottable

## Overview

##### Main components
- External Dependencies – Include jQuery (mandatory), jQueryUI (for interactive drag-and-drop), and optionally charting libraries (D3.js, C3.js, Google Charts, Plotly).
- PivotTable Core Engine – The central logic (written in CoffeeScript and later compiled) that handles data transformation, aggregation, and pivot table generation. This includes both the non-UI version (pivot()) and the UI-enhanced version (pivotUI()).
- UI Layer – This component wraps around the core engine and uses jQueryUI to implement the drag-and-drop interface, enabling users to build and manipulate the pivot table.
- Renderer Modules – Separate renderer plugins that convert summary data into different visual formats. For example, dedicated modules exist for c3_renderers, d3_renderers, export_renderers, gchart_renderers, and plotly_renderers. This layered approach also makes it easy for developers to add more renderers.
- Localization and Configuration – Modules located in the locales folder that provide different language translations and configuration settings.
- Build and Testing Infrastructure – Represented by files like gulpFile.js, composer.json, package.json, and the tests/ directory. This component addresses the build process (CoffeeScript compilation and minification) and automated tests (using Jasmine in tests/).

##### Relationships and interactions between components
- The client application (or the consuming code in an example HTML file) first loads external dependencies (jQuery, jQueryUI, and optionally chart libraries).
- The compiled PivotTable.js (taken from the dist folder) is then loaded.
- The core engine (pivot and pivotUI functions) processes raw data provided by the user and interacts with the UI Layer when pivotUI is used.
- The UI layer listens for drag-and-drop events (powered by jQueryUI) and passes configuration changes back to the core engine, which re-aggregates data accordingly.
- When rendering is required in chart formats, calls are made from the core engine to the appropriate renderer module.
- The localization modules are used throughout the UI to render language-specific messages.
- During development, the build system (gulp, invoked via gulpFile.js) watches changes in the src files, compiles them to the dist folder, and then the test suite (in tests/) validates functionality.

##### Architectural patterns and design principles
- Modular Design: The separation of the core pivot table logic, UI controls, and rendering plugins facilitates extensibility (for instance, adding new renderers or aggregation functions).
- UMD Pattern: The library follows the Universal Module Definition, making it compatible with various script loaders (AMD, CommonJS, direct browser inclusion).
- Layered Architecture: A clear distinction between core data processing (aggregation, transformation) and user interface (drag-and-drop, localization) simplifies maintenance and enhances reusability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime Environment
    subgraph "Runtime Environment"
        %% External Dependencies Subgraph
        subgraph "External Dependencies"
            jQuery["jQuery"]:::external
            jQueryUI["jQueryUI"]:::external
            ChartLib["Chart Libraries (D3.js, C3.js, GoogleCharts, Plotly)"]:::external
        end

        %% PivotTable Core Engine Node (Source and Compiled)
        CoreSrc["PivotTable Core Engine (Source)"]:::core
        CoreCompiled["PivotTable Core Engine (Compiled)"]:::core

        %% UI Layer
        UI["UI Layer (Drag'n'Drop & Config)"]:::ui
        UIDemo["UI Demo"]:::ui

        %% Renderer Modules Subgraph
        subgraph "Renderer Modules"
            c3R["c3 Renderer"]:::render
            d3R["d3 Renderer"]:::render
            expR["Export Renderer"]:::render
            gchartR["Google Chart Renderer"]:::render
            plotlyR["Plotly Renderer"]:::render
        end

        %% Localization Module
        Locale["Localization Module (Locales)"]:::locale

        %% Interactions in Runtime
        jQuery -->|"Enables DOM manipulation"| UI
        jQueryUI -->|"Provides drag'n'drop"| UI
        ChartLib ---|"Optional rendering support"| c3R
        ChartLib --- d3R
        ChartLib --- gchartR
        ChartLib --- plotlyR

        CoreCompiled -->|"Handles pivot()/pivotUI()"| UI
        UI -->|"Triggers recalculation"| CoreCompiled
        CoreCompiled -->|"Calls renderers"| c3R
        CoreCompiled --> d3R
        CoreCompiled --> expR
        CoreCompiled --> gchartR
        CoreCompiled --> plotlyR
        UI -->|"Loads localized messages"| Locale
    end

    %% Development & Build Environment
    subgraph "Development Environment"
        Build["Build System"]:::dev
        DepMgmt["Dependency Management"]:::dev
        Tests["Automated Tests"]:::dev
        CoreSrc -->|"Compiled to"| CoreCompiled
    end

    %% External flow from User Application
    UIDemo -->|"Integrates library"| CoreCompiled

    %% Click Events
    click CoreSrc "https://github.com/nicolaskruchten/pivottable/blob/master/src/pivot.coffee"
    click CoreCompiled "https://github.com/nicolaskruchten/pivottable/blob/master/dist/pivot.js"
    click UIDemo "https://github.com/nicolaskruchten/pivottable/blob/master/examples/simple_ui.html"
    click c3R "https://github.com/nicolaskruchten/pivottable/blob/master/src/c3_renderers.coffee"
    click d3R "https://github.com/nicolaskruchten/pivottable/blob/master/src/d3_renderers.coffee"
    click expR "https://github.com/nicolaskruchten/pivottable/blob/master/src/export_renderers.coffee"
    click gchartR "https://github.com/nicolaskruchten/pivottable/blob/master/src/gchart_renderers.coffee"
    click plotlyR "https://github.com/nicolaskruchten/pivottable/blob/master/src/plotly_renderers.coffee"
    click Locale "https://github.com/nicolaskruchten/pivottable/tree/master/locales/"
    click Build "https://github.com/nicolaskruchten/pivottable/blob/master/gulpFile.js"
    click DepMgmt "https://github.com/nicolaskruchten/pivottable/blob/master/package.json"
    click Tests "https://github.com/nicolaskruchten/pivottable/tree/master/tests/"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:2px;
    classDef core fill:#ccf,stroke:#333,stroke-width:2px;
    classDef ui fill:#cff,stroke:#333,stroke-width:2px;
    classDef render fill:#cfc,stroke:#333,stroke-width:2px;
    classDef locale fill:#fcf,stroke:#333,stroke-width:2px;
    classDef dev fill:#ffc,stroke:#333,stroke-width:2px;
```
