# jeffreyhorner/rapache architecture

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

- Interactive diagram: https://gitdiagram.com/jeffreyhorner/rapache
- Repository: https://github.com/jeffreyhorner/rapache

## Overview

##### Project type and purpose
- Rapache is not a typical web app; it’s an Apache HTTPD extension that embeds the R interpreter in Apache 2.x.
- It comprises two main pieces:
- mod_R: an Apache 2 module (mod_R.c, mod_R.h.in, built by apxs) that hooks into the Apache request lifecycle and acts as glue to R.
- libapreq2 (bundled under libapreq2/…): a request‐parsing library (third‐party Apache project) for parsing query params, multipart uploads, cookies, etc.

##### File structure
- Top level:
- configure / Makefile.am / configure.in – GNU autotools build scripts
- mod_R.c / mod_R.h.in – core Apache module source
- debian/ & rpm/ – platform packaging/installer files
- test/ – end-to-end R script tests and sample Apache configs
- tools/ – auxiliary scripts for packaging and scaffolding
- libapreq2/:
- /, library/, module/, glue/perl/ – splits into C public API headers, C implementation, Apache module adapters, Perl XS glue and tests
- m4/, missing, libtool, depcomp, etc. – autotools macros

##### Key architecture insights from README
- mod_R is loaded at startup via Apache’s LoadModule directive.
- mod_R uses apxs to compile against Apache’s plugin ABI and links against R’s shared libR.so.
- Request handlers (r-info, r-script, r-handler) map URLs or directories to R functions or R script files.
- libapreq2 handles low-level HTTP request parsing.
- R must be built with –enable-R-shlib so mod_R can dlopen() R’s shared library.

a. Main components
- Apache HTTP Server (prefork MPM)
- mod_R module (in‐process plugin)
- libapreq2 library (C library loaded by mod_R)
- R runtime (shared library libR.so)
- R scripts or R packages (e.g., “brew::brew”)
- Client browsers or HTTP clients
- Packaging layers (Debian, RPM) – optional auxiliary component
b. Relationships & interactions
1. Client → Apache HTTP Server: standard HTTP request
2. Apache invokes mod_R hook for specific handlers (r-info, r-script, r-handler).
3. mod_R calls into libapreq2 to parse request params, cookies, uploads.
4. mod_R dlopen()s libR.so and initializes an R embedded session.
5. mod_R invokes R API to run designated R function or script.
6. R engine executes code and returns output (HTML/text/binary).
7. mod_R captures R’s output and writes it into Apache’s response buffers.
8. Apache sends HTTP response back to client.
c. Architectural patterns & principles
- Plugin architecture: mod_R as a dynamic module loaded into Apache’s prefork worker processes
- Layered integration: HTTP parsing separated (libapreq2) from business logic (R interpreter)
- Embedding/interpreter pattern: host process (Apache) embeds guest language runtime (R)
- Configuration-driven routing: Apache directives map URLs/directories to R handlers or scripts
d. Key technologies & libraries
- Apache 2.x API / apxs
- GNU autotools (autoconf, automake, libtool) for build system
- C99 / POSIX for mod_R and libapreq2 implementation
- Perl XS (glue/perl) to generate Perl bindings for libapreq2—useful for testing
- R shared library (libR.so) and R C API
- Debian packaging tools (debhelper) and RPM spec files

##### Essential elements to capture
- Entry & exit points (HTTP client ↔ Apache)
- Plugin hooks (LoadModule, SetHandler directives)
- In‐process integration between C module and R runtime
- Request parsing layer (libapreq2) separated from business logic
- Configuration & packaging aspects off the critical path

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client"
        Client["HTTP Client / Browser"]:::external
    end

    subgraph "Server Runtime"
        Apache["Apache HTTPD (prefork)"]:::server
        modR["mod_R.so"]:::server
        libapreq2["libapreq2.so"]:::server
    end

    subgraph "R Interpreter"
        Rruntime["R Runtime (libR.so)"]:::interpreter
    end

    subgraph "External Assets"
        Rscripts["R Scripts / Packages"]:::external_asset
    end

    subgraph "Build & Deploy"
        configure["configure"]:::packaging
        configureIn["configure.in"]:::packaging
        makefileAM["Makefile.am"]:::packaging
        makefileIn["Makefile.in"]:::packaging
        m4dir["m4/"]:::packaging
    end

    subgraph "Packaging"
        debian["debian/"]:::packaging
        rpm["rpm/"]:::packaging
    end

    subgraph "Tests & Tools"
        test["test/"]:::packaging
        tools["tools/"]:::packaging
    end

    Client -->|"HTTP request"| Apache
    Apache -->|"LoadModule & Hook"| modR
    modR -->|"parse request"| libapreq2
    modR -->|"dlopen & init"| Rruntime
    modR -->|"load script"| Rscripts
    Rscripts -->|"execute code"| Rruntime
    Rruntime -->|"return output"| modR
    modR -->|"response data"| Apache
    Apache -->|"HTTP response"| Client

    classDef server fill:#BBE1FA,stroke:#0288D1,color:#000
    classDef interpreter fill:#B0F2B6,stroke:#388E3C,color:#000
    classDef external_asset fill:#FFF3B0,stroke:#FBC02D,color:#000
    classDef packaging fill:#E0E0E0,stroke:#9E9E9E,color:#000
    classDef external fill:#F0F0F0,stroke:#757575,color:#000

    click modR "https://github.com/jeffreyhorner/rapache/blob/master/mod_R.c"
    click libapreq2 "https://github.com/jeffreyhorner/rapache/tree/master/libapreq2/include/"
    click configure "https://github.com/jeffreyhorner/rapache/tree/master/configure"
    click configureIn "https://github.com/jeffreyhorner/rapache/blob/master/configure.in"
    click makefileAM "https://github.com/jeffreyhorner/rapache/blob/master/Makefile.am"
    click makefileIn "https://github.com/jeffreyhorner/rapache/blob/master/Makefile.in"
    click m4dir "https://github.com/jeffreyhorner/rapache/tree/master/m4/"
    click debian "https://github.com/jeffreyhorner/rapache/tree/master/debian/"
    click rpm "https://github.com/jeffreyhorner/rapache/tree/master/rpm/"
    click test "https://github.com/jeffreyhorner/rapache/tree/master/test/"
    click tools "https://github.com/jeffreyhorner/rapache/tree/master/tools/"
```
