# matplotlib/mplfinance architecture

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

- Interactive diagram: https://gitdiagram.com/matplotlib/mplfinance
- Repository: https://github.com/matplotlib/mplfinance

## Overview

mplfinance is a Python library for financial-data visualization and visual analysis. A user supplies a Pandas OHLC DataFrame to `mpf.plot`; the plotting implementation validates and prepares it, builds panels, applies styles and widths, then renders through Matplotlib. The README also documents candlestick/OHLC/line, Renko/P&F, volume, technical overlays, customization, realtime animation, and a legacy API. Internal call edges follow excerpts or SOURCE INDEX references; README-only and unsampled capabilities are labeled conservatively.

Main entry points: [`src/mplfinance/plotting.py`](https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/plotting.py) (Plot API), [`src/mplfinance/_arg_validators.py`](https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/_arg_validators.py) (Input validation), [`src/mplfinance/_styles.py`](https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/_styles.py) (Style configuration), [`src/mplfinance/_helpers.py`](https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/_helpers.py) (Shared helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Plot entry"]
  node_plot_api["Plot API<br/>[plotting.py]"]
  node_validators["Input validation<br/>[_arg_validators.py]"]
  node_helpers["Shared helpers<br/>[_helpers.py]"]
end

subgraph group_render["Plot construction"]
  node_utils["Plot calculations<br/>[_utils.py]"]
  node_panels["Panel layout<br/>[_panels.py]"]
  node_widths["Plot widths<br/>[_widths.py]"]
  node_technical["Technical overlays<br/>[plotting.py]"]
  node_price_movement["Renko and P&amp;F<br/>[_utils.py]"]
end

subgraph group_custom["Appearance"]
  node_style_api["Style configuration<br/>[_styles.py]"]
  node_style_catalog["Built-in styles<br/>[__init__.py]"]
  node_style_definitions["Style definitions"]
  node_kwarg_help["Keyword help<br/>[_kwarg_help.py]"]
end

subgraph group_compat["Additional APIs"]
  node_animation["Realtime animation<br/>[animation.md]"]
  node_legacy["Legacy finance API<br/>[original_flavor.py]"]
end

node_user(("Data analyst"))
node_dataframe["OHLC DataFrame"]
node_matplotlib["Matplotlib"]
node_chart["Financial chart"]

node_user -->|"supplies"| node_dataframe
node_user -->|"calls"| node_plot_api
node_dataframe -->|"provides data"| node_plot_api
node_plot_api -->|"validates with"| node_validators
node_plot_api -->|"uses calculations"| node_utils
node_plot_api -->|"builds panels"| node_panels
node_plot_api -->|"sets widths"| node_widths
node_plot_api -->|"uses styles"| node_style_api
node_plot_api -->|"uses helpers"| node_helpers
node_validators -->|"uses helpers"| node_helpers
node_panels -->|"uses helpers"| node_helpers
node_panels -->|"validates panels"| node_validators
node_widths -->|"validates options"| node_validators
node_style_api -->|"validates options"| node_validators
node_style_api -->|"loads styles"| node_style_catalog
node_style_api -->|"uses helpers"| node_helpers
node_style_catalog -->|"registers definitions"| node_style_definitions
node_plot_api -->|"renders with"| node_matplotlib
node_matplotlib -->|"renders"| node_chart
node_plot_api -->|"supports overlays"| node_technical
node_plot_api -->|"supports Renko/P&amp;F"| node_price_movement
node_plot_api -.->|"supports updating"| node_animation
node_user -.->|"may use"| node_legacy
node_plot_api -.->|"documents options"| node_kwarg_help

click node_plot_api "https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/plotting.py"
click node_validators "https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/_arg_validators.py"
click node_helpers "https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/_helpers.py"
click node_utils "https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/_utils.py"
click node_panels "https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/_panels.py"
click node_widths "https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/_widths.py"
click node_style_api "https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/_styles.py"
click node_style_catalog "https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/_styledata/__init__.py"
click node_style_definitions "https://github.com/matplotlib/mplfinance/tree/master/src/mplfinance/_styledata"
click node_kwarg_help "https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/_kwarg_help.py"
click node_technical "https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/plotting.py"
click node_price_movement "https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/_utils.py"
click node_animation "https://github.com/matplotlib/mplfinance/blob/master/markdown/animation.md"
click node_legacy "https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/original_flavor.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_plot_api,node_validators,node_helpers toneBlue
class node_utils,node_panels,node_widths,node_technical,node_price_movement toneAmber
class node_style_api,node_style_catalog,node_style_definitions,node_kwarg_help toneMint
class node_animation,node_legacy toneRose
class node_user,node_dataframe,node_matplotlib,node_chart toneIndigo
```

## Components

### Plot entry

- [Plot API](https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/plotting.py): `src/mplfinance/plotting.py`
- [Input validation](https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/_arg_validators.py): `src/mplfinance/_arg_validators.py`
- [Shared helpers](https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/_helpers.py): `src/mplfinance/_helpers.py`

### Plot construction

- [Plot calculations](https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/_utils.py): `src/mplfinance/_utils.py`
- [Panel layout](https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/_panels.py): `src/mplfinance/_panels.py`
- [Plot widths](https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/_widths.py): `src/mplfinance/_widths.py`
- [Technical overlays](https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/plotting.py): `src/mplfinance/plotting.py`
- [Renko and P&F](https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/_utils.py): `src/mplfinance/_utils.py`

### Appearance

- [Style configuration](https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/_styles.py): `src/mplfinance/_styles.py`
- [Built-in styles](https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/_styledata/__init__.py): `src/mplfinance/_styledata/__init__.py`
- [Style definitions](https://github.com/matplotlib/mplfinance/tree/master/src/mplfinance/_styledata): `src/mplfinance/_styledata`
- [Keyword help](https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/_kwarg_help.py): `src/mplfinance/_kwarg_help.py`

### Additional APIs

- [Realtime animation](https://github.com/matplotlib/mplfinance/blob/master/markdown/animation.md): `markdown/animation.md`
- [Legacy finance API](https://github.com/matplotlib/mplfinance/blob/master/src/mplfinance/original_flavor.py): `src/mplfinance/original_flavor.py`

### Other components

- **Data analyst**
- **OHLC DataFrame**
- **Matplotlib**
- **Financial chart**

## Connections

- Data analyst → OHLC DataFrame: supplies (evidence: `README.md`)
- Data analyst → Plot API: calls (evidence: `README.md`)
- OHLC DataFrame → Plot API: provides data (evidence: `README.md`)
- Plot API → Input validation: validates with (evidence: `src/mplfinance/plotting.py`)
- Plot API → Plot calculations: uses calculations (evidence: `src/mplfinance/plotting.py`)
- Plot API → Panel layout: builds panels (evidence: `src/mplfinance/plotting.py`)
- Plot API → Plot widths: sets widths (evidence: `src/mplfinance/plotting.py`)
- Plot API → Style configuration: uses styles (evidence: `src/mplfinance/plotting.py`)
- Plot API → Shared helpers: uses helpers (evidence: `src/mplfinance/plotting.py`)
- Input validation → Shared helpers: uses helpers (evidence: `src/mplfinance/_arg_validators.py`)
- Panel layout → Shared helpers: uses helpers (evidence: `src/mplfinance/_panels.py`)
- Panel layout → Input validation: validates panels (evidence: `src/mplfinance/_panels.py`)
- Plot widths → Input validation: validates options (evidence: `src/mplfinance/_widths.py`)
- Style configuration → Input validation: validates options (evidence: `src/mplfinance/_styles.py`)
- Style configuration → Built-in styles: loads styles (evidence: `src/mplfinance/_styles.py`)
- Style configuration → Shared helpers: uses helpers (evidence: `src/mplfinance/_styles.py`)
- Built-in styles → Style definitions: registers definitions (evidence: `src/mplfinance/_styledata/__init__.py`)
- Plot API → Matplotlib: renders with (evidence: `README.md`)
- Matplotlib → Financial chart: renders (evidence: `README.md`)
- Plot API → Technical overlays: supports overlays (evidence: `README.md`)
- Plot API → Renko and P&F: supports Renko/P&F (evidence: `README.md`)
- Plot API → Realtime animation: supports updating
- Data analyst → Legacy finance API: may use
- Plot API → Keyword help: documents options
