# wch/r-source architecture

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

- Interactive diagram: https://gitdiagram.com/wch/r-source
- Repository: https://github.com/wch/r-source

## Overview

##### Project type & purpose
- R is an interpreted, functional programming language and runtime environment for statistics and graphics.
- It combines a C/Fortran core interpreter with a large standard library (“library/…”) of R‐level packages (stats, graphics, base, etc.), plus modules (X11, internet, lapack) and extensive tools.

##### Top-level components
a. Build & Configuration
– Autotools layer (configure, Makefile.in, etc.)
– m4 macros, etc/ and po/ for localization
– scripts/ for shell wrappers
b. Core Interpreter
– src/main: CLI front-end (Rmain.c), command–line parsing, startup
– src/main + src/appl + src/modules: expression parser, evaluator, memory manager, garbage collector
– include/: public & internal headers defining R’s C API
c. Math & Numerics
– src/nmath: standalone math functions (distributions, random variates)
– src/extra/blas & modules/lapack or system BLAS/LAPACK
d. Graphics
– library/grDevices & library/graphics & library/grid: R-level graphics packages
– src/extra/graphapp, modules/X11, Tcl/Tk front-ends, device back-ends (PDF, X11, Windows)
e. Standard Library (“library”)
– library/base, compiler, datasets, methods, parallel, stats, stats4, tcltk, tools, utils, translations
– Each is a loadable package (R‐level code + C stubs + documentation)
f. Extensions & Modules
– src/modules: dynamic modules (internet, lapack, X11)
– “Contributed packages” via CRAN (not in this tree but loaded at runtime)
g. Tools & Documentation
– tools/: Rd processing, package building, dynamic help
– doc/: manuals, HTML/CSS/JS for help pages
h. Tests
– tests/: unit and integration tests for core, graphics, embedding, packages

##### Relationships & data flows
– CLI/GUI front-ends → Parser/Evaluator
– Evaluator → Memory Manager (allocation/GC)
– Evaluator → Native primitives (C/Fortran functions in src/main, src/nmath, BLAS/LAPACK)
– Evaluator → Standard library packages (loaded via dynamic loader)
– Graphics functions → grDevices → device back-ends → display/file output
– Tools (Rd2HTML, Sweave) read doc/ and library man/ to produce documentation
– Build layer drives compilation of all components

##### Architectural patterns & design principles
- Layered architecture: front-end, evaluator, primitives, devices, library
- Plugin model: packages and modules loaded dynamically
- Autotools build: platform-agnostic configuration
- MVC‐like for graphics: high-level R graphics calls → graphics engine → device drivers

## Diagram (Mermaid)

```mermaid
graph TB
    %% Build & Configuration
    subgraph "Build & Configuration"
        AutotoolsFiles["Autotools files"]:::config
        Localization["Localization macros (etc/, po/)"]:::config
        BuildScripts["Shell wrappers & scripts"]:::config
    end

    %% Core Interpreter & Runtime
    subgraph "Core Interpreter & Runtime"
        Frontend["CLI Front-end (Rmain.c)"]:::core
        Evaluator["Parser/Evaluator"]:::core
        Headers["Public/Internal headers"]:::core
        Memory["Memory Manager & GC"]:::core
        Primitives["Native primitives & builtins"]:::core
    end

    %% Math & Numerics
    subgraph "Math & Numerics"
        MathLib["Standalone Math (src/nmath/)"]:::math
        BLAS["BLAS implementation"]:::math
        LAPACK["LAPACK Module"]:::math
    end

    %% Graphics Subsystem
    subgraph "Graphics Subsystem"
        RLevelGraphics["R-level graphics pkgs"]:::graphics
        GraphApp["Graph application front-end"]:::graphics
        X11Dev["X11 device module"]:::graphics
    end

    %% Standard Library Packages
    subgraph "Standard Library Packages"
        Base["Base package"]:::library
        Stats["Stats package"]:::library
        GraphicsPkg["Graphics packages"]:::library
        GridPkg["Grid package"]:::library
        OtherLibs["Other std libraries"]:::library
    end

    %% Extensions & Modules
    subgraph "Extensions & Modules"
        InternetMod["Internet module"]:::modules
        X11Mod["X11 module"]:::modules
        LAPACKMod["LAPACK module"]:::modules
    end

    %% Tools & Documentation
    subgraph "Tools & Documentation"
        ToolsNode["Tools & Rd processing"]:::tools
        DocNode["Documentation sources"]:::tools
    end

    %% Tests
    subgraph "Tests"
        TestsNode["Test Suites"]:::tests
    end

    %% Build Relationships
    Localization -->|drives| AutotoolsFiles
    BuildScripts -->|drives| AutotoolsFiles
    AutotoolsFiles -->|builds| Frontend
    AutotoolsFiles -->|builds| Primitives
    AutotoolsFiles -->|builds| MathLib
    AutotoolsFiles -->|builds| BLAS
    AutotoolsFiles -->|builds| LAPACK
    AutotoolsFiles -->|builds| RLevelGraphics
    AutotoolsFiles -->|builds| Base
    AutotoolsFiles -->|builds| ToolsNode
    AutotoolsFiles -->|builds| TestsNode

    %% Runtime Flows
    Frontend -->|"parses & starts eval"| Evaluator
    Evaluator -->|"allocates/GC"| Memory
    Evaluator -->|"calls C primitives"| Primitives
    Evaluator -->|"calls Math functions"| MathLib
    Evaluator -->|"RPC to BLAS"| BLAS
    Evaluator -->|"dynamic load"| Base
    Evaluator -->|"dynamic load"| Stats
    Evaluator -->|"dynamic load"| GraphicsPkg
    Evaluator -->|"dynamic load"| OtherLibs
    Evaluator -->|"loads module"| InternetMod
    Evaluator -->|"loads module"| X11Mod
    Evaluator -->|"loads module"| LAPACKMod
    Evaluator -->|"invokes graphics"| RLevelGraphics

    RLevelGraphics -->|"to graphapp"| GraphApp
    RLevelGraphics -->|"to X11 back-end"| X11Dev

    ToolsNode -->|"reads docs & man"| DocNode

    TestsNode -->|"tests core & packages"| Frontend
    TestsNode -->|"tests graphics"| RLevelGraphics

    %% Click Events
    click AutotoolsFiles "https://github.com/wch/r-source/blob/trunk/configure.ac"
    click Localization "https://github.com/wch/r-source/tree/trunk/etc/"
    click BuildScripts "https://github.com/wch/r-source/tree/trunk/scripts/"
    click Frontend "https://github.com/wch/r-source/blob/trunk/src/main/Rmain.c"
    click Evaluator "https://github.com/wch/r-source/blob/trunk/src/main/gram.c"
    click Headers "https://github.com/wch/r-source/tree/trunk/src/include/"
    click Memory "https://github.com/wch/r-source/blob/trunk/src/main/memory.c"
    click Primitives "https://github.com/wch/r-source/blob/trunk/src/main/builtin.c"
    click MathLib "https://github.com/wch/r-source/tree/trunk/src/nmath/"
    click BLAS "https://github.com/wch/r-source/tree/trunk/src/extra/blas/"
    click LAPACK "https://github.com/wch/r-source/tree/trunk/src/modules/lapack/"
    click RLevelGraphics "https://github.com/wch/r-source/tree/trunk/src/library/grDevices/"
    click GraphApp "https://github.com/wch/r-source/tree/trunk/src/extra/graphapp/"
    click X11Dev "https://github.com/wch/r-source/tree/trunk/src/modules/X11/"
    click Base "https://github.com/wch/r-source/tree/trunk/src/library/base/"
    click Stats "https://github.com/wch/r-source/tree/trunk/src/library/stats/"
    click GraphicsPkg "https://github.com/wch/r-source/tree/trunk/src/library/graphics/"
    click GridPkg "https://github.com/wch/r-source/tree/trunk/src/library/grid/"
    click OtherLibs "https://github.com/wch/r-source/tree/trunk/src/library/utils/"
    click InternetMod "https://github.com/wch/r-source/tree/trunk/src/modules/internet/"
    click X11Mod "https://github.com/wch/r-source/tree/trunk/src/modules/X11/"
    click LAPACKMod "https://github.com/wch/r-source/tree/trunk/src/modules/lapack/"
    click ToolsNode "https://github.com/wch/r-source/tree/trunk/src/library/tools/"
    click DocNode "https://github.com/wch/r-source/tree/trunk/doc/"
    click TestsNode "https://github.com/wch/r-source/tree/trunk/tests/"

    %% Styles
    classDef config fill:#d3d3d3,stroke:#333,stroke-width:1px;
    classDef core fill:#add8e6,stroke:#333,stroke-width:1px;
    classDef math fill:#90ee90,stroke:#333,stroke-width:1px;
    classDef graphics fill:#ffa500,stroke:#333,stroke-width:1px;
    classDef library fill:#dda0dd,stroke:#333,stroke-width:1px;
    classDef modules fill:#e6e6fa,stroke:#333,stroke-width:1px;
    classDef tools fill:#a52a2a,stroke:#333,stroke-width:1px;
    classDef tests fill:#ffc0cb,stroke:#333,stroke-width:1px;
```
