How facebookexperimental/robyn works
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)