# pymc-labs/pymc-marketing architecture

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

- Interactive diagram: https://gitdiagram.com/pymc-labs/pymc-marketing
- Repository: https://github.com/pymc-labs/pymc-marketing

## Overview

##### Main components
- Core Library (pymc_marketing package)
- Submodules: mmm (models, builders, components), clv (models, distributions, utilities), customer_choice (MVITS), bass, model_builder, model_config, model_graph, mlflow integration, plotting, utils.
- CLI / Scripts
- scripts/run_notebooks, scripts/docker, scripts/generate_gallery, scripts/slowest_tests, scripts/warnings_in_tests.
- Documentation Site
- Sphinx source in docs/source, ReadTheDocs integration (.readthedocs.yml).
- Generated API reference, gallery notebooks, guides.
- Streamlit Explainer App
- streamlit/mmm-explainer folder with pages, config.toml.
- Data Assets
- data/raw CSVs, config_files (YAML), processed training sets.
- CI/CD & DevOps
- GitHub workflows for tests, notebooks, UML, PyPI releases.
- pre-commit, Makefile, environment.yml, pyproject.toml.
- External Services
- PyPI (package distribution), ReadTheDocs (docs hosting), GitHub (source), Codecov (coverage), Docker Hub (optional), MLflow tracking (optional at runtime).

##### Relationships & interactions
- Users import the Core Library into Jupyter notebooks or production Python code.
- CLI scripts call the Core Library APIs (e.g., generate_gallery → docs, run_notebooks → execute examples).
- The Streamlit App imports Core Library to expose interactive visualizations.
- GitHub Actions workflows:
- test.yml installs environment.yml/pyproject, runs unit tests (tests/).
- test_notebook.yml uses nbformat to execute docs notebooks.
- pypi.yml builds and publishes to PyPI.
- rtd-link-preview builds docs and updates ReadTheDocs preview.
- Data flow:
- Raw data in data/ → Core Library preprocessing → model fitting → output artifacts (plots, models).
- Docker:
- scripts/docker/Dockerfile bundles Core Library, Jupyter for easy notebook access.

##### Architectural patterns & principles
- Modular design: clear separation of concerns (MMM, CLV, CSA, Bass).
- Builder pattern: YAML-driven model builders for MMM (builders/factories, yaml).
- Plugin-style extensibility: ability to swap adstock/saturation functions.
- CI as code: GitHub workflows orchestrate testing, docs, releases.
- Documentation-first: gallery and guide notebooks integrated into docs pipeline.

##### Technologies, frameworks & libraries
- Python (typing, pyproject.toml packaging).
- PyMC (probabilistic modeling), ArviZ (diagnostics).
- Sphinx & MyST-NB for docs.
- Streamlit for explainer app.
- Conda-Forge environment (environment.yml).
- GitHub Actions for CI/CD.
- Docker for container images.
- MLflow for experiment tracking (optional integration).

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Core Library" 
        direction TB
        coreInit["pymc_marketing/__init__.py"]:::core
        subgraph "MMM Submodule"
            direction TB
            mmmSub["pymc_marketing/mmm/"]:::core
            builders["pymc_marketing/mmm/builders/"]:::core
            componentsmmm["pymc_marketing/mmm/components/"]:::core
            plotmm["pymc_marketing/mmm/plot.py"]:::core
            utilmmm["pymc_marketing/mmm/utils.py"]:::core
        end
        subgraph "CLV Submodule"
            direction TB
            clvInit["pymc_marketing/clv/__init__.py"]:::core
            clvModels["pymc_marketing/clv/models/"]:::core
            clvDist["pymc_marketing/clv/distributions.py"]:::core
            clvPlot["pymc_marketing/clv/plotting.py"]:::core
            clvUtil["pymc_marketing/clv/utils.py"]:::core
        end
        customerChoice["pymc_marketing/customer_choice/mv_its.py"]:::core
        bass["pymc_marketing/bass/model.py"]:::core
        modelBuilder["pymc_marketing/model_builder.py"]:::core
        modelConfig["pymc_marketing/model_config.py"]:::core
        modelGraph["pymc_marketing/model_graph.py"]:::core
        mlflow["pymc_marketing/mlflow.py"]:::core
        plotCore["pymc_marketing/plot.py"]:::core
        utilCore["pymc_marketing/utils.py"]:::core
    end

    subgraph "CLI & Scripts" 
        direction TB
        runNotebooks["scripts/run_notebooks/runner.py"]:::script
        dockerScript["scripts/docker/Dockerfile"]:::script
        genGallery["scripts/generate_gallery.py"]:::script
        slowTests["scripts/slowest_tests/extract-slow-tests.py"]:::script
        warnTests["scripts/warnings_in_tests/extract-warnings.py"]:::script
    end

    subgraph "Documentation Site"
        direction TB
        docsSrc["docs/source/"]:::docs
        rtdConfig[".readthedocs.yml"]:::docs
    end

    subgraph "Streamlit Explainer App"
        direction TB
        streamlitApp["streamlit/mmm-explainer/"]:::frontend
    end

    subgraph "Data Assets"
        direction TB
        rawData["data/*.csv"]:::data
        configFiles["data/config_files/"]:::data
        processedData["data/processed/"]:::data
    end

    subgraph "CI/CD & DevOps"
        direction TB
        workflows[".github/workflows/"]:::ci
        environment["environment.yml"]:::ci
        pyproject["pyproject.toml"]:::ci
        makefile["Makefile"]:::ci
        precommit[".pre-commit-config.yaml"]:::ci
        tests["tests/"]:::ci
    end

    subgraph "External Services"
        direction TB
        GitHub["GitHub"]:::external
        PyPI["PyPI"]:::external
        ReadTheDocs["ReadTheDocs"]:::external
        Codecov["Codecov"]:::external
        DockerHub["Docker Hub"]:::external
        MLflowService["MLflow Tracking"]:::external
    end

    subgraph "User Interfaces"
        direction TB
        Users["Users"]:::frontend
        Jupyter["Jupyter Notebooks"]:::frontend
        Browser["Streamlit UI"]:::frontend
    end

    %% Relationships
    Users -->|import| coreInit
    Jupyter -->|import| coreInit
    Browser -->|uses| streamlitApp
    streamlitApp -->|imports| coreInit

    runNotebooks -->|calls| coreInit
    genGallery -->|calls| coreInit
    dockerScript -->|bundles| coreInit
    slowTests -->|analyzes| tests
    warnTests -->|analyzes| tests

    rawData -->|processed by| coreInit
    configFiles -->|used by| modelConfig
    processedData -->|fed into| coreInit
    coreInit -->|generates| plotCore

    workflows -->|runs| tests
    workflows -->|builds docs| docsSrc
    workflows -->|publishes| PyPI
    workflows -->|updates| ReadTheDocs
    workflows -->|reports| Codecov
    workflows -->|builds image| DockerHub

    GitHub -->|source repo| coreInit
    GitHub -->|triggers| workflows

    %% Click Events
    click coreInit "https://github.com/pymc-labs/pymc-marketing/blob/main/pymc_marketing/__init__.py"
    click mmmSub "https://github.com/pymc-labs/pymc-marketing/tree/main/pymc_marketing/mmm/"
    click builders "https://github.com/pymc-labs/pymc-marketing/tree/main/pymc_marketing/mmm/builders/"
    click componentsmmm "https://github.com/pymc-labs/pymc-marketing/tree/main/pymc_marketing/mmm/components/"
    click plotmm "https://github.com/pymc-labs/pymc-marketing/blob/main/pymc_marketing/mmm/plot.py"
    click utilmmm "https://github.com/pymc-labs/pymc-marketing/blob/main/pymc_marketing/mmm/utils.py"
    click clvInit "https://github.com/pymc-labs/pymc-marketing/blob/main/pymc_marketing/clv/__init__.py"
    click clvModels "https://github.com/pymc-labs/pymc-marketing/tree/main/pymc_marketing/clv/models/"
    click clvDist "https://github.com/pymc-labs/pymc-marketing/blob/main/pymc_marketing/clv/distributions.py"
    click clvPlot "https://github.com/pymc-labs/pymc-marketing/blob/main/pymc_marketing/clv/plotting.py"
    click clvUtil "https://github.com/pymc-labs/pymc-marketing/blob/main/pymc_marketing/clv/utils.py"
    click customerChoice "https://github.com/pymc-labs/pymc-marketing/blob/main/pymc_marketing/customer_choice/mv_its.py"
    click bass "https://github.com/pymc-labs/pymc-marketing/blob/main/pymc_marketing/bass/model.py"
    click modelBuilder "https://github.com/pymc-labs/pymc-marketing/blob/main/pymc_marketing/model_builder.py"
    click modelConfig "https://github.com/pymc-labs/pymc-marketing/blob/main/pymc_marketing/model_config.py"
    click modelGraph "https://github.com/pymc-labs/pymc-marketing/blob/main/pymc_marketing/model_graph.py"
    click mlflow "https://github.com/pymc-labs/pymc-marketing/blob/main/pymc_marketing/mlflow.py"
    click plotCore "https://github.com/pymc-labs/pymc-marketing/blob/main/pymc_marketing/plot.py"
    click utilCore "https://github.com/pymc-labs/pymc-marketing/blob/main/pymc_marketing/utils.py"
    click runNotebooks "https://github.com/pymc-labs/pymc-marketing/blob/main/scripts/run_notebooks/runner.py"
    click dockerScript "https://github.com/pymc-labs/pymc-marketing/tree/main/scripts/docker/Dockerfile"
    click genGallery "https://github.com/pymc-labs/pymc-marketing/blob/main/scripts/generate_gallery.py"
    click slowTests "https://github.com/pymc-labs/pymc-marketing/blob/main/scripts/slowest_tests/extract-slow-tests.py"
    click warnTests "https://github.com/pymc-labs/pymc-marketing/blob/main/scripts/warnings_in_tests/extract-warnings.py"
    click docsSrc "https://github.com/pymc-labs/pymc-marketing/tree/main/docs/source/"
    click rtdConfig "https://github.com/pymc-labs/pymc-marketing/blob/main/.readthedocs.yml"
    click streamlitApp "https://github.com/pymc-labs/pymc-marketing/tree/main/streamlit/mmm-explainer/"
    click rawData "https://github.com/pymc-labs/pymc-marketing/blob/main/data/*.csv"
    click configFiles "https://github.com/pymc-labs/pymc-marketing/tree/main/data/config_files/"
    click processedData "https://github.com/pymc-labs/pymc-marketing/tree/main/data/processed/"
    click workflows "https://github.com/pymc-labs/pymc-marketing/tree/main/.github/workflows/"
    click environment "https://github.com/pymc-labs/pymc-marketing/blob/main/environment.yml"
    click pyproject "https://github.com/pymc-labs/pymc-marketing/blob/main/pyproject.toml"
    click makefile "https://github.com/pymc-labs/pymc-marketing/tree/main/Makefile"
    click precommit "https://github.com/pymc-labs/pymc-marketing/blob/main/.pre-commit-config.yaml"
    click tests "https://github.com/pymc-labs/pymc-marketing/tree/main/tests/"

    %% Styles
    classDef core fill:#f9f,stroke:#333;
    classDef script fill:#fcf,stroke:#333;
    classDef docs fill:#ffc,stroke:#333;
    classDef frontend fill:#bbf,stroke:#333;
    classDef data fill:#afa,stroke:#333;
    classDef ci fill:#cff,stroke:#333;
    classDef external fill:#f96,stroke:#333;
```
