# facebook/prophet architecture

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

- Interactive diagram: https://gitdiagram.com/facebook/prophet
- Repository: https://github.com/facebook/prophet

## Overview

1. **Repository purpose**
   - This is the Prophet forecasting library, maintained as a multi-language package repo.
   - The core product is the same statistical model exposed through two primary APIs: an **R package** under `R/` and a **Python package** under `python/`.
   - A third compatibility layer exists in `python_shim/` for the older `fbprophet` package name.

2. **Core modeling boundary**
   - The real modeling engine is a **Stan time-series model** stored in `R/inst/stan/prophet.stan` and `python/stan/prophet.stan`.
   - Both language frontends prepare data, invoke Stan, and then post-process results; neither contains the forecasting logic itself.
   - This makes the architecture “thin language wrapper + shared probabilistic model.”

3. **R package subsystem**
   - `R/R/` contains the public R API and internal helpers: the main `prophet()` object, fitting/prediction methods, plotting, diagnostics, holiday generation, and Stan-backend selection.
   - `R/NAMESPACE`, `R/DESCRIPTION`, `R/man/`, and `R/tests/` indicate a conventional CRAN package structure.
   - `R/src/` and the `configure` scripts support package compilation and platform-specific build setup, including Windows handling.

4. **Python package subsystem**
   - `python/prophet/` is the Python implementation with the main `Prophet` class in `forecaster.py`, diagnostics, plotting, serialization, utilities, and holiday generation.
   - `python/pyproject.toml` and `python/setup.py` show it is packaged as a standard Python distribution.
   - `python/prophet/tests/` contains unit and regression tests, including serialized model fixtures for backward compatibility checks.

5. **Shared data preparation pipeline**
   - In both languages, the user-facing API takes a time series table with date and value columns, validates it, scales/normalizes inputs, constructs seasonal features, holiday indicators, regressors, and changepoints, then sends the result to Stan.
   - After Stan returns posterior samples or point estimates, the libraries compute trend, seasonal components, uncertainty intervals, and final forecasts.
   - This preprocessing/postprocessing pipeline is the main data-flow backbone of the repo.

6. **Holidays and country calendars**
   - Holiday support is a distinct subsystem, with generated holiday datasets and code for constructing holiday feature matrices.
   - The R side keeps generated holiday sources in `R/data-raw/`, while Python has generation scripts in `python/scripts/generate_holidays_file.py`.
   - Holiday functionality is shared conceptually but implemented separately in each language binding.

7. **Diagnostics and evaluation**
   - Both implementations include cross-validation and forecast metric utilities, which are not just helpers but a separate analytical layer on top of the model.
   - This layer generates cutoff-based backtests, computes metrics such as MAE/MSE/RMSE/MAPE/SMAPE, and supports plots of performance over forecast horizon.
   - It depends on the fitted model output rather than directly on Stan.

8. **Visualization layer**
   - Plotting is handled in each frontend, with R plotting functions in `R/R/plot.R` and Python plotting in `python/prophet/plot.py`.
   - These functions consume forecast objects and diagnostic outputs to produce decomposition plots, forecast plots, seasonality views, and component breakdowns.
   - Plotting is therefore a read-only presentation boundary over fitted model artifacts.

9. **Serialization and interoperability**
   - Python includes `serialize.py` and several serialized test fixtures, indicating explicit support for saving/loading models across versions.
   - This is an important boundary for model portability and long-term compatibility, separate from training and prediction.
   - The R package also contains internal loading/model helper routines, but Python’s serialization surface is more explicit in the tree.

10. **Backend/runtime abstraction**
   - The R package includes `stan_backends.R` and `stanmodels.R`, and the README calls out `rstan` plus an experimental `cmdstanr` backend.
   - On the Python side, the historical shift is to `cmdstanpy`/CmdStan-based execution, with packaging logic that can compile or repackage CmdStan binaries.
   - So the repo has an abstraction layer for “how Stan runs,” separate from the forecasting model itself.

11. **Documentation and examples**
   - `docs/` is a full static documentation site with markdown docs, generated assets, layouts, styles, and hosted tutorials.
   - `notebooks/` and `examples/` provide reproducible end-to-end usage flows and sample datasets.
   - These are not part of the runtime, but they document the intended data flow from input time series to forecast output.

12. **Build, release, and CI**
   - GitHub Actions workflows, Travis config, Docker support, and package build files indicate a CI/release system for multiple artifacts.
   - The repo builds R source packages, Python wheels/sdist artifacts, and documentation, with platform-specific packaging concerns.
   - This matters architecturally because model compilation and binary distribution are part of the delivery pipeline, not just development tooling.

13. **Compatibility layer**
   - `python_shim/` mirrors the older `fbprophet` package namespace and implementation surface.
   - This is a migration/compatibility boundary that preserves older imports and package expectations while the main Python package lives under `prophet`.
   - It is separate from the primary Python package but shares the same conceptual API.

14. **Overall architecture summary**
   - The repo is best drawn as three main layers: **language frontends** (R, Python, shim), **shared statistical model in Stan**, and **supporting services** around holidays, diagnostics, plotting, serialization, docs, and packaging.
   - Data flows from user time series input into preprocessing, through Stan inference, and back into forecast objects consumed by diagnostics/visualization/serialization layers.
   - The main architectural boundary is between the **host language APIs** and the **Stan inference engine**.

Main entry points: [`python/prophet/forecaster.py`](https://github.com/facebook/prophet/blob/main/python/prophet/forecaster.py) (Python API), [`R/R/prophet.R`](https://github.com/facebook/prophet/blob/main/R/R/prophet.R) (R API), [`docs/index.md`](https://github.com/facebook/prophet/blob/main/docs/index.md) (Docs site), [`examples/example_air_passengers.csv`](https://github.com/facebook/prophet/blob/main/examples/example_air_passengers.csv) (Examples)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Shared model"]
  node_r_stan["R Stan<br/>Stan model<br/>[prophet.stan]"]
  node_py_stan["Python Stan<br/>Stan model<br/>[prophet.stan]"]
end

subgraph group_r["R package"]
  node_r_api["R API<br/>R front-end<br/>[prophet.R]"]
  node_r_data["R prep<br/>R data prep<br/>[utilities.R]"]
  node_r_backend["R backend<br/>R stan backend<br/>[stan_backends.R]"]
  node_r_diag["R metrics<br/>R diagnostics<br/>[diagnostics.R]"]
  node_r_plot["R plots<br/>R visualization<br/>[plot.R]"]
  node_r_holidays["R holidays<br/>[make_holidays.R]"]
end

subgraph group_python["Python package"]
  node_py_api["Python API<br/>Python front-end<br/>[forecaster.py]"]
  node_py_data["Python prep<br/>Python data prep<br/>[utilities.py]"]
  node_py_models["Python backend<br/>Python stan backend<br/>[models.py]"]
  node_py_diag["Python metrics<br/>Python diagnostics<br/>[diagnostics.py]"]
  node_py_plot["Python plots<br/>Python visualization<br/>[plot.py]"]
  node_py_ser["Python serialize<br/>Python portability<br/>[serialize.py]"]
  node_py_holidays["Python holidays<br/>[make_holidays.py]"]
end

subgraph group_support["Supporting layers"]
  node_shim_api["fbprophet API<br/>compat shim<br/>[forecaster.py]"]
  node_docs["Docs site<br/>documentation<br/>[index.md]"]
  node_examples["Examples"]
end

node_r_api -->|"prepares"| node_r_data
node_r_api -->|"fits via"| node_r_backend
node_r_backend -->|"runs"| node_r_stan
node_r_api -->|"evaluates"| node_r_diag
node_r_api -->|"renders"| node_r_plot
node_r_api -->|"adds holidays"| node_r_holidays
node_py_api -->|"prepares"| node_py_data
node_py_api -->|"fits via"| node_py_models
node_py_models -->|"runs"| node_py_stan
node_py_api -->|"evaluates"| node_py_diag
node_py_api -->|"renders"| node_py_plot
node_py_api -->|"adds holidays"| node_py_holidays
node_py_api -->|"serializes"| node_py_ser
node_shim_api -.->|"maps to"| node_py_api
node_docs -.->|"documents"| node_r_api
node_docs -.->|"documents"| node_py_api
node_examples -.->|"demonstrates"| node_r_api
node_examples -.->|"demonstrates"| node_py_api
node_r_holidays -.->|"conceptually shared"| node_py_holidays
node_r_diag -.->|"parallel layer"| node_py_diag

click node_r_api "https://github.com/facebook/prophet/blob/main/R/R/prophet.R"
click node_r_data "https://github.com/facebook/prophet/blob/main/R/R/utilities.R"
click node_r_backend "https://github.com/facebook/prophet/blob/main/R/R/stan_backends.R"
click node_r_diag "https://github.com/facebook/prophet/blob/main/R/R/diagnostics.R"
click node_r_plot "https://github.com/facebook/prophet/blob/main/R/R/plot.R"
click node_r_holidays "https://github.com/facebook/prophet/blob/main/R/R/make_holidays.R"
click node_r_stan "https://github.com/facebook/prophet/blob/main/R/inst/stan/prophet.stan"
click node_py_api "https://github.com/facebook/prophet/blob/main/python/prophet/forecaster.py"
click node_py_data "https://github.com/facebook/prophet/blob/main/python/prophet/utilities.py"
click node_py_models "https://github.com/facebook/prophet/blob/main/python/prophet/models.py"
click node_py_diag "https://github.com/facebook/prophet/blob/main/python/prophet/diagnostics.py"
click node_py_plot "https://github.com/facebook/prophet/blob/main/python/prophet/plot.py"
click node_py_ser "https://github.com/facebook/prophet/blob/main/python/prophet/serialize.py"
click node_py_holidays "https://github.com/facebook/prophet/blob/main/python/prophet/make_holidays.py"
click node_py_stan "https://github.com/facebook/prophet/blob/main/python/stan/prophet.stan"
click node_shim_api "https://github.com/facebook/prophet/blob/main/python_shim/fbprophet/forecaster.py"
click node_docs "https://github.com/facebook/prophet/blob/main/docs/index.md"
click node_examples "https://github.com/facebook/prophet/blob/main/examples/example_air_passengers.csv"

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_r_stan,node_py_stan toneBlue
class node_r_api,node_r_data,node_r_backend,node_r_diag,node_r_plot,node_r_holidays toneAmber
class node_py_api,node_py_data,node_py_models,node_py_diag,node_py_plot,node_py_ser,node_py_holidays toneMint
class node_shim_api,node_docs,node_examples toneRose
```

## Components

### Shared model

Common Stan inference engine used by both language frontends.

- [R Stan](https://github.com/facebook/prophet/blob/main/R/inst/stan/prophet.stan): Stan model · Embedded Stan model source used by the R package. · `R/inst/stan/prophet.stan`
- [Python Stan](https://github.com/facebook/prophet/blob/main/python/stan/prophet.stan): Stan model · Embedded Stan model source used by the Python package. · `python/stan/prophet.stan`

### R package

CRAN-style R frontend and package internals.

- [R API](https://github.com/facebook/prophet/blob/main/R/R/prophet.R): R front-end · Public R entry points and forecast object methods. · `R/R/prophet.R`
- [R prep](https://github.com/facebook/prophet/blob/main/R/R/utilities.R): R data prep · Input validation, scaling, seasonal features, changepoints, and helper utilities. · `R/R/utilities.R`
- [R backend](https://github.com/facebook/prophet/blob/main/R/R/stan_backends.R): R stan backend · Backend selection and Stan model wiring for R execution. · `R/R/stan_backends.R`
- [R metrics](https://github.com/facebook/prophet/blob/main/R/R/diagnostics.R): R diagnostics · Cross-validation and forecast evaluation utilities. · `R/R/diagnostics.R`
- [R plots](https://github.com/facebook/prophet/blob/main/R/R/plot.R): R visualization · Forecast, component, and seasonality plotting functions. · `R/R/plot.R`
- [R holidays](https://github.com/facebook/prophet/blob/main/R/R/make_holidays.R): R holidays · Holiday feature construction and generated holiday data. · `R/R/make_holidays.R`

### Python package

Modern Python frontend and distribution.

- [Python API](https://github.com/facebook/prophet/blob/main/python/prophet/forecaster.py): Python front-end · Main Prophet class and package entry surface. · `python/prophet/forecaster.py`
- [Python prep](https://github.com/facebook/prophet/blob/main/python/prophet/utilities.py): Python data prep · Validation, scaling, feature building, and forecast object assembly. · `python/prophet/utilities.py`
- [Python backend](https://github.com/facebook/prophet/blob/main/python/prophet/models.py): Python stan backend · CmdStan-oriented model execution and backend abstraction. · `python/prophet/models.py`
- [Python metrics](https://github.com/facebook/prophet/blob/main/python/prophet/diagnostics.py): Python diagnostics · Cross-validation, horizon metrics, and performance analysis. · `python/prophet/diagnostics.py`
- [Python plots](https://github.com/facebook/prophet/blob/main/python/prophet/plot.py): Python visualization · Forecast and component plotting functions. · `python/prophet/plot.py`
- [Python serialize](https://github.com/facebook/prophet/blob/main/python/prophet/serialize.py): Python portability · Model save/load and versioned serialization support. · `python/prophet/serialize.py`
- [Python holidays](https://github.com/facebook/prophet/blob/main/python/prophet/make_holidays.py): Python holidays · Holiday feature generation and country calendar support. · `python/prophet/make_holidays.py`

### Supporting layers

Compatibility, docs, examples, and release tooling around the model.

- [fbprophet API](https://github.com/facebook/prophet/blob/main/python_shim/fbprophet/forecaster.py): compat shim · Legacy namespace compatibility layer for older imports. · `python_shim/fbprophet/forecaster.py`
- [Docs site](https://github.com/facebook/prophet/blob/main/docs/index.md): documentation · Static documentation, tutorials, and rendered examples. · `docs/index.md`
- [Examples](https://github.com/facebook/prophet/blob/main/examples/example_air_passengers.csv): usage examples · Sample datasets and notebooks demonstrating end-to-end forecasting. · `examples/example_air_passengers.csv`

## Connections

- R API → R prep: prepares · The R API validates and transforms user time series before fitting.
- R API → R backend: fits via · The R API delegates inference to the Stan backend layer.
- R backend → R Stan: runs · R backend executes the shared Stan model.
- R API → R metrics: evaluates · Forecast objects feed cross-validation and metrics routines.
- R API → R plots: renders · Forecast output is consumed by plotting helpers.
- R API → R holidays: adds holidays · Holiday features are composed into the R model inputs.
- Python API → Python prep: prepares · The Python API validates, scales, and builds model features.
- Python API → Python backend: fits via · The Python API delegates execution to the backend layer.
- Python backend → Python Stan: runs · Python backend executes the shared Stan model.
- Python API → Python metrics: evaluates · Fitted forecasts feed diagnostics and backtesting.
- Python API → Python plots: renders · Forecast objects feed plotting and decomposition views.
- Python API → Python holidays: adds holidays · Holiday features are generated for Python model inputs.
- Python API → Python serialize: serializes · Python exposes explicit model persistence boundaries.
- fbprophet API → Python API: maps to · The legacy fbprophet namespace mirrors the modern Python API.
- Docs site → R API: documents · Docs describe the R user-facing forecasting flow.
- Docs site → Python API: documents · Docs describe the Python user-facing forecasting flow.
- Examples → R API: demonstrates · Examples and notebooks show the forecasting API in practice.
- Examples → Python API: demonstrates · Examples and notebooks show the Python workflow in practice.
- R holidays → Python holidays: conceptually shared · Holiday support is implemented separately but follows the same idea.
- R metrics → Python metrics: parallel layer · Both frontends provide similar cross-validation and metric utilities.
