Architecture

PlotSmith follows a strict 4-layer architecture with clear boundaries between layers. This design ensures separation of concerns, testability, and maintainability.

Layer 1: Data and Representations

Location: plotsmith.objects

This layer defines immutable dataclasses that represent plot-ready data and plot specifications. No matplotlib imports are allowed in this layer.

View Objects:

• plotsmith.objects.SeriesView - Time series data

• plotsmith.objects.BandView - Confidence bands

• plotsmith.objects.ScatterView - Scatter plot data

• plotsmith.objects.HistogramView - Histogram data

• plotsmith.objects.BarView - Bar chart data

• plotsmith.objects.HeatmapView - Heatmap data

• plotsmith.objects.FigureSpec - Figure specifications

Validators: plotsmith.objects.validate contains validation functions that check shapes and alignment of view objects.

Layer 2: Primitives

Location: plotsmith.primitives

This layer defines the drawing API. It can import matplotlib and must accept only Layer 1 objects. All matplotlib calls are encapsulated here.

Drawing Functions:

• plotsmith.primitives.draw_series() - Draw time series

• plotsmith.primitives.draw_band() - Draw confidence bands

• plotsmith.primitives.draw_scatter() - Draw scatter plots

• plotsmith.primitives.draw_histogram() - Draw histograms

• plotsmith.primitives.draw_bar() - Draw bar charts

• plotsmith.primitives.draw_heatmap() - Draw heatmaps

Styling Helpers:

• plotsmith.primitives.minimal_axes() - Apply minimalist axes styling

• plotsmith.primitives.tidy_axes() - Tidy axes styling

• plotsmith.primitives.style_line_plot() - Style line plots

• plotsmith.primitives.style_scatter_plot() - Style scatter plots

• plotsmith.primitives.style_bar_plot() - Style bar plots

Labeling Helpers:

• plotsmith.primitives.direct_label() - Add direct labels

• plotsmith.primitives.note() - Add notes

• plotsmith.primitives.emphasize_last() - Emphasize last point

• plotsmith.primitives.accent_point() - Highlight specific points

• plotsmith.primitives.event_line() - Mark events with lines

Layer 3: Tasks

Location: plotsmith.tasks

Tasks translate user intent into Layer 1 objects and a FigureSpec. Tasks can import pandas and numpy, but not matplotlib. Tasks can only import Layer 1 objects.

Task Classes:

• plotsmith.tasks.TimeseriesPlotTask - Convert time series data to views

• plotsmith.tasks.BacktestPlotTask - Convert backtest results to views

• plotsmith.tasks.HistogramPlotTask - Convert data to histogram views

• plotsmith.tasks.BarPlotTask - Convert data to bar views

• plotsmith.tasks.HeatmapPlotTask - Convert data to heatmap views

• plotsmith.tasks.ResidualsPlotTask - Convert residuals to views

Layer 4: Workflows

Location: plotsmith.workflows

Workflows provide one-call entry points for users. Workflows can import matplotlib. They call tasks, then primitives, then save or show plots.

Workflow Functions:

• plotsmith.workflows.plot_timeseries() - Plot time series

• plotsmith.workflows.plot_backtest() - Plot backtest results

• plotsmith.workflows.plot_residuals() - Plot residuals

• plotsmith.workflows.plot_histogram() - Plot histograms

• plotsmith.workflows.plot_bar() - Plot bar charts

• plotsmith.workflows.plot_heatmap() - Plot heatmaps

• plotsmith.workflows.plot_model_comparison() - Compare models

• plotsmith.workflows.figure() - Create styled figure

• plotsmith.workflows.small_multiples() - Create small multiples

Public API

The public API is defined in plotsmith/__init__.py and exports only:

• Workflow functions

• View objects (for type hints)

• Styling helpers

All other modules are internal and should not be imported directly.