# prl-prg/r-compile-server architecture

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

- Interactive diagram: https://gitdiagram.com/prl-prg/r-compile-server
- Repository: https://github.com/prl-prg/r-compile-server

## Overview

##### Project type and purpose
- This is a distributed R-compiler system:
- A thin R “client” (an R package + C++ shim) that submits R code to be compiled.
- A Java-based “server” that implements a gRPC service to compile or JIT R code through multiple internal stages (bytecode, FIR, C, native code).
- An external R interpreter (submodule) that the server invokes when needed.
- Its purpose is to allow remote or embedded compilation of R code (e.g. for benchmarking, JIT, or ahead-of-time compilation) in a reproducible containerized environment.

##### File structure
- Top-level directories:
- client/      ⇒ R package “rsh” + C++ code + Rbenchmarks + tests
- proto/       ⇒ .proto definitions for messages & services
- server/      ⇒ Java + Maven multi-module project implementing gRPC compile server
- external/    ⇒ R source tree submodule for embedding/interfacing
- tools/, .devcontainer/ ⇒ build scripts, container config
- Within server/src/main/java: many packages implementing a compiler pipeline (bc, bc2c, bc2fir, fir, fir/analyze, fir/opt, parseprint, sexp, rds, session, service).
- Configuration & build: Makefile, Maven (“pom.xml”), Dockerfile, devcontainer.json, git hooks, CI workflow (maven.yml).

##### README for additional insights
- Describes dev workflows (devcontainer, IntelliJ, Maven), dependency on Java-24, R submodule, code formatting, etc.

##### Details
- Every major module from the file tree (client/src, proto, server/src/main/java org.prlprg.* packages, external/R).
- How protocol buffers definitions under proto/ propagate into both client and server folders.
- Compile pipeline order (bytecode → intermediate → native) is visually clear.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% R Client Layer
    subgraph "R Client Layer"
        direction TB
        RScripts["R Scripts / User Code"]:::client
        RPackage["rsh R Package"]:::client
        CppShim["C++ Shim"]:::client
    end

    %% Transport Layer
    subgraph "gRPC Transport"
        direction TB
        ProtoDefs["Protocol Buffers Definitions"]:::transport
        GRPCStub["gRPC Stubs (client)"]:::transport
    end

    %% Compile Server
    subgraph "Compile Server (Java)"
        direction TB
        Entrypoint["CompileServer & CompileService"]:::server
        Session["Session Management"]:::server
        BC["Bytecode Compiler (BCCompiler)"]:::server
        BC2FIR["BC → FIR Compiler"]:::server
        FIR["FIR Pipeline"]:::server
        BC2C["C-Code Generator (BC2C)"]:::server
        RDS["Serialization (RDS Reader/Writer)"]:::server
    end

    %% External & Resources
    subgraph "External & Resources"
        direction TB
        ExternalR["External R Runtime"]:::external
        Resources["Static Resources (builtins.fir, intrinsics.fir, RDS)"]:::external
    end

    %% CI / Dev Container
    subgraph "CI & Dev Container"
        direction TB
        DevContainer[".devcontainer/Dockerfile & config"]:::ci
        CIWorkflow["GitHub Actions & Makefile"]:::ci
    end

    %% Connections
    RScripts -->|"calls"| RPackage
    RPackage -->|"invokes"| CppShim
    CppShim -->|"RPC call"| GRPCStub
    ProtoDefs -->|"defines messages/services"| GRPCStub

    GRPCStub -->|"gRPC Request"| Entrypoint
    Entrypoint -->|"create session"| Session
    Session -->|"load bytecode"| BC
    BC -->|"emit BC IR"| BC2FIR
    BC2FIR -->|"emit FIR"| FIR
    FIR -->|"optimize/check/interpret"| BC2C
    BC2C -->|"emit C / JIT"| RDS
    RDS -->|"encode results"| CppShim
    Entrypoint -->|"invoke R"| ExternalR
    Session -->|"load resources"| Resources

    %% Click Events
    click RPackage "https://github.com/prl-prg/r-compile-server/tree/main/client/rsh"
    click CppShim "https://github.com/prl-prg/r-compile-server/tree/main/client/rsh/src"
    click ProtoDefs "https://github.com/prl-prg/r-compile-server/blob/main/proto/messages.proto"
    click ProtoDefs "https://github.com/prl-prg/r-compile-server/blob/main/proto/routes.proto"
    click GRPCStub "https://github.com/prl-prg/r-compile-server/tree/main/client/rsh/src"
    click Entrypoint "https://github.com/prl-prg/r-compile-server/blob/main/server/src/main/java/org/prlprg/server/CompileServer.java"
    click Entrypoint "https://github.com/prl-prg/r-compile-server/blob/main/server/src/main/java/org/prlprg/server/CompileService.java"
    click Session "https://github.com/prl-prg/r-compile-server/tree/main/server/src/main/java/org/prlprg/session"
    click BC "https://github.com/prl-prg/r-compile-server/tree/main/server/src/main/java/org/prlprg/bc"
    click BC2FIR "https://github.com/prl-prg/r-compile-server/tree/main/server/src/main/java/org/prlprg/bc2fir"
    click FIR "https://github.com/prl-prg/r-compile-server/tree/main/server/src/main/java/org/prlprg/fir"
    click BC2C "https://github.com/prl-prg/r-compile-server/tree/main/server/src/main/java/org/prlprg/bc2c"
    click RDS "https://github.com/prl-prg/r-compile-server/tree/main/server/src/main/java/org/prlprg/rds"
    click ExternalR "https://github.com/prl-prg/r-compile-server/tree/main/external/R"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0366d6,stroke-width:1px;
    classDef transport fill:#E0FFD8,stroke:#228B22,stroke-width:1px;
    classDef server fill:#FFE0B2,stroke:#FF8C00,stroke-width:1px;
    classDef external fill:#F0F0F0,stroke:#666666,stroke-width:1px;
    classDef ci fill:#F5F5F5,stroke:#999999,stroke-width:1px;
```
