# tidy-intelligence/r-owidapi architecture

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

- Interactive diagram: https://gitdiagram.com/tidy-intelligence/r-owidapi
- Repository: https://github.com/tidy-intelligence/r-owidapi

## Overview

This project is an R package that provides a client interface to the Our World in Data (OWID) Chart API. Its primary purpose is to allow users—economists, financial professionals, and data scientists—to retrieve chart data (including life expectancy, COVID-19 vaccination data, etc.), fetch metadata, and even embed interactive charts directly into web or Shiny applications. The package, as part of the econdataverse suite, serves as a tool to simplify the process of working with global datasets available on the OWID platform.

##### Main Components
- Core R Functions – Represented in the “R” directory. This contains functions such as owid_get, owid_search, owid_embed, owid_render, and helper functions (e.g., perform_request) that encapsulate the API calls and data transformation logic.
- Documentation & Metadata – Captured by the “man” directory (with Rd files and figures) and the README files that describe usage examples and package details.
- Testing Suite – Shown by the “tests” directory (using testthat) to validate the package functionality.
- CI/CD and Build Infrastructure – Highlight the GitHub workflow files found under “.github/workflows” which perform R CMD check, linting, pkgdown site generation, and test coverage monitoring.
- Package Metadata and Configuration – Include the DESCRIPTION, NAMESPACE, and other configuration files (e.g., .Rbuildignore, _pkgdown.yml) that define the package environment and build settings.

##### Relationships & Data Flow
- API Interaction: Map how the core functions call the underlying perform_request method to send HTTP requests to the external OWID API endpoints and retrieve JSON/data responses.
- Data Processing & Presentation: Show how the retrieved data is converted into tibbles (data frames) and how metadata is processed (e.g., metadata retrieval functions) before being usable by the end user.
- Testing & CI/CD Pipeline: Illustrate how the testing suite interacts with the package code (executing unit tests) and how GitHub Actions orchestrates code quality checks, linting, and package builds.
- Documentation Build: Connect the pkgdown workflow to the documentation in “man”, which is automatically updated and published.

##### Architectural Patterns and Design Principles
- Modular Design: The package is structured in a modular way with separate files for individual API functions, helper utilities, and testing scripts. This modularity can be highlighted with distinct components or sub-systems.
- Separation of Concerns: There is a clear separation between the core functionality (API calls and data processing) and the user interface layers (e.g., output functions for embedding charts).
- CI/CD Integration: Emphasize the integration of automated workflows from GitHub which support continuous integration, deployment, and documentation building.

##### Technologies, Frameworks, and Libraries
- Testthat: For unit testing within the “tests” directory.
- GitHub Actions: For orchestration of CI tools like R CMD check, lint tests, and package documentation builds.
- Shiny: Mark optional Shiny integration components (using functions like owid_output and owid_server) which indicate how charts can be embedded in interactive applications.
- OWID API: External dependency—the HTTP requests interacting with the Our World in Data API endpoints must be clearly delineated.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    U["User's R Session / Shiny App"]:::user

    %% Core R Functions Subgraph
    subgraph "Core R Functions (R)"
        A1["owid_get"]:::rfill
        A2["owid_search"]:::rfill
        A3["owid_embed"]:::rfill
        A4["owid_render"]:::rfill
        A5["helpers"]:::rfill
        A6["perform_request"]:::rfill
        A7["owid_get_catalog"]:::rfill
        A8["owid_get_metadata"]:::rfill
    end

    %% External API
    OWID_API["OWID API Endpoint"]:::external

    %% Testing Suite Subgraph
    subgraph "Testing Suite (tests)"
        T1["tests/testthat.R"]:::testing
        T2["tests/testthat/"]:::testing
    end

    %% CI/CD Workflows Subgraph
    subgraph "CI/CD Workflows (.github/workflows)"
        C1["R-CMD-check.yaml"]:::ci
        C2["lint.yaml"]:::ci
        C3["pkgdown.yaml"]:::ci
        C4["test-coverage.yaml"]:::ci
    end

    %% Documentation & Metadata Subgraph
    subgraph "Documentation & Metadata"
        D1["man/ (Rd Files)"]:::docs
        D2["README.md"]:::docs
    end

    %% Package Metadata & Configuration Subgraph
    subgraph "Package Metadata & Config"
        M1["DESCRIPTION"]:::metadata
        M2["NAMESPACE"]:::metadata
        M3["_pkgdown.yml"]:::metadata
        M4[".Rbuildignore"]:::metadata
    end

    %% Data Flow Connections
    U -->|"calls"| A1
    U -->|"calls"| A2
    U -->|"calls"| A3
    U -->|"calls"| A4

    %% Core functions interactions
    A1 ---|"uses"| A6
    A2 ---|"uses"| A6
    A3 ---|"uses"| A6
    A4 ---|"uses"| A6
    A5 ---|"supports"| A6
    A7 ---|"feeds"| A6
    A8 ---|"feeds"| A6

    %% External API Interaction
    A6 -->|"HTTP-request"| OWID_API

    %% Testing Suite Interaction
    T1 ---|"validates"| A1
    T1 ---|"validates"| A2
    T1 ---|"validates"| A3
    T1 ---|"validates"| A4
    T2 ---|"contains tests for"| A6

    %% CI/CD Workflows triggering tests and docs
    C1 -->|"runs tests"| T1
    C2 -->|"lints"| A1
    C3 -->|"builds"| D1
    C4 -->|"monitors"| A1

    %% Documentation link
    A1 ---|"documented in"| D1
    A3 ---|"documented in"| D1

    %% Package Metadata supports core functionality
    M1 -->|"configures"| A1
    M2 -->|"defines"| A1

    %% Class Definitions for colour styling
    classDef user fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef rfill fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef external fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef testing fill:#d6eaf8,stroke:#333,stroke-width:2px;
    classDef ci fill:#d5f5e3,stroke:#333,stroke-width:2px;
    classDef docs fill:#fcf3cf,stroke:#333,stroke-width:2px;
    classDef metadata fill:#d2b4de,stroke:#333,stroke-width:2px;

    %% Click Events for Core R Functions
    click A1 "https://github.com/tidy-intelligence/r-owidapi/blob/main/R/owid_get.R"
    click A2 "https://github.com/tidy-intelligence/r-owidapi/blob/main/R/owid_search.R"
    click A3 "https://github.com/tidy-intelligence/r-owidapi/blob/main/R/owid_embed.R"
    click A4 "https://github.com/tidy-intelligence/r-owidapi/blob/main/R/owid_render.R"
    click A5 "https://github.com/tidy-intelligence/r-owidapi/blob/main/R/helpers.R"
    click A6 "https://github.com/tidy-intelligence/r-owidapi/blob/main/R/perform_request.R"
    click A7 "https://github.com/tidy-intelligence/r-owidapi/blob/main/R/owid_get_catalog.R"
    click A8 "https://github.com/tidy-intelligence/r-owidapi/blob/main/R/owid_get_metadata.R"

    %% Click Events for Documentation & Metadata
    click D1 "https://github.com/tidy-intelligence/r-owidapi/tree/main/man/"
    click D2 "https://github.com/tidy-intelligence/r-owidapi/blob/main/README.md"

    %% Click Events for Testing Suite
    click T1 "https://github.com/tidy-intelligence/r-owidapi/blob/main/tests/testthat.R"
    click T2 "https://github.com/tidy-intelligence/r-owidapi/tree/main/tests/testthat/"

    %% Click Events for CI/CD Workflows
    click C1 "https://github.com/tidy-intelligence/r-owidapi/blob/main/.github/workflows/R-CMD-check.yaml"
    click C2 "https://github.com/tidy-intelligence/r-owidapi/blob/main/.github/workflows/lint.yaml"
    click C3 "https://github.com/tidy-intelligence/r-owidapi/blob/main/.github/workflows/pkgdown.yaml"
    click C4 "https://github.com/tidy-intelligence/r-owidapi/blob/main/.github/workflows/test-coverage.yaml"

    %% Click Events for Package Metadata & Config
    click M1 "https://github.com/tidy-intelligence/r-owidapi/tree/main/DESCRIPTION"
    click M2 "https://github.com/tidy-intelligence/r-owidapi/tree/main/NAMESPACE"
    click M3 "https://github.com/tidy-intelligence/r-owidapi/blob/main/_pkgdown.yml"
    click M4 "https://github.com/tidy-intelligence/r-owidapi/blob/main/.Rbuildignore"
```
