OWID Grapher Development Assistant

Expert assistant for developing on the Our World In Data Grapher platform - a comprehensive system for creating interactive data visualizations.

Codebase Overview

This is a monorepo for the Our World In Data website, including the custom Grapher data visualization component. Built with TypeScript, React 19, and Node 22.

Key Directories (Dependency Order)

1. **./packages/types** - Shared type definitions

2. **./packages/utils** - Utility functions

3. **./packages/core-table** - Custom dataframe classes for Grapher

4. **./packages/components** - Shared React components

5. **./packages/grapher** - Data visualization component (MobX 6 state management)

6. **./packages/explorer** - Data explorer wrapper with additional controls

7. **./db** - MySQL 8 database access and business logic for ArchieML from Google Docs

8. **./site** - Website code (React rendering ArchieML, uses hooks not MobX)

9. **./baker** - Static site generation (React to HTML)

10. **./adminSiteServer** - Internal admin API

11. **./adminSiteClient** - Admin UI client

12. **./devTools** - Various utilities

13. **./functions** - CloudFlare Functions for dynamic chart rendering

Development Workflow

Common Commands

When working on this codebase, use these commands:

1. **Type checking**: `yarn typecheck`

2. **Lint changed files**: `yarn testLintChanged`

3. **Check formatting**: `yarn testPrettierChanged`

4. **Fix formatting**: `yarn fixPrettierChanged`

5. **Run tests**: `yarn test run --reporter dot` (can specify test filenames)

6. **Database migrations**: `make migrate`

7. **Database tests**: `make dbtest`

After Completing Changes

Run this command and fix any errors:

```bash

yarn fixPrettierChanged > /dev/null 2>&1 && yarn typecheck

```

Creating Commits

Refer to `docs/agent-guidelines/commit-messages.md` for commit message guidelines.

Code Style Guidelines

General Conventions

1. **Strings**: Use double quotes, not single quotes

2. **Type safety**: Always add type definitions for function params and return values

3. **Reuse types**: Use existing shared type definitions where possible

4. **Avoid `any`**: Only use if absolutely necessary and ask for permission first

MobX 6 Pattern (Grapher & Admin)

Use a non-standard setup with class-based components:

CSS Conventions

1. **Primary approach**: Named style classes following BEM conventions in separate `.scss` files

2. **Avoid inline styles** unless the component already uses them for similar cases

3. **Component structure**: Components usually have companion `.scss` file with same name

4. **Entry points**:

- Site styles: `/site/owid.scss`

- Grapher styles: `/packages/@ourworldindata/grapher/src/core/grapher.scss`

Database Documentation

Main Datastore

MySQL 8 database with comprehensive documentation in `db/docs/`:

1. **Start with**: `db/docs/README.md` (overview and starting point)

2. **Table details**: One `TABLE-NAME.yml` file per table

Database Queries

**ALWAYS list the `db/docs/` directory before constructing queries or writing migrations.**

Run queries:

```bash

Query production database (read-only)

yarn query "QUERY TEXT"

Query staging database for current branch

yarn query -s "QUERY TEXT"

```

Example: On branch `images-pageviews`, staging query connects to `staging-site-images-pageviews`

Additional Documentation

Google Docs Pipeline

Before working on Google Docs-related features, read:

1. **`./docs/agent-guidelines/gdocs-cms-pipeline.md`**

- Detailed overview of ArchieML pipeline from Google Docs to database

2. **`./docs/agent-guidelines/gdocs-class-hierarchy.md`**

- Different types of Google Docs and how they differ

- How to create new document types

3. **`./docs/agent-guidelines/gdocs-attachments.md`**

- Attachments mechanism for providing context to React components

Step-by-Step Development Process

1. Understanding the Task

2. Before Writing Code

3. Writing Code

4. Testing

5. Before Committing

1. Fix formatting: `yarn fixPrettierChanged`

2. Run type checker: `yarn typecheck`

3. Fix all errors

4. Review commit message guidelines: `docs/agent-guidelines/commit-messages.md`

Common Patterns

Working with Database

1. List available tables: Check `db/docs/`

2. Understand table structure: Read `db/docs/TABLE-NAME.yml`

3. Test query: `yarn query "SELECT ..."`

4. Apply migration: `make migrate`

Working with Types

1. Check existing types in `./packages/types`

2. Add type definitions for all function parameters and return values

3. Avoid `any` type

Working with React Components

Important Notes