# loreneteval/xray-core-python architecture

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

- Interactive diagram: https://gitdiagram.com/loreneteval/xray-core-python
- Repository: https://github.com/loreneteval/xray-core-python

## Overview

##### Project Type and Purpose
- This is a language‐binding library rather than a standalone service. Specifically, it exposes the Xray-core (Go) networking engine to Python via a C++ wrapper using pybind11.
- Users install the package with pip, triggering a build pipeline that compiles the Go core, wraps it in a C++ extension, and produces a Python importable module (`xray`).

##### Architectural Overview
- At a high level the system has two phases:
a. Build‐time pipeline: orchestrated by CMake+setup.py+gobuild, which
- Invokes Go toolchain to compile the Xray-core (`xray-go` directory) into a static library or object files.
- Invokes CMake to find pybind11 headers and compile `src/xray.cpp` into a Python extension module (`xray.so` / `xray.pyd`), linking against the Go artifacts.
b. Runtime interaction:
- Python code (`import xray`) calls into the pybind11 extension.
- The extension invokes C++ glue code (in `src/xray.cpp`) which in turn calls exported Go functions.
- The Go core executes networking logic and returns results back to Python.

##### Main Components
- Python Layer
- `xray/__init__.py`: Python package exposing the extension.
- User API: `startFromJSON(...)`, `queryStats(...)`.
- C++/pybind11 Wrapper
- `src/xray.cpp`: defines Python-callable functions, binds to Go functions.
- `pybind11/`: vendored pybind11 library and config for building.
- Go Core
- `xray-go/`: full Xray-core source with its subpackages (app, common, proxy, transport, etc.).
- Exposes C-callable functions via cgo or a small C wrapper.
- Build System
- `CMakeLists.txt` (root) and `gobuild/`: coordinates:
– Discovery of Go toolchain.
– Compilation of Go code to static libs.
– Compilation of C++ extension with pybind11.
- `setup.py` / `pyproject.toml`: Python packaging metadata, invokes CMake during pip install.
- External Tools
- Go compiler
- CMake
- GNU C++ toolchain
- pip / setuptools

##### Relationships and Data Flow
[pip install] → [setup.py / pyproject.toml] → [CMake] → {Go compiler → Xray-core lib} + {C++ compiler + pybind11 → Python extension}
[Python app] → [pybind11 extension (xray.so)] → [C++ glue (xray.cpp)] → [Go core functions] → [return results back up]

##### Key Architectural Patterns
- Layered binding pattern: Python → C++ → Go
- Decoupled build stages: Go build and C++ build are separate targets in CMake.
- Vendored library structure: pybind11 lives inside project, isolated from system.

##### Essential Elements
- Build orchestration (pip → setup → CMake → compilers).
- Python API module and exposed methods.
- C++ wrapper code (pybind11).
- Go core library.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build-Time Pipeline
    subgraph "Build-Time Pipeline"
        direction TB
        Pip["pip install"]:::buildTool
        SetupPY["setup.py"]:::buildTool
        PyProj["pyproject.toml"]:::buildTool
        CMake["CMake"]:::buildTool
        CMakeLists["CMakeLists.txt"]:::buildTool
        Gobuild["gobuild/"]:::buildTool
        Goc["Go compiler"]:::buildTool
        CppComp["C++ compiler"]:::buildTool
        PybindVend["pybind11/"]:::buildTool

        Pip -->|"invokes"| SetupPY
        Pip -->|"reads"| PyProj
        SetupPY -->|"calls"| CMake
        PyProj -->|"configures"| CMake
        CMakeLists -->|".txt definitions"| CMake
        CMake -->|"invoke gobuild"| Gobuild
        Gobuild -->|"compile Go code"| Goc
        Goc -->|"produce static lib"| XrayLib
        CMake -->|"compile C++ extension"| CppComp
        CppComp -->|"use headers from"| PybindVend
        CppComp -->|"produce extension"| XrayExt
        XrayLib -->|"link against"| XrayExt

        click SetupPY "https://github.com/loreneteval/xray-core-python/blob/main/setup.py"
        click PyProj "https://github.com/loreneteval/xray-core-python/blob/main/pyproject.toml"
        click CMakeLists "https://github.com/loreneteval/xray-core-python/blob/main/CMakeLists.txt"
        click Gobuild "https://github.com/loreneteval/xray-core-python/tree/main/gobuild/"
        click PybindVend "https://github.com/loreneteval/xray-core-python/tree/main/pybind11/"
    end

    %% Build Artifacts
    XrayLib["xray_go_lib (static lib)"]:::artifact
    XrayExt["xray_python_extension (xray.so/.pyd)"]:::artifact

    %% Runtime Interaction
    subgraph "Runtime Interaction"
        direction TB
        PyApp["Python Application"]:::runtime
        PythonLayer["xray/__init__.py"]:::runtime
        ExtModule["pybind11 extension (xray.so)"]:::runtime
        CppGlue["C++ glue (src/xray.cpp)"]:::runtime
        GoCore["Go core (xray-go/)"]:::runtime

        PyApp -->|"import xray"| PythonLayer
        PythonLayer -->|"loads extension"| ExtModule
        ExtModule -->|"call bound functions"| CppGlue
        CppGlue -->|"invoke C functions"| GoCore
        GoCore -->|"return results"| CppGlue
        CppGlue -->|"return to Python"| ExtModule
        ExtModule -->|"return results"| PythonLayer
        PythonLayer -->|"provide API to app"| PyApp

        click PythonLayer "https://github.com/loreneteval/xray-core-python/blob/main/xray/__init__.py"
        click CppGlue "https://github.com/loreneteval/xray-core-python/blob/main/src/xray.cpp"
        click GoCore "https://github.com/loreneteval/xray-core-python/tree/main/xray-go/"
    end

    %% Styles
    classDef buildTool fill:#FFA500,stroke:#333,stroke-width:1px
    classDef runtime fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef artifact fill:#D3D3D3,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
