# vega/vega-lite architecture

> Architecture diagram of the GitHub repository vega/vega-lite, 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/vega/vega-lite
- Repository: https://github.com/vega/vega-lite

## Overview

##### Main Components
- Input Interface / CLI – This is represented by the commands in the “bin” directory (e.g., vl2pdf, vl2png, etc.) and likely other wrappers (scripts, package.json scripts) that accept Vega-Lite specifications.
- Specification Parser and Validator – The library begins by accepting a user-provided Vega-Lite spec. This component is responsible for parsing, validating, and possibly providing initial error handling (check files in “src/spec” and “src/normalize”).
- Normalization Engine – Located in the “src/normalize” folder, this module ensures that the input spec follows a canonical structure and deals with any implicit defaults or composition rules.
– Data Handling (src/compile/data/*): Aggregation, binning, filtering, imputation, etc.
– Mark Encoding (src/compile/mark): Conversion for different mark types (bar, line, point, area, etc.).
– Scale, Projection, and Selection – These components (found in their respective folders) build the mapping from data to visual channels, handle spatial projection rules, and process user selections.
– Final Assembly / Code Generation (e.g., src/compile/compile.ts, src/compile/unit.ts, src/compile/signal.ts): This component pulls together the output from the modules above into a complete, valid Vega specification.
- Utility and Helper Modules – Files like “src/util.ts” and “src/log” provide supportive functionality (error logging, common utility functions) across the system.
- Testing and Continuous Integration – A large number of tests exist under “test” and “test-runtime” folders, ensuring each module’s behavior is consistent. Although not part of the production runtime per se, these encapsulate an important architecture aspect (robustness and validation).
- Website and Documentation – The “site” directory handles documentation, examples, and the online demos that demonstrate how Vega-Lite operates. It represents the integration with external user-facing environments.

##### Relationships and Data Flow
– The process starts with the user’s input (a Vega-Lite specification) via the CLI or programmatic interface.
– The Parser/Validator reads the input and hands off a cleaned spec to the Normalizer.
– The Normalization Engine processes the spec into a canonical form, and passes it to the Compiler.
– The outputs from each compilation module are then assembled into a complete Vega spec.
– The final output is provided back to the user (or further rendered) by one of the conversion utilities (e.g., in the “bin” folder).

##### Architectural Patterns and Design Principles
– Layered Compilation Pipeline: The architecture follows a pipeline (input → parse → normalize → compile → output). This clear stage separation is essential for understanding the transformation process.
– Separation of Concerns: There is a clear separation between user-facing utilities (CLI, examples, website) and the core engine (normalization and compilation). This promotes extensibility and independent testing.

##### Relevant Technologies and Frameworks
– The project is developed in TypeScript/JavaScript.
– Build tools include Rollup (see rollup.config.js) and scripts under the “scripts” folder for builds and deployment.
– GitHub Actions workflows, as seen in the “.github/workflows” directory, ensure CI/CD and continuous validation of the builds/test suite.

##### Instructing the Principal Software Engineer
– Highlight any error-handling or validation routes (e.g., if an invalid spec is detected, route flows to error modules in “src/compile/invalid”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["User's Vega-Lite Specification"]:::input
    B["Input Interface / CLI"]:::cli
    C["Specification Parser/Validator"]:::parser
    D["Normalization Engine"]:::norm
    E["Compiler & Assembly Modules"]:::comp
    F["General Compilation (Code Generation)"]:::comp2
    G["Data Handling Module"]:::comp2
    H["Axis Module"]:::comp2
    I["Legend Module"]:::comp2
    J["Header Module"]:::comp2
    K["Mark Encoding Module"]:::comp2
    L["Scale Module"]:::comp2
    M["Projection Module"]:::comp2
    N["Selection Module"]:::comp2
    X["Compiled Modules Consolidation"]:::comp2
    O["Final Vega Specification"]:::final
    U["Utility & Helper Modules"]:::util
    T["Testing & CI"]:::test
    R["Website & Documentation"]:::docs

    A --> B
    B --> C
    C --> D
    D --> E

    E --> F
    E --> G
    E --> H
    E --> I
    E --> J
    E --> K
    E --> L
    E --> M
    E --> N

    F --> X
    G --> X
    H --> X
    I --> X
    J --> X
    K --> X
    L --> X
    M --> X
    N --> X

    X --> O

    %% Utility support from core modules
    C ---|utilize| U
    D ---|utilize| U
    E ---|utilize| U

    %% Testing and Documentation integration
    O ---|validated_by| T
    O ---|published_to| R

    %% Click Events
    click B "https://github.com/vega/vega-lite/tree/main/bin"
    click C "https://github.com/vega/vega-lite/blob/main/src/spec/index.ts"
    click D "https://github.com/vega/vega-lite/blob/main/src/normalize/index.ts"
    click E "https://github.com/vega/vega-lite/blob/main/src/compile/unit.ts"
    click F "https://github.com/vega/vega-lite/blob/main/src/compile/compile.ts"
    click G "https://github.com/vega/vega-lite/tree/main/src/compile/data"
    click H "https://github.com/vega/vega-lite/tree/main/src/compile/axis"
    click I "https://github.com/vega/vega-lite/tree/main/src/compile/legend"
    click J "https://github.com/vega/vega-lite/tree/main/src/compile/header"
    click K "https://github.com/vega/vega-lite/tree/main/src/compile/mark"
    click L "https://github.com/vega/vega-lite/tree/main/src/compile/scale"
    click M "https://github.com/vega/vega-lite/tree/main/src/compile/projection"
    click N "https://github.com/vega/vega-lite/tree/main/src/compile/selection"
    click U "https://github.com/vega/vega-lite/blob/main/src/util.ts"
    click T "https://github.com/vega/vega-lite/tree/main/test"
    click R "https://github.com/vega/vega-lite/tree/main/site"

    %% Styles
    classDef input fill:#ffffff,stroke:#000,stroke-width:2px
    classDef cli fill:#ffcc00,stroke:#333,stroke-width:2px
    classDef parser fill:#ccffcc,stroke:#333,stroke-width:2px
    classDef norm fill:#ccffff,stroke:#333,stroke-width:2px
    classDef comp fill:#ffcccc,stroke:#333,stroke-width:2px
    classDef comp2 fill:#ffc0cb,stroke:#333,stroke-width:2px
    classDef final fill:#c6efce,stroke:#333,stroke-width:2px
    classDef util fill:#ffebcc,stroke:#333,stroke-width:2px
    classDef test fill:#e6ccff,stroke:#333,stroke-width:2px
    classDef docs fill:#d9f2d9,stroke:#333,stroke-width:2px
```
