# kjkoeller/glyphx architecture

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

- Interactive diagram: https://gitdiagram.com/kjkoeller/glyphx
- Repository: https://github.com/kjkoeller/glyphx

## Overview

#### Purpose and public entry points
GlyphX is a Python 3.12+ visualization library that produces SVG-first charts, self-contained interactive HTML, and optional raster/PPTX exports. Its principal APIs are package imports and one-line plotting in `glyphx/__init__.py`, figure construction in `glyphx/figure.py`, 3-D construction in `glyphx/figure3d.py`, DataFrame integration in `glyphx/accessor.py`, and terminal commands in `glyphx/cli.py`.

#### Figure composition model
`Figure` is the central 2-D orchestration object: it owns chart state, series, axes/subplots, theme, annotations, layout, display, and persistence. `Axes` provides the coordinate-system and subplot boundary; `Series` classes represent chart-specific data and SVG emission contracts. Core paths: `glyphx/figure.py`, `glyphx/axes.py`, `glyphx/series.py`.

Control flow is generally: caller/API adapter → `Figure`/`Axes` configuration → add one or more series → layout/scale calculation → SVG rendering → optional HTML wrapping or file export.

#### Plot-type implementation layer
Chart types are distributed as specialized series modules rather than a monolithic renderer. Basic series are concentrated in `glyphx/series.py`; specialized statistical, financial, hierarchical, and composite visualizations each have dedicated implementations such as `glyphx/ecdf.py`, `glyphx/candlestick.py`, and `glyphx/treemap.py`. This lets the Figure pipeline treat heterogeneous visualizations through a common add/render interface.

Convenience dispatch lives in `glyphx/plot.py`; dataframe-oriented selection, grouping, aggregation, and hue splitting are handled at the pandas boundary by `glyphx/accessor.py` and `glyphx/hue_mixin.py`.

#### Rendering, HTML, and browser interaction
SVG rendering is separated from output packaging and browser behavior. Rendering support is centered on `glyphx/renderer.py`; HTML/SVG augmentation and export capabilities reside in `glyphx/assets/` and `glyphx/figure.py`. Browser-side interactivity is shipped as local JavaScript assets, including `glyphx/assets/tooltip.js`, `glyphx/assets/zoom.js`, and `glyphx/assets/brush.js`, enabling offline self-contained HTML rather than requiring a chart server or CDN.

Accessibility is a first-class rendering concern through `glyphx/a11y.py` plus `glyphx/assets/accessibility.js`, producing ARIA metadata and keyboard interactions alongside visual output.

#### Performance and real-time paths
Large-data preprocessing occurs before SVG generation. `glyphx/downsample.py` implements the common 2-D/3-D thinning and decimation algorithms, while series retain rendering/downsampling metadata. Streaming charts use a mutable series and live-refresh control path in `glyphx/streaming.py`, without a required server runtime.

#### 3-D pipeline
3-D charts use a separate figure and series family: `glyphx/figure3d.py`, `glyphx/plot3d.py`, and `glyphx/projection3d.py`, with concrete series in files such as `glyphx/scatter3d.py` and `glyphx/surface3d.py`. This boundary supports interactive WebGL-oriented HTML output with SVG fallback and applies 3-D-specific camera-aware/downsampling behavior.

#### External dependencies and delivery
Core runtime relies on NumPy and pandas. Optional export integrations require CairoSVG and python-pptx; natural-language chart generation in `glyphx/nlp.py` uses Anthropic and an API key. Distribution is Python packaging via `pyproject.toml` and `setup.cfg`; CI and PyPI publishing are defined in `.github/workflows/ci_tests.yml` and `.github/workflows/python-publish.yml`.

Main entry points: [`glyphx/figure.py`](https://github.com/kjkoeller/glyphx/blob/main/glyphx/figure.py) (Figure), [`glyphx/renderer.py`](https://github.com/kjkoeller/glyphx/blob/main/glyphx/renderer.py) (SVG renderer), [`glyphx/figure3d.py`](https://github.com/kjkoeller/glyphx/blob/main/glyphx/figure3d.py) (Figure3D), [`glyphx/scatter3d.py`](https://github.com/kjkoeller/glyphx/blob/main/glyphx/scatter3d.py) (3-D series)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public APIs"]
  node_package_api["Package API<br/>Python API<br/>[__init__.py]"]
  node_plot_dispatch["Plot dispatch<br/>convenience API<br/>[plot.py]"]
  node_dataframe_accessor["DataFrame accessor<br/>pandas adapter<br/>[accessor.py]"]
  node_cli["CLI<br/>terminal API<br/>[cli.py]"]
  node_nlp["Natural-language charts<br/>optional AI integration<br/>[nlp.py]"]
end

subgraph group_two_d["2-D Chart Pipeline"]
  node_figure["Figure<br/>2-D orchestrator<br/>[figure.py]"]
  node_axes["Axes &amp; subplots<br/>coordinate system<br/>[axes.py]"]
  node_series["Core series<br/>series contract<br/>[series.py]"]
  node_specialized_series["Specialized series<br/>chart implementations<br/>[ecdf.py]"]
  node_hue_mixin["Hue splitting<br/>pandas support<br/>[hue_mixin.py]"]
  node_downsample["Downsampling<br/>data preprocessing<br/>[downsample.py]"]
  node_streaming["Streaming charts<br/>live refresh<br/>[streaming.py]"]
end

subgraph group_output["Rendering &amp; Output"]
  node_renderer["SVG renderer<br/>rendering support<br/>[renderer.py]"]
  node_html_assets["HTML interaction assets<br/>browser JavaScript<br/>[tooltip.js]"]
  node_accessibility["Accessibility<br/>a11y rendering<br/>[a11y.py]"]
end

subgraph group_three_d["3-D Pipeline"]
  node_figure3d["Figure3D<br/>3-D orchestrator<br/>[figure3d.py]"]
  node_plot3d["3-D plot dispatch<br/>convenience API<br/>[plot3d.py]"]
  node_projection3d["3-D projection<br/>camera pipeline<br/>[projection3d.py]"]
  node_series3d["3-D series<br/>3-D chart implementations<br/>[scatter3d.py]"]
end

subgraph group_delivery["Distribution"]
  node_packaging["Python packaging<br/>distribution<br/>[pyproject.toml]"]
  node_ci_publish["CI &amp; PyPI publishing<br/>delivery automation<br/>[python-publish.yml]"]
end

node_package_api -->|"exposes"| node_plot_dispatch
node_plot_dispatch -->|"constructs"| node_figure
node_dataframe_accessor -->|"uses"| node_hue_mixin
node_dataframe_accessor -->|"adapts data into"| node_figure
node_cli -->|"drives"| node_figure
node_figure -->|"manages"| node_axes
node_figure -->|"adds and coordinates"| node_series
node_figure -->|"accepts"| node_specialized_series
node_series -->|"preprocesses large data"| node_downsample
node_specialized_series -->|"uses"| node_downsample
node_streaming -->|"mutates"| node_series
node_figure -->|"lays out then renders"| node_renderer
node_renderer -->|"packages SVG with"| node_html_assets
node_renderer -->|"augments with"| node_accessibility
node_plot3d -->|"constructs"| node_figure3d
node_figure3d -->|"coordinates"| node_series3d
node_series3d -->|"uses"| node_projection3d
node_series3d -->|"uses"| node_downsample
node_figure3d -->|"WebGL HTML or SVG fallback"| node_renderer
node_packaging -->|"released by"| node_ci_publish
node_nlp -.->|"generates charts through"| node_figure

click node_package_api "https://github.com/kjkoeller/glyphx/blob/main/glyphx/__init__.py"
click node_plot_dispatch "https://github.com/kjkoeller/glyphx/blob/main/glyphx/plot.py"
click node_dataframe_accessor "https://github.com/kjkoeller/glyphx/blob/main/glyphx/accessor.py"
click node_cli "https://github.com/kjkoeller/glyphx/blob/main/glyphx/cli.py"
click node_figure "https://github.com/kjkoeller/glyphx/blob/main/glyphx/figure.py"
click node_axes "https://github.com/kjkoeller/glyphx/blob/main/glyphx/axes.py"
click node_series "https://github.com/kjkoeller/glyphx/blob/main/glyphx/series.py"
click node_specialized_series "https://github.com/kjkoeller/glyphx/blob/main/glyphx/ecdf.py"
click node_hue_mixin "https://github.com/kjkoeller/glyphx/blob/main/glyphx/hue_mixin.py"
click node_downsample "https://github.com/kjkoeller/glyphx/blob/main/glyphx/downsample.py"
click node_streaming "https://github.com/kjkoeller/glyphx/blob/main/glyphx/streaming.py"
click node_renderer "https://github.com/kjkoeller/glyphx/blob/main/glyphx/renderer.py"
click node_html_assets "https://github.com/kjkoeller/glyphx/blob/main/glyphx/assets/tooltip.js"
click node_accessibility "https://github.com/kjkoeller/glyphx/blob/main/glyphx/a11y.py"
click node_figure3d "https://github.com/kjkoeller/glyphx/blob/main/glyphx/figure3d.py"
click node_plot3d "https://github.com/kjkoeller/glyphx/blob/main/glyphx/plot3d.py"
click node_projection3d "https://github.com/kjkoeller/glyphx/blob/main/glyphx/projection3d.py"
click node_series3d "https://github.com/kjkoeller/glyphx/blob/main/glyphx/scatter3d.py"
click node_packaging "https://github.com/kjkoeller/glyphx/blob/main/pyproject.toml"
click node_ci_publish "https://github.com/kjkoeller/glyphx/blob/main/.github/workflows/python-publish.yml"
click node_nlp "https://github.com/kjkoeller/glyphx/blob/main/glyphx/nlp.py"

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_package_api,node_plot_dispatch,node_dataframe_accessor,node_cli,node_nlp toneBlue
class node_figure,node_axes,node_series,node_specialized_series,node_hue_mixin,node_downsample,node_streaming toneAmber
class node_renderer,node_html_assets,node_accessibility toneMint
class node_figure3d,node_plot3d,node_projection3d,node_series3d toneRose
class node_packaging,node_ci_publish toneIndigo
```

## Components

### Public APIs

- [Package API](https://github.com/kjkoeller/glyphx/blob/main/glyphx/__init__.py): Python API · One-line plotting and package imports. · `glyphx/__init__.py`
- [Plot dispatch](https://github.com/kjkoeller/glyphx/blob/main/glyphx/plot.py): convenience API · `glyphx/plot.py`
- [DataFrame accessor](https://github.com/kjkoeller/glyphx/blob/main/glyphx/accessor.py): pandas adapter · Selects, groups, aggregates, and splits data by hue. · `glyphx/accessor.py`
- [CLI](https://github.com/kjkoeller/glyphx/blob/main/glyphx/cli.py): terminal API · `glyphx/cli.py`
- [Natural-language charts](https://github.com/kjkoeller/glyphx/blob/main/glyphx/nlp.py): optional AI integration · Uses Anthropic with an API key. · `glyphx/nlp.py`

### 2-D Chart Pipeline

- [Figure](https://github.com/kjkoeller/glyphx/blob/main/glyphx/figure.py): 2-D orchestrator · Owns chart state, layout, display, and persistence. · `glyphx/figure.py`
- [Axes & subplots](https://github.com/kjkoeller/glyphx/blob/main/glyphx/axes.py): coordinate system · `glyphx/axes.py`
- [Core series](https://github.com/kjkoeller/glyphx/blob/main/glyphx/series.py): series contract · Common chart data and SVG emission interface. · `glyphx/series.py`
- [Specialized series](https://github.com/kjkoeller/glyphx/blob/main/glyphx/ecdf.py): chart implementations · Statistical, financial, hierarchical, and composite charts. · `glyphx/ecdf.py`
- [Hue splitting](https://github.com/kjkoeller/glyphx/blob/main/glyphx/hue_mixin.py): pandas support · `glyphx/hue_mixin.py`
- [Downsampling](https://github.com/kjkoeller/glyphx/blob/main/glyphx/downsample.py): data preprocessing · 2-D and 3-D thinning and decimation. · `glyphx/downsample.py`
- [Streaming charts](https://github.com/kjkoeller/glyphx/blob/main/glyphx/streaming.py): live refresh · Mutable series with local live refresh control. · `glyphx/streaming.py`

### Rendering & Output

- [SVG renderer](https://github.com/kjkoeller/glyphx/blob/main/glyphx/renderer.py): rendering support · `glyphx/renderer.py`
- [HTML interaction assets](https://github.com/kjkoeller/glyphx/blob/main/glyphx/assets/tooltip.js): browser JavaScript · Offline tooltip, zoom, and brush behavior. · `glyphx/assets/tooltip.js`
- [Accessibility](https://github.com/kjkoeller/glyphx/blob/main/glyphx/a11y.py): a11y rendering · Adds ARIA metadata and keyboard interaction. · `glyphx/a11y.py`

### 3-D Pipeline

- [Figure3D](https://github.com/kjkoeller/glyphx/blob/main/glyphx/figure3d.py): 3-D orchestrator · `glyphx/figure3d.py`
- [3-D plot dispatch](https://github.com/kjkoeller/glyphx/blob/main/glyphx/plot3d.py): convenience API · `glyphx/plot3d.py`
- [3-D projection](https://github.com/kjkoeller/glyphx/blob/main/glyphx/projection3d.py): camera pipeline · Camera-aware projection and rendering behavior. · `glyphx/projection3d.py`
- [3-D series](https://github.com/kjkoeller/glyphx/blob/main/glyphx/scatter3d.py): 3-D chart implementations · Includes scatter and surface chart families. · `glyphx/scatter3d.py`

### Distribution

- [Python packaging](https://github.com/kjkoeller/glyphx/blob/main/pyproject.toml): distribution · `pyproject.toml`
- [CI & PyPI publishing](https://github.com/kjkoeller/glyphx/blob/main/.github/workflows/python-publish.yml): delivery automation · `.github/workflows/python-publish.yml`

## Connections

- Package API → Plot dispatch: exposes
- Plot dispatch → Figure: constructs
- DataFrame accessor → Hue splitting: uses
- DataFrame accessor → Figure: adapts data into
- CLI → Figure: drives
- Figure → Axes & subplots: manages
- Figure → Core series: adds and coordinates
- Figure → Specialized series: accepts
- Core series → Downsampling: preprocesses large data
- Specialized series → Downsampling: uses
- Streaming charts → Core series: mutates
- Figure → SVG renderer: lays out then renders
- SVG renderer → HTML interaction assets: packages SVG with
- SVG renderer → Accessibility: augments with
- 3-D plot dispatch → Figure3D: constructs
- Figure3D → 3-D series: coordinates
- 3-D series → 3-D projection: uses
- 3-D series → Downsampling: uses
- Figure3D → SVG renderer: WebGL HTML or SVG fallback
- Python packaging → CI & PyPI publishing: released by
- Natural-language charts → Figure: generates charts through