# facebookexperimental/robyn architecture

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

- Interactive diagram: https://gitdiagram.com/facebookexperimental/robyn
- Repository: https://github.com/facebookexperimental/robyn

## Overview

##### Project type and purpose
- This is a multi‐language, monorepo open-source tool for Marketing Mix Modeling (MMM), providing core engines in R and Python, a Shiny GUI, a Plumber API wrapper, tutorial notebooks, demo scripts, and a public documentation website.
- The R package (folder R/) is the original “core engine.” The Python module (folder python/) is a beta translation of that engine. The Shiny app (folder app/) and the Plumber service (folder robyn_api/) expose the engine via web UI and HTTP endpoints. The website (folder website/) hosts docs and guides.

##### File structure
- Top-level modules:
- R/ → R package sources, man pages, data, Dockerfile & build scripts
- app/ → R Shiny application (ui.R, server.R, app.R) and DESCRIPTION
- python/ → Python package sources, tutorials, docs, tests, pyproject.toml
- robyn_api/ → R Plumber endpoints + helper scripts for Python wrapper
- demo/ → Example scripts tying together R + Python workflows
- website/ → Docusaurus site (React code, markdown docs, Dockerfile, CI)
- CI config lives in .github/workflows (python-app.yml, website.yml, R-CMD.yaml).
- Dockerfiles exist under R/Docker, website/Dockerfile; docker-compose in website/.

##### Readme insights
- Core features: data input & validation, adstock & transformations, calibration, Ridge regression, multi‐objective evolutionary (Nevergrad), clustering, convergence analysis, Pareto front optimization, budget allocation, one-pager reporting, visualization.
- Python beta version mirrors R modules in an OOP fashion.
- API wrapper uses Plumber (R) to serve endpoints for R logic.

##### Main components & relationships
a. Components
- Clients:
- R CLI (import Robyn package)
- R Shiny App (app/)
- Python CLI / Jupyter notebooks (python/tutorials)
- HTTP API (robyn_api/ Plumber service)
- Documentation website (website/)
- Engines:
- R modeling engine (R/R/*.R modules)
- Python modeling engine (python/src/robyn/*)
- Sub-components (core logic):
1) Data ingestion & validation
2) Feature engineering & adstock transformations
3) Calibration & time-series decomposition
4) Model fitting (Ridge)
5) Hyperparameter optimization (Nevergrad evolutionary)
6) Clustering & convergence analysis
7) Pareto front optimizer & budget allocation
8) Reporting & visualization
- Infrastructure:
- CI/CD (GitHub Actions)
- Docker containers
- Package registries (CRAN, PyPI)
- Source control & collaboration (GitHub)

b. Interactions
- User → (R CLI or Shiny UI or Python notebook or HTTP client) → Engine
- Engine sub-components call each other in sequence (data → preprocess → model → optimize → report)
- HTTP client → Plumber API → R engine → returns JSON/plots
- CI pipelines trigger on push/PR: run R checks, Python tests, build website

##### Architectural patterns & principles
- Modular layering: clear separation of UI, API, core logic, data
- Language‐agnostic core: shared conceptual modules in R & Python
- Plugin‐style extensibility: each stage (calibration, optimizer, visualizer) lives in its own namespace
- CI/CD as code: workflows for each language & website
- Containerization for repeatable builds (Docker)

##### Technologies, frameworks & libraries
- R: base R, glmnet, jsonlite, plumber, devtools, Shiny
- Python: object‐oriented modules, Nevergrad, pandas, pytest
- Web: Docusaurus (React, MDX), Docker, nginx (via docker-compose)
- CI: GitHub Actions
- Packaging: CRAN, PyPI (robynpy)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Clients"
        U["User"]:::external
        RCLI["R CLI"]:::rcomp
        PyNB["Python Notebooks"]:::pycomp
        ShinyUI["Shiny Web UI"]:::rcomp
        APIClient["HTTP API Client"]:::rcomp
    end

    U -->|uses| RCLI
    U -->|uses| PyNB
    U -->|uses| ShinyUI
    U -->|uses HTTP JSON| APIClient

    subgraph "R Package" 
        RPMeta["Metadata & Build"]:::rcomp
        RCore["Modeling Engine Core Logic"]:::rcomp
        RDocker["Docker Setup"]:::rcomp
    end

    subgraph "Python Package"
        PYPkgMeta["Metadata & Build"]:::pycomp
        PYCore["Modeling Engine Core Logic"]:::pycomp
        PYNB["Tutorial Notebooks"]:::pycomp
        PYTests["Tests & Integration"]:::pycomp
    end

    subgraph "API & UI Wrappers"
        PlumberAPI["Plumber HTTP API"]:::rcomp
    end

    subgraph "Demo"
        Demo["Demo Scripts"]:::neutral
    end

    RCLI -->|function call| RPMeta
    RCLI -->|function call| RCore
    ShinyUI -->|function call| RCore
    APIClient -->|HTTP JSON| PlumberAPI
    PlumberAPI -->|function call| RCore

    PyNB -->|import module| PYPkgMeta
    PyNB -->|import module| PYCore
    PYCore -->|runs| PYTests
    Demo -->|flows to| RCore
    Demo -->|flows to| PYCore

    subgraph "Documentation"
        Website["Docusaurus Site"]:::web
    end

    U -->|reads docs| Website

    subgraph "Infrastructure"
        CI["CI/CD Workflows"]:::infra
        DockerCompose["Docker Compose"]:::infra
    end

    CI -->|triggers build/test| RCore
    CI -->|triggers build/test| PYCore
    CI -->|triggers deploy| Website
    DockerCompose -->|services| Website

    click RCore "https://github.com/facebookexperimental/robyn/tree/main/R/R/"
    click RPMeta "https://github.com/facebookexperimental/robyn/tree/main/R/DESCRIPTION"
    click RDocker "https://github.com/facebookexperimental/robyn/tree/main/R/Docker/Dockerfile"
    click ShinyUI "https://github.com/facebookexperimental/robyn/blob/main/app/R/ui.R"
    click PlumberAPI "https://github.com/facebookexperimental/robyn/blob/main/robyn_api/robynapi_endpoints.R"
    click PYCore "https://github.com/facebookexperimental/robyn/tree/main/python/src/robyn/"
    click PYPkgMeta "https://github.com/facebookexperimental/robyn/blob/main/python/pyproject.toml"
    click PYNB "https://github.com/facebookexperimental/robyn/blob/main/python/src/robyn/tutorials/tutorial1.ipynb"
    click PYTests "https://github.com/facebookexperimental/robyn/tree/main/python/tests/unit/"
    click Demo "https://github.com/facebookexperimental/robyn/blob/main/demo/demo.R"
    click Website "https://github.com/facebookexperimental/robyn/tree/main/website/Dockerfile"
    click CI "https://github.com/facebookexperimental/robyn/tree/main/.github/workflows/"
    click DockerCompose "https://github.com/facebookexperimental/robyn/blob/main/website/docker-compose.yml"

    classDef rcomp fill:#ddeeff,stroke:#000,stroke-width:1px
    classDef pycomp fill:#ffffcc,stroke:#000,stroke-width:1px
    classDef web fill:#ccffcc,stroke:#000,stroke-width:1px
    classDef infra fill:#eeeeee,stroke:#000,stroke-width:1px
    classDef external fill:#ccccff,stroke:#000,stroke-width:1px
    classDef neutral fill:#f8f8f8,stroke:#000,stroke-width:1px
```
