# observablehq/plot architecture

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

- Interactive diagram: https://gitdiagram.com/observablehq/plot
- Repository: https://github.com/observablehq/plot

## Overview

#### Purpose and Public Entry Points
Observable Plot is a JavaScript grammar-of-graphics library for rendering exploratory visualizations from tabular data. The package API is centralized in `src/index.js`, with public TypeScript declarations in `src/index.d.ts`; the core `Plot.plot` constructor is implemented in `src/plot.js`. A prebuilt distributable exists at `bundle.js`.

#### Plot Assembly Pipeline
`src/plot.js` orchestrates a plot specification into a rendered SVG/DOM figure: it establishes dimensions, scales, axes, facets, marks, legends, and interaction state. Marks conform to the abstraction in `src/mark.js`; common channel/value interpretation and option normalization occur in `src/channel.js` and `src/options.js`. This is the principal boundary between user-facing declarative options and internal render state.

#### Scales, Coordinates, and Layout
Scale inference and construction is owned by `src/scales.js`, with scale-family implementations under `src/scales/quantitative.js`, `src/scales/ordinal.js`, and `src/scales/temporal.js`. Spatial sizing, margins, and insets are resolved in `src/dimensions.js` and `src/inset.js`; geographic projection setup is separated in `src/projection.js`. Axes are generated by `src/axes.js`, consuming resolved scales rather than raw data.

#### Marks and SVG Rendering
Concrete visual layers live in `src/marks/`, including foundational marks such as `src/marks/dot.js`, `src/marks/line.js`, and `src/marks/rect.js`, plus specialized statistical, geographic, raster, and annotation marks. Each mark maps channels through the resolved scale context and produces DOM/SVG elements. Mark-specific composition is kept out of the central plot orchestration path.

#### Data Transformation Layer
Transforms reshape or aggregate input before mark rendering: `src/transforms/basic.js` provides common filtering/mapping behavior, while `src/transforms/bin.js`, `src/transforms/group.js`, `src/transforms/stack.js`, `src/transforms/window.js`, and `src/transforms/tree.js` implement higher-level analytical operations. This forms the data-processing boundary: user data/options become transformed channel arrays consumed by marks and scales.

#### Faceting, Legends, and Interaction
`src/facet.js` partitions data and coordinates repeated plot cells, working with the plot layout and marks. `src/legends.js`, `src/legends/ramp.js`, and `src/legends/swatches.js` construct scale-derived legend DOM. Pointer-driven interaction is isolated in `src/interactions/pointer.js`, while interactive annotation marks include `src/marks/tip.js` and `src/marks/crosshair.js`.

#### Documentation, Runtime, and Delivery
The library targets JavaScript environments with DOM/SVG rendering and relies materially on D3-style visualization primitives (the documentation hosts `docs/public/d3.js`). Rollup produces package bundles via `rollup.config.js`. Documentation is a VitePress site configured in `docs/.vitepress/config.ts`, with executable rendering support in `docs/components/PlotRender.js`; its static examples use the published plot runtime at `docs/public/plot.js`. GitHub Actions provide test, publication, and deployment automation through `.github/workflows/test.yml`, `.github/workflows/publish.yml`, and `.github/workflows/deploy.yml`.

Main entry points: [`src/plot.js`](https://github.com/observablehq/plot/blob/main/src/plot.js) (Plot constructor), [`src/scales.js`](https://github.com/observablehq/plot/blob/main/src/scales.js) (Scale inference), [`src/channel.js`](https://github.com/observablehq/plot/blob/main/src/channel.js) (Channels & options), [`src/index.js`](https://github.com/observablehq/plot/blob/main/src/index.js) (Package API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_api["Package API<br/>JavaScript entry<br/>[index.js]"]
  node_types["Type declarations<br/>TypeScript API<br/>[index.d.ts]"]
  node_bundle["Prebuilt bundle<br/>distributable<br/>[bundle.js]"]
end

subgraph group_core["Plot Assembly"]
  node_plot{{"Plot constructor<br/>orchestrator<br/>[plot.js]"}}
  node_channels["Channels &amp; options<br/>normalization<br/>[channel.js]"]
  node_transforms["Data transforms<br/>processing layer<br/>[basic.js]"]
  node_scales["Scale inference<br/>scale system<br/>[scales.js]"]
  node_scale_families["Scale families<br/>[quantitative.js]"]
  node_layout["Dimensions &amp; insets<br/>layout resolver<br/>[dimensions.js]"]
end

subgraph group_render["Rendering Features"]
  node_axes["Axes<br/>SVG generator<br/>[axes.js]"]
  node_projection["Projection setup<br/>geographic coordinates<br/>[projection.js]"]
  node_mark_base["Mark abstraction<br/>render contract<br/>[mark.js]"]
  node_marks["Concrete marks<br/>SVG layers"]
  node_facet["Faceting<br/>cell coordinator<br/>[facet.js]"]
  node_legends["Legends<br/>scale-derived DOM<br/>[legends.js]"]
  node_pointer["Pointer interaction<br/>[pointer.js]"]
end

subgraph group_delivery["Docs &amp; Delivery"]
  node_docs["Documentation site<br/>VitePress site<br/>[config.ts]"]
  node_docs_runtime["Docs plot runtime<br/>static runtime<br/>[plot.js]"]
  node_rollup["Bundle build<br/>Rollup pipeline<br/>[rollup.config.js]"]
  node_automation["GitHub Actions<br/>[test.yml]"]
end

node_api -->|"exports"| node_plot
node_types -.->|"declares"| node_api
node_plot -->|"normalizes spec"| node_channels
node_channels -->|"creates channel inputs"| node_transforms
node_transforms -->|"supplies transformed data"| node_scales
node_scales -->|"constructs"| node_scale_families
node_plot -->|"resolves sizing"| node_layout
node_plot -->|"configures"| node_projection
node_plot -->|"coordinates cells"| node_facet
node_plot -->|"renders"| node_axes
node_scales -->|"resolved scales"| node_axes
node_plot -->|"renders layers"| node_marks
node_mark_base -->|"implemented by"| node_marks
node_channels -->|"channel arrays"| node_marks
node_scales -->|"scale context"| node_marks
node_plot -->|"builds"| node_legends
node_scales -->|"drives"| node_legends
node_pointer -->|"supports interactive marks"| node_marks
node_rollup -->|"produces"| node_bundle
node_docs_runtime -.->|"published runtime"| node_api
node_docs -->|"serves examples"| node_docs_runtime
node_automation -.->|"tests and publishes"| node_rollup
node_automation -.->|"deploys"| node_docs

click node_api "https://github.com/observablehq/plot/blob/main/src/index.js"
click node_types "https://github.com/observablehq/plot/blob/main/src/index.d.ts"
click node_bundle "https://github.com/observablehq/plot/blob/main/bundle.js"
click node_plot "https://github.com/observablehq/plot/blob/main/src/plot.js"
click node_channels "https://github.com/observablehq/plot/blob/main/src/channel.js"
click node_transforms "https://github.com/observablehq/plot/blob/main/src/transforms/basic.js"
click node_scales "https://github.com/observablehq/plot/blob/main/src/scales.js"
click node_scale_families "https://github.com/observablehq/plot/blob/main/src/scales/quantitative.js"
click node_layout "https://github.com/observablehq/plot/blob/main/src/dimensions.js"
click node_axes "https://github.com/observablehq/plot/blob/main/src/axes.js"
click node_projection "https://github.com/observablehq/plot/blob/main/src/projection.js"
click node_mark_base "https://github.com/observablehq/plot/blob/main/src/mark.js"
click node_facet "https://github.com/observablehq/plot/blob/main/src/facet.js"
click node_legends "https://github.com/observablehq/plot/blob/main/src/legends.js"
click node_pointer "https://github.com/observablehq/plot/blob/main/src/interactions/pointer.js"
click node_docs "https://github.com/observablehq/plot/blob/main/docs/.vitepress/config.ts"
click node_docs_runtime "https://github.com/observablehq/plot/blob/main/docs/public/plot.js"
click node_rollup "https://github.com/observablehq/plot/blob/main/rollup.config.js"
click node_automation "https://github.com/observablehq/plot/blob/main/.github/workflows/test.yml"

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_api,node_types,node_bundle toneBlue
class node_plot,node_channels,node_transforms,node_scales,node_scale_families,node_layout toneAmber
class node_axes,node_projection,node_mark_base,node_marks,node_facet,node_legends,node_pointer toneMint
class node_docs,node_docs_runtime,node_rollup,node_automation toneRose
```

## Components

### Public API

- [Package API](https://github.com/observablehq/plot/blob/main/src/index.js): JavaScript entry · `src/index.js`
- [Type declarations](https://github.com/observablehq/plot/blob/main/src/index.d.ts): TypeScript API · `src/index.d.ts`
- [Prebuilt bundle](https://github.com/observablehq/plot/blob/main/bundle.js): distributable · `bundle.js`

### Plot Assembly

- [Plot constructor](https://github.com/observablehq/plot/blob/main/src/plot.js): orchestrator · Assembles specifications into rendered figures. · `src/plot.js`
- [Channels & options](https://github.com/observablehq/plot/blob/main/src/channel.js): normalization · `src/channel.js`
- [Data transforms](https://github.com/observablehq/plot/blob/main/src/transforms/basic.js): processing layer · Filtering, aggregation, binning, stacking, windows, and trees. · `src/transforms/basic.js`
- [Scale inference](https://github.com/observablehq/plot/blob/main/src/scales.js): scale system · `src/scales.js`
- [Scale families](https://github.com/observablehq/plot/blob/main/src/scales/quantitative.js): quantitative / ordinal / temporal · `src/scales/quantitative.js`
- [Dimensions & insets](https://github.com/observablehq/plot/blob/main/src/dimensions.js): layout resolver · `src/dimensions.js`

### Rendering Features

- [Axes](https://github.com/observablehq/plot/blob/main/src/axes.js): SVG generator · Consumes resolved scales. · `src/axes.js`
- [Projection setup](https://github.com/observablehq/plot/blob/main/src/projection.js): geographic coordinates · `src/projection.js`
- [Mark abstraction](https://github.com/observablehq/plot/blob/main/src/mark.js): render contract · `src/mark.js`
- **Concrete marks**: SVG layers · Dot, line, rect, statistical, geographic, raster, and annotation marks.
- [Faceting](https://github.com/observablehq/plot/blob/main/src/facet.js): cell coordinator · `src/facet.js`
- [Legends](https://github.com/observablehq/plot/blob/main/src/legends.js): scale-derived DOM · `src/legends.js`
- [Pointer interaction](https://github.com/observablehq/plot/blob/main/src/interactions/pointer.js): interaction · `src/interactions/pointer.js`

### Docs & Delivery

- [Documentation site](https://github.com/observablehq/plot/blob/main/docs/.vitepress/config.ts): VitePress site · Executable examples render Plot in documentation. · `docs/.vitepress/config.ts`
- [Docs plot runtime](https://github.com/observablehq/plot/blob/main/docs/public/plot.js): static runtime · `docs/public/plot.js`
- [Bundle build](https://github.com/observablehq/plot/blob/main/rollup.config.js): Rollup pipeline · `rollup.config.js`
- [GitHub Actions](https://github.com/observablehq/plot/blob/main/.github/workflows/test.yml): CI / publish / deploy · `.github/workflows/test.yml`

## Connections

- Package API → Plot constructor: exports
- Type declarations → Package API: declares
- Plot constructor → Channels & options: normalizes spec
- Channels & options → Data transforms: creates channel inputs
- Data transforms → Scale inference: supplies transformed data
- Scale inference → Scale families: constructs
- Plot constructor → Dimensions & insets: resolves sizing
- Plot constructor → Projection setup: configures
- Plot constructor → Faceting: coordinates cells
- Plot constructor → Axes: renders
- Scale inference → Axes: resolved scales
- Plot constructor → Concrete marks: renders layers
- Mark abstraction → Concrete marks: implemented by
- Channels & options → Concrete marks: channel arrays
- Scale inference → Concrete marks: scale context
- Plot constructor → Legends: builds
- Scale inference → Legends: drives
- Pointer interaction → Concrete marks: supports interactive marks
- Bundle build → Prebuilt bundle: produces
- Docs plot runtime → Package API: published runtime
- Documentation site → Docs plot runtime: serves examples
- GitHub Actions → Bundle build: tests and publishes
- GitHub Actions → Documentation site: deploys
