System Design
Detailed architecture of Plotcn: three-engine strategy, runtime boundaries, shared visualization layer, and registry distribution.
Plotcn Architecture
A source-first visualization system composed of three engines, a shared experience layer, and shadcn-compatible registry distribution.
Plotcn is an open-source, source-first visualization architecture for React.
The architecture preserves engine independence while delivering a unified developer and product experience. Recharts, D3.js, and Google Charts remain distinct engines, while Plotcn provides the shared visual tokens, responsive measurement, accessibility shell, and registry distribution layer.
High-Level Architecture
Plotcn organizes visualization delivery around two primary branches: the public website application and the shadcn-compatible registry distribution layer.
High-Level System Architecture
Three engines, shared visualization experience, shadcn-compatible registry distribution, and local consumer ownership.
Product Website
Plotcn Registry
Distributes complete component source, dependencies, and Tailwind tokens as JSON items.
Shared Visualization Experience
The Plotcn product model solves the problem of rigid third-party visualization libraries by separating engine capability, shared standards, and source ownership:
Plotcn does not attempt to replace the underlying visualization engines. Instead, it provides the production-ready product layer surrounding them.
Architectural Domains
The system is partitioned into five major architectural domains with strict unidirectional boundaries:
1. Product Application
Public user-facing surfaces built with Next.js App Router.
- Documentation
- Component Gallery
- Interactive Playground
- Registry Static Hosting
2. Shared Visualization Layer
Engine-independent product concerns wrapping each chart.
- Responsive Container
- Truthful States
- Semantic Theming
- Accessibility Shell
- Interaction Conventions
3. Visualization Engines
Three distinct rendering technologies with isolated scopes.
- Recharts (Declarative SVG)
- D3.js (Math & Geometry)
- Google Charts (Hosted Runtime)
4. Registry Distribution
Static JSON metadata consumed by the official shadcn CLI.
- Item Catalog
- Registry Item Manifests
- NPM Dependencies
- Registry Dependencies
5. Consumer Application
Your local codebase where source code is installed and modified.
- Installed TypeScript Files
- Direct Component Tweaks
- Local Styling Overrides
- No Upstream Lock-in
These five domains remain intentionally separated to prevent coupling product UI code to low-level visualization primitives.
Engine Architecture
Plotcn features three distinct rendering engines. Each engine is chosen for what it does best, maintaining clean architectural pipelines from typed application data to rendered pixels.
Recharts Pipeline
Preserves declarative React conventions without extra proprietary wrappers.
D3.js Pipeline
Avoids imperative `d3.select(...)` mutations inside React component lifecycles.
Google Charts Pipeline
Protected behind narrow client boundary. Never loaded in root layout or docs shell.
Recharts Architecture
Recharts is the primary engine for conventional React application charts:
- Line & Area: Continuous time-series metrics, trends, and filled volume distributions
- Bar & Column: Categorical comparisons, grouped bars, and stacked financial metrics
- Pie & Donut: Proportional breakdowns, category shares, and center-stat KPI cards
- Scatter & Bubble: Two-dimensional correlation plots and distribution clusters
- Radar & Radial: Multi-axis capability scoring and circular progress metrics
- Composed Charts: Combined line and bar charts sharing a unified time axis
Plotcn preserves Recharts' declarative React model without wrapping every primitive behind proprietary abstractions.
D3.js Architecture
D3 is used for custom mathematical geometries, continuous coordinate systems, and physics simulations:
- Mathematical Scales: Continuous linear, logarithmic, power, time, and band scales
- Geometric Paths: Area generators, curved lines, Voronoi tessellations, and contour paths
- Hierarchy & Trees: Treemaps, circle packing, sunbursts, and dendrograms
- Physics Layouts: Force-directed simulation nodes and spring networks
- Interaction Transforms: Dynamic brush selections and smooth coordinate zoom/pan
Plotcn enforces a strict separation: D3 computes the math; React manages the DOM. Imperative mutations (d3.select(...)) are avoided in favor of declarative JSX SVG elements.
Google Charts Architecture
Google Charts requires a dedicated architecture because it uses a browser-loaded, externally hosted visualization runtime:
- Typed Application Data: Passed as standard JavaScript object arrays
- Plotcn Google Component: Handles data transformation, CSS variable theme translation, accessible screen-reader shell, and container lifecycle
- Shared Google Loader: Coordinates script deduplication, on-demand package fetching, and promise caching
- Google Runtime: Executes
chart.draw(dataTable, options)inside an isolated rendering container
Shared Google Loader
All Google Charts components share a resilient, singleton loader located at @/lib/google-charts/loader.ts.
Shared Google Loader Guarantees
Located at `@/lib/google-charts/loader.ts`
Component unmounted or script not yet requested.
Script or package Promise is actively pending.
google.visualization API is ready to call .draw().
Script blocked by CSP, network offline, or timeout.
Core 2D business Cartesian charts
Vector world and regional choropleths
Temporal spans and Gantt schedules
Multi-stage energy and data flow paths
Hierarchical reporting structures
Interactive statistical data grid
The loader guarantees:
- Single Script Injection: The external loader script (
https://www.gstatic.com/charts/loader.js) is injected at most once across the entire application lifecycle. - Request Deduplication: Concurrent requests await the same pending initialization Promise.
- On-Demand Package Loading: Only the packages required by active visualizations (
corechart,geochart,timeline,sankey,orgchart,table) are fetched. - Explicit State Machine: Transitions through strongly typed states (
idle→loading→ready|error). - SSR Safety: Guards against accessing
windowordocumentduring server-side pre-rendering.
export type GoogleChartsLoaderState = | "idle" | "loading" | "ready" | "error"Packages are mapped dynamically:
export const googleChartPackages = { core: ["corechart"], geo: ["geochart"], timeline: ["timeline"], sankey: ["sankey"], org: ["orgchart"], table: ["table"],} as constRendering Architecture
Plotcn implements three distinct rendering models, each reflecting the underlying engine's technical paradigm:
Recharts
Declarative React SVGDirect declarative React JSX rendering with built-in SVG transitions.
D3.js
Math-Driven React SVG/CanvasReact owns state and DOM lifecycle. D3 computes coordinates and paths.
Google Charts
Hosted Client RuntimeIsolated behind client-side wrapper. Redraws managed via ResizeObserver.
This distinction remains explicit throughout the codebase. No engine is forced to mimic another engine's internal execution model.
Shared Chart Layer
The shared chart layer encapsulates engine-independent product concerns while keeping engine-specific visualization mechanics native:
What the Shared Layer Owns
- ChartContainer & ResizeObserver measurement
- Truthful states (loading, empty, error, offline)
- Semantic CSS variable theme tokens
- Accessibility shell & screen-reader data tables
- Number & currency formatting utilities
- Tooltip & Legend visual design conventions
- Reduced-motion-aware interaction conventions
- Standardized registry item metadata
What the Shared Layer Excludes
- Recharts-specific primitives (e.g. <XAxis>, <Tooltip>)
- D3 scale calculations or force simulation engines
- Google ChartOptions or google.visualization globals
- Google loader internals or external network calls
- Engine-specific event types or proprietary wrappers
- Monolithic 'universal chart' abstractions
Shared Experience vs. Shared Implementation
The guiding rule of Plotcn is:
Share the experience when possible. Keep engine mechanics native.
Plotcn standardizes visual language, state transitions, accessibility requirements, and responsive conventions across all three engines without forcing an artificial, leaky universal chart abstraction.
Architectural Boundary Rules
Twelve architectural invariants govern every component in Plotcn:
Never force D3 through Recharts
D3 stays idiomatic React + modular D3. Do not create artificial Recharts adapters.
Never force Google Charts through Recharts
Google Charts retains its native loader, data model, and option semantics.
Do not create one universal chart API
Universal <Chart engine='google' /> abstractions hide engine strengths. Keep APIs engine-specific.
shadcn/ui is not a visualization engine
shadcn/ui provides surrounding dialogs, tabs, and registry conventions—not mathematical chart algorithms.
Registry code must remain readable
Installed components should be clean, readable TypeScript with zero obscure build helpers.
Prefer SVG as default renderer
SVG is responsive, accessible, inspectable, and CSS-friendly for normal chart densities.
Canvas is an optimization path
Introduce Canvas only when data point density and framerates genuinely justify it.
WebGL requires justification
Never add WebGL overhead unless extreme visual volume or 3D coordinate space demands it.
React owns component state
D3 computes geometry and scales; React owns rendering, state, and DOM lifecycle.
Google owns its runtime DOM
Google Charts controls its inner chart surface. React owns wrapper, container, and accessibility.
Google must never become a global dependency
The root layout, docs shell, and Recharts gallery must never load the Google script.
No cross-engine dependency leakage
Installing Recharts items never installs D3 or Google packages, and vice versa.
Client / Server Boundaries
The Plotcn website and consumer implementations follow Next.js server-first principles:
Server Environment
SSR / RSC- • Documentation prose & headings
- • Server-rendered Shiki syntax highlighting
- • Registry item catalog & manifests
- • SEO metadata & OpenGraph tags
- • Static layout skeletons & navigation
Client Environment
"use client"- • Interactive chart hover & tooltips
- • Brush, pan, and zoom gestures
- • Container ResizeObserver callbacks
- • Google Charts runtime initialization
- • Playground state & code preview tabs
Documentation prose, syntax highlighting, and registry manifests render statically on the server. Interactive chart interactions, hover tooltips, gesture zooms, and the Google Charts runtime initialize exclusively on the client behind explicit boundaries.
Responsive Architecture
Responsiveness in Plotcn is driven by the chart container, not merely the viewport window:
Container-First Responsiveness
Charts adapt to their bounding parent, not merely viewport width
ResizeObserver detects width change ➔ Debounces 150ms to prevent thrashing ➔ Invokes `chart.draw(data, options)` ➔ Clean up listener on unmount.
Using ResizeObserver, charts respond fluidly whether placed inside full-width pages, responsive dashboard grids, narrow sidebar cards, or mobile modal drawers. Google Charts uses a 150ms debounced redraw schedule to prevent layout thrashing during continuous resize events.
Theme & Accessibility Architecture
Visual theming and screen-reader accessibility exist outside individual engine assumptions:
Semantic Theme Flow
Universal Accessibility Contract
- Theme Flow: Inherits semantic application CSS variables (
--chart-1through--chart-5,--background,--foreground) and adapts them for Recharts SVG fills, D3 color scales, or Google Charts options objects. - Accessibility Flow: Every visualization implements
role="region",aria-label, hidden natural-language screen-reader summaries, and accessible data disclosure tables.
Registry & Dependency Distribution
The Plotcn Registry is a distribution system, not an immutable runtime package.
Registry Distribution Flow
Engine Sibling Model
Never stacked Recharts → D3 → Google. Each engine is an independent peer.
Visualizations are distributed as static JSON item manifests from the production registry origin (https://plotcn.vercel.app/r/{name}.json) and installed directly into your repository via the shadcn CLI:
npx shadcn@latest add @plotcn/line-basicInstalled components are regular TypeScript and React files in your project. You own every line, with zero opaque node_modules lock-in.
Technology Stack
The Plotcn system leverages modern, production-hardened web standards:
| Layer | Technology | Primary Responsibility |
|---|---|---|
| Application | Next.js App Router, React 19, TypeScript | Documentation, gallery, registry hosting, SEO, playground shell |
| Styling | Tailwind CSS v4, CSS Variables, shadcn/ui | Design tokens, glassmorphism, responsive utilities, surrounding controls |
| Icons | Hugeicons React | Navigation, action buttons, technical badges, status indicators |
| Motion | Motion for React + D3 transitions | State transitions, data updates, reduced-motion-aware animations |
| Standard Charts | Recharts | Conventional Cartesian dashboard charts, analytics, and business metrics |
| Advanced Geometry | Modular D3 (d3-shape, d3-scale, d3-force) | Custom math, continuous scales, hierarchies, Voronoi, and physics layouts |
| Enterprise & Geo | Google Charts & GeoChart | Statistical choropleth mapping, Gantt timelines, Sankey flows, and data grids |
| Google Runtime | Shared Plotcn Google Loader | Script deduplication, on-demand package loading, readiness lifecycle |
| Primary Rendering | Vector SVG | Default renderer for Plotcn-owned Recharts and D3 visualizations |
| High-Density | Canvas API | High-throughput D3 visualizations where data density justifies it |
| Distribution | shadcn Registry Schema | Source-available component delivery and dependency resolution |
| Documentation | MDX + Server-Side Shiki | Rich technical guides, live interactive examples, and syntax highlighting |
Testing Boundaries
Quality assurance in Plotcn is organized across clear boundaries:
- Shared Layer Tests: Validates ResizeObserver policies, theme token translation, screen-reader data table disclosure, and truthful state fallbacks.
- Recharts Tests: Verifies component composition, tooltip rendering, reduced-motion overrides, and responsive breakpoints.
- D3.js Tests: Tests mathematical coordinate projections, scale ranges, and geometric path generators independently of DOM rendering.
- Google Charts Tests: Isolates local React wrapper unit tests from live external Google CDN integration tests.
- Registry Installation Tests: Verifies that installed component source builds cleanly inside empty, fresh consumer projects.
Core Architectural Invariants
Eighteen immutable principles maintain Plotcn's architectural integrity as the catalog grows:
Final System Mental Model
Plotcn brings Recharts, D3.js, and Google Charts into one coherent developer ecosystem:
Final System Mental Model
Three visualization engines. One shared product experience. No unnecessary cross-engine abstraction.
Semantic Tokens • Responsive Measurement • Truthful States • Accessibility Shell • Tooltip & Legend Standards
Three visualization engines. One shared product experience. Complete source ownership.
Recharts remains Recharts. D3 remains idiomatic React + D3. Google Charts retains its enterprise runtime and option model. Plotcn provides the unifying layer that makes all three feel intentional, consistent, responsive, accessible, and source-available for modern React applications.