# ropensci/openalexr architecture

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

- Interactive diagram: https://gitdiagram.com/ropensci/openalexr
- Repository: https://github.com/ropensci/openalexr

## Overview

##### Project Type and Purpose
- This is an R client‐library (an R package) named **openalexR** that interfaces with the OpenAlex REST API.
- It lets R users compose API queries, fetch JSON data from OpenAlex, and transform that data into tibbles/data frames for bibliometric analysis.

##### File‐Structure Analysis
- **R/**
- Contains all R source code, grouped by functionality:
– `oa_query`, `oa_request`, `oa2df` form the core API client pipeline
– Wrappers: `oa_fetch`, `oa_random`, `oa_snowball`, `oa_ngrams`
– Utilities: `utils.R`, `simplify.R`, `globals.R`, `coro.R`
- **data-raw/** and **data/**
- Scripts and shipped datasets used internally (e.g., coverage tables, countrycode)
- **man/**
- Auto‐generated Rd help files (via roxygen2)
- **vignettes/**
- User guides and example analyses in R Markdown
- **tests/**
- `testthat` suite validating function behavior
- **pkgdown/**
- Configuration for building the package website
- **.github/workflows/**
- CI pipelines (R-CMD-check, coverage, pkgdown site deploy)
- Top-level metadata: `DESCRIPTION`, `NAMESPACE`, `README.Rmd/README.md`, `LICENSE`, `NEWS.md`

##### README Insights
- Describes five core functions:
1. **oa_query** – builds filter strings
2. **oa_request** – performs HTTP GET to OpenAlex
3. **oa2df** – parses JSON → tibble
4. **oa_fetch** – user-friendly wrapper
5. **oa_random** – fetch a random entity
- Additional modules: snowballing (`oa_snowball`), N-grams (`oa_ngrams`), plotting examples using tidyverse.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["User (R Console, Scripts, Shiny)"]:::user

    %% Package Core
    subgraph "Package Core"
        direction TB
        QueryBuilder["Query Builder (oa_query)"]:::code
        HTTPClient["HTTP Client (oa_request)"]:::code
        Parser["Parser (oa2df)"]:::code

        subgraph Wrappers
            direction TB
            oa_fetch["Wrapper: oa_fetch"]:::code
            oa_random["Wrapper: oa_random"]:::code
            oa_snowball["Wrapper: oa_snowball"]:::code
            oa_ngrams["Wrapper: oa_ngrams"]:::code
        end

        subgraph Utilities
            direction TB
            Utils["General Helpers"]:::code
            Simplify["Result Simplification"]:::code
            Globals["Global Settings"]:::code
            Coro["Coroutine Support"]:::code
        end
    end

    %% Data Storage
    ShippedData["Shipped Data (.rda lookup tables)"]:::data
    DataRaw["Data‐Raw Scripts & Sources"]:::data

    %% Documentation & Examples
    subgraph "Documentation & Examples"
        direction TB
        RdHelp["Rd Help Files"]:::docs
        Vignettes["Vignettes & Examples"]:::docs
        SiteConfig["Site Configuration"]:::docs
    end

    %% Tests & CI/CD
    subgraph "Tests & CI/CD"
        direction TB
        Tests["Testthat Suite"]:::ci
        CIWorkflows["GitHub Workflows"]:::ci
        Pkgdown["Pkgdown Site"]:::docs
    end

    %% External API
    OpenAlexAPI["OpenAlex REST API"]:::external

    %% Flows
    User -->|calls| oa_fetch
    User -->|calls| oa_random
    User -->|calls| oa_snowball
    User -->|calls| oa_ngrams

    oa_fetch -->|uses| QueryBuilder
    oa_random -->|uses| QueryBuilder
    oa_snowball -->|uses| QueryBuilder
    oa_ngrams -->|uses| QueryBuilder

    QueryBuilder -->|builds URL| HTTPClient
    HTTPClient -->|sends request| OpenAlexAPI
    OpenAlexAPI -->|returns JSON| Parser
    Parser -->|produces tibble| Utilities
    Utilities -->|returns data frame| User

    Utilities -->|loads lookup| ShippedData
    Utilities -->|generates data| DataRaw

    %% CI/CD flows
    CIWorkflows -->|runs tests| Tests
    Tests -->|coverage results| CIWorkflows
    CIWorkflows -->|deploy site| Pkgdown

    %% Click Events
    click QueryBuilder "https://github.com/ropensci/openalexr/blob/main/R/oa_query.R"
    click HTTPClient "https://github.com/ropensci/openalexr/blob/main/R/oa_request.R"
    click Parser "https://github.com/ropensci/openalexr/blob/main/R/oa2df.R"
    click oa_fetch "https://github.com/ropensci/openalexr/blob/main/R/oa_fetch.R"
    click oa_random "https://github.com/ropensci/openalexr/blob/main/R/oa_random.R"
    click oa_snowball "https://github.com/ropensci/openalexr/blob/main/R/oa_snowball.R"
    click oa_ngrams "https://github.com/ropensci/openalexr/blob/main/R/oa_ngrams.R"
    click Utils "https://github.com/ropensci/openalexr/blob/main/R/utils.R"
    click Simplify "https://github.com/ropensci/openalexr/blob/main/R/simplify.R"
    click Globals "https://github.com/ropensci/openalexr/blob/main/R/globals.R"
    click Coro "https://github.com/ropensci/openalexr/blob/main/R/coro.R"
    click ShippedData "https://github.com/ropensci/openalexr/blob/main/data/*.rda"
    click DataRaw "https://github.com/ropensci/openalexr/blob/main/data-raw/gen-data.R"
    click RdHelp "https://github.com/ropensci/openalexr/blob/main/man/*.Rd"
    click Vignettes "https://github.com/ropensci/openalexr/blob/main/vignettes/articles/*.Rmd"
    click SiteConfig "https://github.com/ropensci/openalexr/blob/main/_pkgdown.yml"
    click Tests "https://github.com/ropensci/openalexr/blob/main/tests/testthat.R"
    click CIWorkflows "https://github.com/ropensci/openalexr/blob/main/.github/workflows/*.yaml"

    %% Styles
    classDef code fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px
    classDef data fill:#FFA500,stroke:#000,stroke-width:1px
    classDef ci fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef docs fill:#FFFF99,stroke:#000,stroke-width:1px
    classDef user fill:#D3D3D3,stroke:#000,stroke-width:1px
```
