# salesforce/merlion architecture

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

- Interactive diagram: https://gitdiagram.com/salesforce/merlion
- Repository: https://github.com/salesforce/merlion

## Overview

Merlion is a time-series intelligence library, with separate anomaly-detection, forecasting, and change-point capabilities. Its principal workflow is to load time-series data, transform it, train or apply a model, post-process anomaly scores where relevant, and evaluate results. It also offers model selection, ensembles, visualization, a clickable dashboard, and a PySpark backend. The graph includes documented dataset and benchmarking support. Some subsystem links rely on README descriptions or SOURCE INDEX references; unsampled implementation details are not assumed.

Main entry points: [`merlion/dashboard/models`](https://github.com/salesforce/merlion/tree/main/merlion/dashboard/models) (Dashboard model workflows), [`merlion/models/factory.py`](https://github.com/salesforce/merlion/blob/main/merlion/models/factory.py) (Model factory), [`merlion/models/anomaly`](https://github.com/salesforce/merlion/tree/main/merlion/models/anomaly) (Anomaly and change-point models), [`merlion/models/forecast`](https://github.com/salesforce/merlion/tree/main/merlion/models/forecast) (Forecasting models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data and transforms"]
  node_datasets["Dataset loaders"]
  node_series["Time-series representation<br/>[time_series.py]"]
  node_transform["Preprocessing transforms"]
  node_resample["Resampling<br/>[resample.py]"]
end

subgraph group_models["Modeling"]
  node_factory["Model factory<br/>[factory.py]"]
  node_anomaly["Anomaly and change-point models"]
  node_forecast["Forecasting models"]
  node_automl["Automated model selection"]
  node_ensemble["Model ensembles"]
  node_postprocess["Anomaly post-processing"]
end

subgraph group_evaluation["Evaluation and benchmarking"]
  node_evalbase["Evaluation framework<br/>[base.py]"]
  node_anomalyeval["Anomaly evaluation<br/>[anomaly.py]"]
  node_forecasteval["Forecast evaluation<br/>[forecast.py]"]
  node_benchmark["Benchmark runners"]
end

subgraph group_interfaces["User interfaces and scale"]
  node_plot["Prediction visualization<br/>[plot.py]"]
  node_dashboard["Interactive dashboard<br/>[server.py]"]
  node_dashcallbacks["Dashboard callbacks"]
  node_dashmodels["Dashboard model workflows"]
  node_filemanager["Dashboard file manager<br/>[file_manager.py]"]
  node_spark["Distributed backend<br/>[pandas_udf.py]"]
  node_sparkdata["Spark dataset operations<br/>[dataset.py]"]
end

node_user(("Engineer"))

node_user -->|"load data"| node_datasets
node_datasets -.->|"provide series"| node_series
node_series -->|"transform inputs"| node_transform
node_transform -->|"supports resampling"| node_resample
node_user -.->|"configure model"| node_factory
node_factory -.->|"create detector"| node_anomaly
node_factory -.->|"create forecaster"| node_forecast
node_anomaly -->|"post-process scores"| node_postprocess
node_anomaly -->|"plot predictions"| node_plot
node_forecast -->|"plot predictions"| node_plot
node_automl -.->|"select models"| node_forecast
node_ensemble -->|"combine outputs"| node_anomaly
node_ensemble -.->|"combine outputs"| node_forecast
node_anomalyeval -->|"uses evaluator base"| node_evalbase
node_forecasteval -->|"uses evaluator base"| node_evalbase
node_anomalyeval -->|"evaluates detector"| node_anomaly
node_forecasteval -->|"evaluates forecaster"| node_forecast
node_benchmark -->|"runs evaluation"| node_anomalyeval
node_benchmark -->|"loads benchmarks"| node_datasets
node_user -->|"open dashboard"| node_dashboard
node_dashboard -->|"registers callbacks"| node_dashcallbacks
node_dashboard -->|"registers pages"| node_dashmodels
node_dashcallbacks -->|"invoke workflows"| node_dashmodels
node_dashcallbacks -->|"accesses files"| node_filemanager
node_dashmodels -->|"creates models"| node_factory
node_dashmodels -->|"evaluates results"| node_anomalyeval
node_dashmodels -->|"visualizes results"| node_plot
node_sparkdata -->|"supports UDFs"| node_spark
node_spark -->|"instantiates models"| node_factory
node_user -.->|"run distributed jobs"| node_spark

click node_datasets "https://github.com/salesforce/merlion/tree/main/ts_datasets/ts_datasets"
click node_series "https://github.com/salesforce/merlion/blob/main/merlion/utils/time_series.py"
click node_transform "https://github.com/salesforce/merlion/tree/main/merlion/transform"
click node_resample "https://github.com/salesforce/merlion/blob/main/merlion/transform/resample.py"
click node_factory "https://github.com/salesforce/merlion/blob/main/merlion/models/factory.py"
click node_anomaly "https://github.com/salesforce/merlion/tree/main/merlion/models/anomaly"
click node_forecast "https://github.com/salesforce/merlion/tree/main/merlion/models/forecast"
click node_automl "https://github.com/salesforce/merlion/tree/main/merlion/models/automl"
click node_ensemble "https://github.com/salesforce/merlion/tree/main/merlion/models/ensemble"
click node_postprocess "https://github.com/salesforce/merlion/tree/main/merlion/post_process"
click node_evalbase "https://github.com/salesforce/merlion/blob/main/merlion/evaluate/base.py"
click node_anomalyeval "https://github.com/salesforce/merlion/blob/main/merlion/evaluate/anomaly.py"
click node_forecasteval "https://github.com/salesforce/merlion/blob/main/merlion/evaluate/forecast.py"
click node_benchmark "https://github.com/salesforce/merlion/blob/main/benchmark_anomaly.py"
click node_plot "https://github.com/salesforce/merlion/blob/main/merlion/plot.py"
click node_dashboard "https://github.com/salesforce/merlion/blob/main/merlion/dashboard/server.py"
click node_dashcallbacks "https://github.com/salesforce/merlion/tree/main/merlion/dashboard/callbacks"
click node_dashmodels "https://github.com/salesforce/merlion/tree/main/merlion/dashboard/models"
click node_filemanager "https://github.com/salesforce/merlion/blob/main/merlion/dashboard/utils/file_manager.py"
click node_spark "https://github.com/salesforce/merlion/blob/main/merlion/spark/pandas_udf.py"
click node_sparkdata "https://github.com/salesforce/merlion/blob/main/merlion/spark/dataset.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_datasets,node_series,node_transform,node_resample toneBlue
class node_factory,node_anomaly,node_forecast,node_automl,node_ensemble,node_postprocess toneAmber
class node_evalbase,node_anomalyeval,node_forecasteval,node_benchmark toneMint
class node_plot,node_dashboard,node_dashcallbacks,node_dashmodels,node_filemanager,node_spark,node_sparkdata toneRose
class node_user toneIndigo
```

## Components

### Data and transforms

- [Dataset loaders](https://github.com/salesforce/merlion/tree/main/ts_datasets/ts_datasets): `ts_datasets/ts_datasets`
- [Time-series representation](https://github.com/salesforce/merlion/blob/main/merlion/utils/time_series.py): `merlion/utils/time_series.py`
- [Preprocessing transforms](https://github.com/salesforce/merlion/tree/main/merlion/transform): `merlion/transform`
- [Resampling](https://github.com/salesforce/merlion/blob/main/merlion/transform/resample.py): `merlion/transform/resample.py`

### Modeling

- [Model factory](https://github.com/salesforce/merlion/blob/main/merlion/models/factory.py): `merlion/models/factory.py`
- [Anomaly and change-point models](https://github.com/salesforce/merlion/tree/main/merlion/models/anomaly): `merlion/models/anomaly`
- [Forecasting models](https://github.com/salesforce/merlion/tree/main/merlion/models/forecast): `merlion/models/forecast`
- [Automated model selection](https://github.com/salesforce/merlion/tree/main/merlion/models/automl): `merlion/models/automl`
- [Model ensembles](https://github.com/salesforce/merlion/tree/main/merlion/models/ensemble): `merlion/models/ensemble`
- [Anomaly post-processing](https://github.com/salesforce/merlion/tree/main/merlion/post_process): `merlion/post_process`

### Evaluation and benchmarking

- [Evaluation framework](https://github.com/salesforce/merlion/blob/main/merlion/evaluate/base.py): `merlion/evaluate/base.py`
- [Anomaly evaluation](https://github.com/salesforce/merlion/blob/main/merlion/evaluate/anomaly.py): `merlion/evaluate/anomaly.py`
- [Forecast evaluation](https://github.com/salesforce/merlion/blob/main/merlion/evaluate/forecast.py): `merlion/evaluate/forecast.py`
- [Benchmark runners](https://github.com/salesforce/merlion/blob/main/benchmark_anomaly.py): `benchmark_anomaly.py`

### User interfaces and scale

- [Prediction visualization](https://github.com/salesforce/merlion/blob/main/merlion/plot.py): `merlion/plot.py`
- [Interactive dashboard](https://github.com/salesforce/merlion/blob/main/merlion/dashboard/server.py): `merlion/dashboard/server.py`
- [Dashboard callbacks](https://github.com/salesforce/merlion/tree/main/merlion/dashboard/callbacks): `merlion/dashboard/callbacks`
- [Dashboard model workflows](https://github.com/salesforce/merlion/tree/main/merlion/dashboard/models): `merlion/dashboard/models`
- [Dashboard file manager](https://github.com/salesforce/merlion/blob/main/merlion/dashboard/utils/file_manager.py): `merlion/dashboard/utils/file_manager.py`
- [Distributed backend](https://github.com/salesforce/merlion/blob/main/merlion/spark/pandas_udf.py): `merlion/spark/pandas_udf.py`
- [Spark dataset operations](https://github.com/salesforce/merlion/blob/main/merlion/spark/dataset.py): `merlion/spark/dataset.py`

### Other components

- **Engineer**

## Connections

- Engineer → Dataset loaders: load data
- Dataset loaders → Time-series representation: provide series
- Time-series representation → Preprocessing transforms: transform inputs (evidence: `merlion/models/base.py`)
- Preprocessing transforms → Resampling: supports resampling (evidence: `merlion/transform/resample.py`)
- Engineer → Model factory: configure model
- Model factory → Anomaly and change-point models: create detector
- Model factory → Forecasting models: create forecaster
- Anomaly and change-point models → Anomaly post-processing: post-process scores (evidence: `merlion/models/anomaly/base.py`)
- Anomaly and change-point models → Prediction visualization: plot predictions (evidence: `merlion/models/anomaly/base.py`)
- Forecasting models → Prediction visualization: plot predictions (evidence: `merlion/models/forecast/base.py`)
- Automated model selection → Forecasting models: select models
- Model ensembles → Anomaly and change-point models: combine outputs (evidence: `merlion/models/ensemble/anomaly.py`)
- Model ensembles → Forecasting models: combine outputs
- Anomaly evaluation → Evaluation framework: uses evaluator base (evidence: `merlion/evaluate/anomaly.py`)
- Forecast evaluation → Evaluation framework: uses evaluator base (evidence: `merlion/evaluate/forecast.py`)
- Anomaly evaluation → Anomaly and change-point models: evaluates detector (evidence: `merlion/evaluate/anomaly.py`)
- Forecast evaluation → Forecasting models: evaluates forecaster (evidence: `merlion/evaluate/forecast.py`)
- Benchmark runners → Anomaly evaluation: runs evaluation (evidence: `benchmark_anomaly.py`)
- Benchmark runners → Dataset loaders: loads benchmarks (evidence: `benchmark_anomaly.py`)
- Engineer → Interactive dashboard: open dashboard
- Interactive dashboard → Dashboard callbacks: registers callbacks (evidence: `merlion/dashboard/server.py`)
- Interactive dashboard → Dashboard model workflows: registers pages (evidence: `merlion/dashboard/server.py`)
- Dashboard callbacks → Dashboard model workflows: invoke workflows (evidence: `merlion/dashboard/callbacks/anomaly.py`)
- Dashboard callbacks → Dashboard file manager: accesses files (evidence: `merlion/dashboard/callbacks/anomaly.py`)
- Dashboard model workflows → Model factory: creates models (evidence: `merlion/dashboard/models/anomaly.py`)
- Dashboard model workflows → Anomaly evaluation: evaluates results (evidence: `merlion/dashboard/models/anomaly.py`)
- Dashboard model workflows → Prediction visualization: visualizes results (evidence: `merlion/dashboard/models/anomaly.py`)
- Spark dataset operations → Distributed backend: supports UDFs (evidence: `merlion/spark/pandas_udf.py`)
- Distributed backend → Model factory: instantiates models (evidence: `merlion/spark/pandas_udf.py`)
- Engineer → Distributed backend: run distributed jobs
