# um-bridge/umbridge architecture

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

- Interactive diagram: https://gitdiagram.com/um-bridge/umbridge
- Repository: https://github.com/um-bridge/umbridge

## Overview

##### Project type and purpose
- UM-Bridge is a protocol-driven, language-agnostic “model-server” framework.
- It exposes numerical models (C++, Python, Julia, etc.) via HTTP so that any client (R, Python, C++, MATLAB, Julia, Muq) can call them in a uniform way.
- It also provides deployment scripts (HPC, Kubernetes), clients in many languages, CI workflows, benchmarks, and protocol‐conformance tests.

##### File structure
- Top-level “umbridge/” directory: the core Python package implementing the client-side protocol.
- “clients/” subfolders: example clients in R, C++, Python, MATLAB, Julia, Muq.
- “models/”: template minimal servers in C++, Python, Julia plus Dockerfiles.
- “hpc/”: LoadBalancer code, SLURM scripts, helper scripts for high-throughput cluster deployment.
- “kubernetes/”: YAMLs and launch scripts for containerized, multi-node, MPI model deployments.
- “benchmarks/”: testbenchmark server and Dockerfile for UQ benchmarking.
- “testing/”: protocol-conformity tests for versions 0.9 and 1.0, plus client‐side unit tests.
- CI workflows in “.github/workflows” orchestrate build, test, documentation, and multi-language client package releases.
- “R/” subtree: R wrapper package.
- “lib/”: low-level HTTP utility headers (httplib, JSON, umbridge.h).
- “setup.py”: Python packaging entry point.

##### Key architecture insights from README
- UM-Bridge’s core goal is “coupling advanced models … to statistical or optimization methods” via a unified HTTP interface.
- It is designed as a modular, client–server system with clearly defined protocol versions.

##### Final advice
- Break the overall system into these subsystems and show how they interconnect.
- Be exhaustive: include each language client, each deployment mode, each test/benchmark component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        PythonSDK["Python SDK"]:::client
        PythonExamples["Python Example Scripts"]:::client
        RSDK["R SDK"]:::client
        CPPExample["C++ Example"]:::client
        MatlabSDK["MATLAB SDK"]:::client
        JuliaExample["Julia Example"]:::client
        MuqExample["Muq Example"]:::client
    end

    %% Transport Layer
    subgraph "Transport Layer"
        direction TB
        HTTPProtocol["HTTP Protocol"]:::transport
        JSONPayloads["JSON Payloads"]:::data
        ProtocolVersions["Protocol Versions (0.9,1.0)"]:::transport
    end

    %% Core Server Layer
    subgraph "Core Server Layer"
        direction TB
        CPPServer["C++ Minimal Server"]:::server
        PythonServer["Python Minimal Server"]:::server
        JuliaServer["Julia Minimal Server"]:::server
    end

    %% Deployment / Orchestration
    subgraph "Deployment / Orchestration"
        direction TB
        HPC["HPC LoadBalancer & SLURM"]:::orchestration
        Kubernetes["Kubernetes Manifests & Launch Scripts"]:::orchestration
        DockerImages["Docker Images"]:::orchestration
    end

    %% CI / Testing / Benchmarking
    subgraph "CI / Testing / Benchmarking"
        direction TB
        CIWorkflows["GitHub Actions Workflows"]:::ci
        ProtocolTests["Protocol-Conformity Tests"]:::ci
        Benchmark["Benchmark Harness"]:::ci
        Packaging["Python Packaging (setup.py)"]:::ci
    end

    %% Data Flows
    PythonSDK -->|HTTP Request| HTTPProtocol
    PythonExamples -->|HTTP Request| HTTPProtocol
    RSDK -->|HTTP Request| HTTPProtocol
    CPPExample -->|HTTP Request| HTTPProtocol
    MatlabSDK -->|HTTP Request| HTTPProtocol
    JuliaExample -->|HTTP Request| HTTPProtocol
    MuqExample -->|HTTP Request| HTTPProtocol

    HTTPProtocol -->|JSON Payloads| JSONPayloads
    JSONPayloads -->|Delivered to| CPPServer
    JSONPayloads -->|Delivered to| PythonServer
    JSONPayloads -->|Delivered to| JuliaServer

    CPPServer -->|JSON Response| JSONPayloads
    PythonServer -->|JSON Response| JSONPayloads
    JuliaServer -->|JSON Response| JSONPayloads
    JSONPayloads -->|HTTP Response| PythonSDK

    CPPServer -->|Containerized| DockerImages
    PythonServer -->|Containerized| DockerImages
    JuliaServer -->|Containerized| DockerImages

    DockerImages -->|Deploy| HPC
    DockerImages -->|Deploy| Kubernetes

    CIWorkflows -.->|Build & Test| DockerImages
    CIWorkflows -.->|Run| ProtocolTests
    CIWorkflows -.->|Run| Benchmark
    CIWorkflows -.->|Publish| Packaging

    %% Click Events
    click PythonSDK "https://github.com/um-bridge/umbridge/blob/main/umbridge/__init__.py"
    click PythonExamples "https://github.com/um-bridge/umbridge/blob/main/clients/python/umbridge-client.py"
    click RSDK "https://github.com/um-bridge/umbridge/tree/main/R/DESCRIPTION"
    click CPPExample "https://github.com/um-bridge/umbridge/blob/main/clients/c++/http-client.cpp"
    click MatlabSDK "https://github.com/um-bridge/umbridge/blob/main/matlab/@HTTPModel/HTTPModel.m"
    click JuliaExample "https://github.com/um-bridge/umbridge/blob/main/clients/julia/juliaClient.jl"
    click MuqExample "https://github.com/um-bridge/umbridge/blob/main/clients/muq/HTTPModPieceClientMCMCPoisson.cpp"
    click HTTPProtocol "https://github.com/um-bridge/umbridge/blob/main/lib/httplib.h"
    click JSONPayloads "https://github.com/um-bridge/umbridge/blob/main/lib/json.hpp"
    click ProtocolVersions "https://github.com/um-bridge/umbridge/blob/main/lib/umbridge.h"
    click CPPServer "https://github.com/um-bridge/umbridge/blob/main/models/testmodel/minimal-server.cpp"
    click PythonServer "https://github.com/um-bridge/umbridge/blob/main/models/testmodel-python/minimal-server.py"
    click JuliaServer "https://github.com/um-bridge/umbridge/blob/main/models/testmodel-julia/minimal-server.jl"
    click HPC "https://github.com/um-bridge/umbridge/blob/main/hpc/LoadBalancer.cpp"
    click Kubernetes "https://github.com/um-bridge/umbridge/blob/main/kubernetes/model.yaml"
    click CIWorkflows "https://github.com/um-bridge/umbridge/blob/main/.github/workflows/testing-protocol-conformity-0.9.yml"
    click ProtocolTests "https://github.com/um-bridge/umbridge/tree/main/testing/protocol_conformity_0.9/"
    click Benchmark "https://github.com/um-bridge/umbridge/blob/main/benchmarks/testbenchmark/benchmark-server.py"
    click Packaging "https://github.com/um-bridge/umbridge/blob/main/setup.py"

    %% Styles
    classDef client fill:#AED6F1,stroke:#1F618D,color:#1B4F72;
    classDef transport fill:#A9DFBF,stroke:#196F3D,color:#145A32;
    classDef server fill:#F5B041,stroke:#B9770E,color:#7E5109;
    classDef orchestration fill:#BB8FCE,stroke:#6C3483,color:#4A235A;
    classDef ci fill:#D5DBDB,stroke:#5D6D7E,color:#1C2833;
    classDef data fill:#E8DAEF,stroke:#7D3C98,color:#4A235A;
```
