# owid/owid-grapher architecture

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

- Interactive diagram: https://gitdiagram.com/owid/owid-grapher
- Repository: https://github.com/owid/owid-grapher

## Overview

OWID Grapher is a data-visualization and publishing monorepo: teams manage data and chart configurations, render interactive charts and related content, then publish site pages and embeddable outputs. The graph emphasizes the documented admin-to-database-to-Grapher workflow and the Baker static-site path, while preserving Explorer, bespoke visualizations, search, and dynamic delivery as separate capabilities. Most links are supported by the README or SOURCE INDEX; unsampled implementation details are not treated as verified call paths.

Main entry points: [`site`](https://github.com/owid/owid-grapher/tree/master/site) (Site pages), [`adminSiteClient`](https://github.com/owid/owid-grapher/tree/master/adminSiteClient) (Grapher Admin), [`db/db.ts`](https://github.com/owid/owid-grapher/blob/master/db/db.ts) (MySQL data store), [`functions/_common/explorerHandlers.ts`](https://github.com/owid/owid-grapher/blob/master/functions/_common/explorerHandlers.ts) (Explorer handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Authoring and Admin"]
  node_adminui["Grapher Admin"]
  node_adminapi["Admin server"]
  node_gdocs["Gdocs content"]
end

subgraph group_data["Data and Models"]
  node_database[("MySQL data store<br/>[db.ts]")]
  node_variable["Variable model<br/>[Variable.ts]"]
end

subgraph group_visualization["Visualization"]
  node_grapher["Grapher library<br/>[ChartManager.ts]"]
  node_explorer["Explorer UI"]
  node_demography["Demography model<br/>[model.ts]"]
  node_scenarios["Projection scenarios<br/>[scenarios.ts]"]
end

subgraph group_delivery["Rendering and Publishing"]
  node_site["Site pages"]
  node_baker["Static site baker<br/>[SiteBaker.tsx]"]
  node_functions["Dynamic handlers"]
  node_grapher_render["Grapher renderer<br/>[grapherRenderer.ts]"]
  node_explorer_handlers["Explorer handlers"]
  node_downloads["Data downloads"]
end

subgraph group_services["Platform Services"]
  node_search["Search API<br/>[searchApi.ts]"]
  node_search_data["Search result assembly"]
  node_client_settings["Client settings<br/>[clientSettings.mts]"]
  node_server_settings["Server settings<br/>[serverSettings.ts]"]
end

node_team(("OWID authors"))
node_readers(("Site readers"))

node_team -->|"configure charts"| node_adminui
node_adminui -.->|"manage data"| node_adminapi
node_adminapi -->|"manage database"| node_database
node_database -.->|"stores variables"| node_variable
node_database -->|"supplies chart data"| node_grapher
node_adminui -->|"configure explorers"| node_explorer
node_team -->|"author content"| node_gdocs
node_gdocs -->|"provides authored content"| node_baker
node_grapher -->|"renders charts"| node_site
node_explorer -->|"renders interfaces"| node_site
node_demography -->|"uses scenarios"| node_scenarios
node_baker -->|"builds static site"| node_site
node_readers -->|"view pages"| node_site
node_readers -.->|"request dynamic output"| node_functions
node_functions -->|"renders charts"| node_grapher_render
node_explorer_handlers -->|"renders PNG"| node_grapher_render
node_explorer_handlers -->|"assembles downloads"| node_downloads
node_search -.->|"assembles results"| node_search_data
node_server_settings -->|"imports settings"| node_client_settings

click node_adminui "https://github.com/owid/owid-grapher/tree/master/adminSiteClient"
click node_adminapi "https://github.com/owid/owid-grapher/tree/master/adminSiteServer"
click node_gdocs "https://github.com/owid/owid-grapher/tree/master/db/model/Gdoc"
click node_database "https://github.com/owid/owid-grapher/blob/master/db/db.ts"
click node_variable "https://github.com/owid/owid-grapher/blob/master/db/model/Variable.ts"
click node_grapher "https://github.com/owid/owid-grapher/blob/master/packages/%40ourworldindata/grapher/src/chart/ChartManager.ts"
click node_demography "https://github.com/owid/owid-grapher/blob/master/bespoke/projects/demography/src/core/model/model.ts"
click node_scenarios "https://github.com/owid/owid-grapher/blob/master/bespoke/projects/demography/src/core/model/scenarios.ts"
click node_site "https://github.com/owid/owid-grapher/tree/master/site"
click node_baker "https://github.com/owid/owid-grapher/blob/master/baker/SiteBaker.tsx"
click node_functions "https://github.com/owid/owid-grapher/blob/master/functions/_common/reusableHandlers.ts"
click node_grapher_render "https://github.com/owid/owid-grapher/blob/master/functions/_common/grapherRenderer.ts"
click node_explorer_handlers "https://github.com/owid/owid-grapher/blob/master/functions/_common/explorerHandlers.ts"
click node_downloads "https://github.com/owid/owid-grapher/blob/master/functions/_common/downloadFunctions.ts"
click node_search "https://github.com/owid/owid-grapher/blob/master/functions/api/search/searchApi.ts"
click node_search_data "https://github.com/owid/owid-grapher/blob/master/functions/_common/search/constructSearchResultJson.ts"
click node_client_settings "https://github.com/owid/owid-grapher/blob/master/settings/clientSettings.mts"
click node_server_settings "https://github.com/owid/owid-grapher/blob/master/settings/serverSettings.ts"

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_adminui,node_adminapi,node_gdocs toneBlue
class node_database,node_variable toneAmber
class node_grapher,node_explorer,node_demography,node_scenarios toneMint
class node_site,node_baker,node_functions,node_grapher_render,node_explorer_handlers,node_downloads toneRose
class node_search,node_search_data,node_client_settings,node_server_settings,node_team,node_readers toneIndigo
```

## Components

### Authoring and Admin

- [Grapher Admin](https://github.com/owid/owid-grapher/tree/master/adminSiteClient): `adminSiteClient`
- [Admin server](https://github.com/owid/owid-grapher/tree/master/adminSiteServer): `adminSiteServer`
- [Gdocs content](https://github.com/owid/owid-grapher/tree/master/db/model/Gdoc): `db/model/Gdoc`

### Data and Models

- [MySQL data store](https://github.com/owid/owid-grapher/blob/master/db/db.ts): `db/db.ts`
- [Variable model](https://github.com/owid/owid-grapher/blob/master/db/model/Variable.ts): `db/model/Variable.ts`

### Visualization

- [Grapher library](https://github.com/owid/owid-grapher/blob/master/packages/%40ourworldindata/grapher/src/chart/ChartManager.ts): `packages/@ourworldindata/grapher/src/chart/ChartManager.ts`
- **Explorer UI**
- [Demography model](https://github.com/owid/owid-grapher/blob/master/bespoke/projects/demography/src/core/model/model.ts): `bespoke/projects/demography/src/core/model/model.ts`
- [Projection scenarios](https://github.com/owid/owid-grapher/blob/master/bespoke/projects/demography/src/core/model/scenarios.ts): `bespoke/projects/demography/src/core/model/scenarios.ts`

### Rendering and Publishing

- [Site pages](https://github.com/owid/owid-grapher/tree/master/site): `site`
- [Static site baker](https://github.com/owid/owid-grapher/blob/master/baker/SiteBaker.tsx): `baker/SiteBaker.tsx`
- [Dynamic handlers](https://github.com/owid/owid-grapher/blob/master/functions/_common/reusableHandlers.ts): `functions/_common/reusableHandlers.ts`
- [Grapher renderer](https://github.com/owid/owid-grapher/blob/master/functions/_common/grapherRenderer.ts): `functions/_common/grapherRenderer.ts`
- [Explorer handlers](https://github.com/owid/owid-grapher/blob/master/functions/_common/explorerHandlers.ts): `functions/_common/explorerHandlers.ts`
- [Data downloads](https://github.com/owid/owid-grapher/blob/master/functions/_common/downloadFunctions.ts): `functions/_common/downloadFunctions.ts`

### Platform Services

- [Search API](https://github.com/owid/owid-grapher/blob/master/functions/api/search/searchApi.ts): `functions/api/search/searchApi.ts`
- [Search result assembly](https://github.com/owid/owid-grapher/blob/master/functions/_common/search/constructSearchResultJson.ts): `functions/_common/search/constructSearchResultJson.ts`
- [Client settings](https://github.com/owid/owid-grapher/blob/master/settings/clientSettings.mts): `settings/clientSettings.mts`
- [Server settings](https://github.com/owid/owid-grapher/blob/master/settings/serverSettings.ts): `settings/serverSettings.ts`

### Other components

- **OWID authors**
- **Site readers**

## Connections

- OWID authors → Grapher Admin: configure charts (evidence: `README.md`)
- Grapher Admin → Admin server: manage data
- Admin server → MySQL data store: manage database (evidence: `README.md`)
- MySQL data store → Variable model: stores variables
- MySQL data store → Grapher library: supplies chart data (evidence: `README.md`)
- Grapher Admin → Explorer UI: configure explorers (evidence: `README.md`)
- OWID authors → Gdocs content: author content (evidence: `README.md`)
- Gdocs content → Static site baker: provides authored content (evidence: `README.md`)
- Grapher library → Site pages: renders charts (evidence: `README.md`)
- Explorer UI → Site pages: renders interfaces (evidence: `README.md`)
- Demography model → Projection scenarios: uses scenarios (evidence: `bespoke/projects/demography/src/core/model/scenarios.ts`)
- Static site baker → Site pages: builds static site (evidence: `README.md`)
- Site readers → Site pages: view pages (evidence: `README.md`)
- Site readers → Dynamic handlers: request dynamic output
- Dynamic handlers → Grapher renderer: renders charts (evidence: `functions/_common/reusableHandlers.ts`)
- Explorer handlers → Grapher renderer: renders PNG (evidence: `functions/_common/explorerHandlers.ts`)
- Explorer handlers → Data downloads: assembles downloads (evidence: `functions/_common/explorerHandlers.ts`)
- Search API → Search result assembly: assembles results
- Server settings → Client settings: imports settings (evidence: `settings/serverSettings.ts`)
