# xpn-arcos/xpn architecture

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

- Interactive diagram: https://gitdiagram.com/xpn-arcos/xpn
- Repository: https://github.com/xpn-arcos/xpn

## Overview

##### Project type and purpose
- XPN (“Expand Ad‑Hoc Parallel File System”) is an open‑source, MPI‑based parallel file system and I/O middleware.
- It provides a user‑level, POSIX‑compatible file interface via LD_PRELOAD (xpn_bypass), plus optional FUSE and MPI‑IO connectors, to a set of MPI‑based server processes that stripe and store file data on per‑node local storage.

##### File structure
- Top‑level modules:
- src/xpn_server: the MPI‑based server implementation
- src/xpn_client + include/xpn_client: the client libraries (bypass, policy, core) and MPI socket or message‑queue stubs
- src/base + include/base: foundational utilities (networking, threading, profiling) shared by client & server
- src/bypass + include/bypass: LD_PRELOAD library that intercepts POSIX calls
- src/connector_fuse, src/connector_romio: optional adapters (FUSE mount, MPI‑IO integration)
- src/utils: user utilities (xpn‑ls, xpn‑cp, xpn_expand, etc.)
- src/mq_server: standalone message queue server support
- admire/io‑scheduler: experimental scheduling plugin
- scripts/execute, scripts/compile, scripts/spack: deployment & build automation
- Config & build:
- xpn.conf (example in info/xpn.conf.example) plus hostfile for MPI
- Autotools / CMake build infrastructure (configure.ac, Makefile.am, CMakeLists.txt)
- Docker, Spack recipe for packaging/deployment

##### README for additional insights
- Architecture: three‑step execution (1. generate xpn.conf, 2. start servers, 3. launch client).
- Communication: clients (LD_PRELOAD or mpiexec) talk to servers via TCP sockets or MPI messaging.
- Deployment: supports MPICH and OpenMPI, cluster launch via mpiexec or prte.

##### Elements
- Labels:
- “Configuration Manager” (mk_conf.sh, xpn.sh)
- “MPI Servers” (xpn_server)
- “NODE_DIR” (local filesystem)
- “LD_PRELOAD Bypass” (xpn_bypass.so)
- “User App or MPI App”
- “FUSE Connector”
- “Shared WORK_DIR (hostfile, xpn.conf)”
- “External S3 Service (optional)”
- Config ﬂow (script → xpn.conf)
- Control ﬂow (launcher → servers → client → stop)
- Data ﬂow (client bypass → server → local disk)
- Side‑path to S3 via stage_cloud
- Orange for optional connectors

##### Final advice
- Be explicit about which processes run where (per‑node MPI server vs. client process)
- Both control (start/stop) and data (read/write) flows
- Don’t omit supporting libraries (base, bypass) that glue the system together
- You show pluggability: how new connectors or scheduling plugins fit in

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Phase
    subgraph "Configuration Phase"
        ConfigManager["Configuration Manager\n(mk_conf.sh, xpn.sh)"]:::scripts
        SharedConf["Shared WORK_DIR\n(hostfile, xpn.conf)"]:::scripts
        ConfigManager -->|"generates"| SharedConf
    end

    %% Server Launch Phase
    subgraph "Server Launch Phase"
        MPIStart["mpiexec: start XPN Servers"]:::scripts
        MQServerStart["mq_server.sh"]:::scripts
        Servers["MPI Servers\n(xpn_server)"]:::core
        MPIStart --> Servers
        MQServerStart --> Servers
        Servers -->|"read config"| SharedConf
    end

    %% Client Runtime Phase
    subgraph "Client Runtime Phase"
        UserApp["User App / MPI App"]:::core
        Bypass["LD_PRELOAD Bypass\n(xpn_bypass.so)"]:::core
        ClientLib["XPN Client Libraries"]:::core
        BaseLib["Base Utilities\n(src/base)"]:::core
        Utils["User Utilities\n(src/utils)"]:::core
        FUSE["FUSE Connector"]:::optional
        ROMIO["MPI-IO Connector"]:::optional
        CloudScript["stage_cloud scripts"]:::scripts
        S3["External S3 Service"]:::external
        NodeDir["NODE_DIR\n(local storage)"]:::storage

        UserApp -->|"LD_PRELOAD"| Bypass
        Bypass -->|"calls"| Servers
        Bypass -->|"uses"| ClientLib
        ClientLib -->|"depends on"| BaseLib
        Utils -.->|"+bypass"| Bypass
        FUSE -.-> Servers
        ROMIO -.-> Servers
        CloudScript -->|"stage data"| S3
        CloudScript --> SharedConf
        Servers -->|"reads/writes blocks"| NodeDir
    end

    %% Click Events
    click Servers "https://github.com/xpn-arcos/xpn/tree/master/src/xpn_server/"
    click Servers "https://github.com/xpn-arcos/xpn/tree/master/include/xpn_server/"
    click ClientLib "https://github.com/xpn-arcos/xpn/tree/master/src/xpn_client/"
    click ClientLib "https://github.com/xpn-arcos/xpn/tree/master/include/xpn_client/"
    click BaseLib "https://github.com/xpn-arcos/xpn/tree/master/src/base/"
    click BaseLib "https://github.com/xpn-arcos/xpn/tree/master/include/base/"
    click Bypass "https://github.com/xpn-arcos/xpn/tree/master/src/bypass/"
    click Bypass "https://github.com/xpn-arcos/xpn/tree/master/include/bypass/"
    click FUSE "https://github.com/xpn-arcos/xpn/tree/master/src/connector_fuse/"
    click ROMIO "https://github.com/xpn-arcos/xpn/tree/master/src/connector_romio/"
    click Utils "https://github.com/xpn-arcos/xpn/tree/master/src/utils/"
    click MQServerStart "https://github.com/xpn-arcos/xpn/blob/master/scripts/execute/mq_server.sh"
    click ConfigManager "https://github.com/xpn-arcos/xpn/blob/master/scripts/execute/mk_conf.sh"
    click ConfigManager "https://github.com/xpn-arcos/xpn/blob/master/scripts/execute/xpn.sh"
    click ConfigManager "https://github.com/xpn-arcos/xpn/blob/master/scripts/execute/sck_server.sh"
    click MPIStart "https://github.com/xpn-arcos/xpn/blob/master/scripts/execute/xpn_start.cfg"
    click SharedConf "https://github.com/xpn-arcos/xpn/blob/master/info/xpn.conf.example"
    click compile "https://github.com/xpn-arcos/xpn/tree/master/scripts/compile/"
    click spack "https://github.com/xpn-arcos/xpn/tree/master/scripts/spack/"
    click autotools1 "https://github.com/xpn-arcos/xpn/blob/master/configure.ac"
    click autotools2 "https://github.com/xpn-arcos/xpn/blob/master/Makefile.am"
    click autotools3 "https://github.com/xpn-arcos/xpn/tree/master/config/"
    click autotools4 "https://github.com/xpn-arcos/xpn/blob/master/CMakeLists.txt"

    %% Styles
    classDef core fill:#a2fca2,stroke:#333,stroke-width:1px
    classDef scripts fill:#a2d4ff,stroke:#333,stroke-width:1px
    classDef optional fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef external fill:#d9d9d9,stroke:#333,stroke-width:1px
    classDef storage fill:#e0e0e0,stroke:#333,stroke-width:1px,shape:cylinder
```
