# cext-dan/pyrx architecture

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

- Interactive diagram: https://gitdiagram.com/cext-dan/pyrx
- Repository: https://github.com/cext-dan/pyrx

## Overview

1. **What this repo is**
   PyRx is a native C++ extension for CAD hosts, not a .NET layer. It embeds CPython 3.12 into loadable ARX/BRX/GRX/ZRX/IRX modules so Python code can run inside AutoCAD and compatible clones such as BricsCAD, GstarCAD, and ZwCAD.

2. **Top-level architecture**
   The repository is split into three main runtime layers:
   - **Native host modules** in `PyRxCore` and `PyRxLoader`
   - **Python package/API layer** in `pyrx`
   - **Samples, tests, and tooling** in `PySamples`, `tests`, and `pyrx/doc_utils`

3. **Native core binding layer**
   `PyRxCore` is the main binding implementation. It contains many C++ wrappers grouped by CAD API area: `Db`, `Ge`, `Ed`, `Ap`, `Ax`, `Gi`, `Gs`, `Pl`, `Sm`, plus BricsCAD/Civil/BIM-specific namespaces like `PyBrx`, `PyBrxCv`, `PyBrxBim`, and `PyBimCore`. These wrappers expose the host application's object model, geometry, editor, graphics, sheet set, and UI services to Python.

4. **Host-module entry points**
   The native modules are built around ARX-style entry points such as `acrxEntryPoint.cpp` and `dllmain.cpp`. The loader side in `PyRxLoader` is the thin bootstrap module that gets loaded by the CAD host and then initializes the embedded Python environment and PyRx runtime.

5. **Versioned host compatibility**
   The repo carries multiple project files and binaries for different CAD host versions and vendors, such as `PyRx24.2`, `PyRx25.0`, `PyRx26.0`, `PyRxV*`, `PyRxG*`, and `PyRxZ*`. This means compatibility is handled at the binary/module boundary, not by a single universal plugin.

6. **Python-facing API layer**
   The `pyrx` package is the public Python surface. It provides importable modules such as `pyrx.db`, `pyrx.ge`, `pyrx.ed`, `pyrx.ap`, `pyrx.repl`, and utility modules for commands, configuration, console integration, reloading, and typing support. The package also ships the generated host-specific extension binaries and startup helpers.

7. **Command and scripting flow**
   Once the CAD host loads the loader module, the runtime exposes commands like `PYLOAD`, `PYRELOAD`, `PYDEBUG`, `PYCMDPROMPT`, and `PYPIP`. The flow is: CAD host → native loader → embedded Python runtime → Python command/utility modules → CAD API wrappers. AutoLISP hooks are also provided for script-driven loading and inspection.

8. **UI and interactive tooling**
   GUI support is built around wxPython, with palette/dialog wrappers in the native layer and sample apps under `PySamples/wxPython`. This is a separate interaction boundary from the CAD database/editor APIs: UI code talks to the Python runtime, which then invokes CAD services through the bindings.

9. **Documentation and stub generation pipeline**
   `pyrx/doc_utils`, `gen_pyi.py`, and `PyRxStubs/docgen.py` indicate a documentation/stub-generation subsystem. It parses docstrings and metadata to produce `.pyi` stub files shipped in `pyrx/`, enabling autocomplete and type checking for the exposed CAD APIs.

10. **Samples as architectural coverage**
   `PySamples` is organized by API domain and scenario rather than by application. It includes command examples, database/entity manipulation, editor interactions, reactors, geometry utilities, Civil/BIM examples, wxPython apps, and small utility scripts. These samples are the primary reference for how the runtime pieces fit together.

11. **Test strategy**
   `tests/` is large and host-aware. It includes unit-style Python tests for the pure-Python helpers, plus CAD-integration tests that exercise the wrapped APIs against real DWG/DST/IFC/sample assets under `tests/media`. The test suite is structured by API area to mirror the module boundaries in `pyrx` and `PyRxCore`.

12. **Packaging and release boundary**
   Packaging is handled by standard Python build files (`pyproject.toml`, `setup.py`, `MANIFEST.in`) plus release workflows in GitHub Actions. The repo publishes a pip installable package (`cad-pyrx`) that includes the Python package, stub files, and the correct host-specific binaries.

13. **External dependencies that matter architecturally**
   The two major external runtime dependencies are the CAD host SDKs/APIs and wxPython. The repo also embeds third-party geometry/utilities in C++ headers such as `delaunator.h`, `concaveman.h`, and `nanoflann.hpp`, which support internal geometric operations exposed through the Python bindings.

14. **How to think about the diagram**
   A useful architecture diagram should show:
   - CAD application host at the top
   - Native loader modules as the entry point
   - Embedded Python runtime inside the host process
   - Native binding layer (`PyRxCore`) bridging Python to CAD SDK APIs
   - Public Python package (`pyrx`) and command/repl utilities on the Python side
   - Sample scripts and tests as consumers of the public API, not as separate runtime services

Main entry points: [`PyRxCore`](https://github.com/cext-dan/pyrx/tree/main/PyRxCore) (PyRxCore), [`pyrx`](https://github.com/cext-dan/pyrx/tree/main/pyrx) (pyrx), [`PyRxLoader`](https://github.com/cext-dan/pyrx/tree/main/PyRxLoader) (Loader), [`PySamples`](https://github.com/cext-dan/pyrx/tree/main/PySamples) (Samples)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_native["Native runtime"]
  node_cad_host(("CAD host<br/>external host"))
  node_rx_loader["Loader<br/>native bootstrap"]
  node_rx_core["PyRxCore<br/>native bindings"]
  node_host_entry["Entry points<br/>module init<br/>[acrxEntryPoint.cpp]"]
  node_api_db["DB wrappers<br/>CAD database<br/>[PyDbDatabase.cpp]"]
  node_api_ed["Editor wrappers<br/>CAD editor<br/>[PyEdInput.cpp]"]
  node_api_ge["Geometry wrappers<br/>geometry kernel<br/>[PyGeCurve3d.cpp]"]
  node_api_ui["UI wrappers<br/>ui bridge<br/>[PyUiPalette.cpp]"]
  node_api_brx["BricsCAD APIs<br/>vendor extensions<br/>[PyBrxCore.cpp]"]
end

subgraph group_grp_python["Python API"]
  node_pyrx_pkg["pyrx<br/>public package"]
  node_pkg_commands["Commands<br/>[commands.py]"]
  node_pkg_repl["REPL<br/>interactive shell"]
  node_pkg_utils["Runtime utils<br/>python helpers"]
  node_pkg_hostinit["Host init<br/>startup glue<br/>[_host_init.py]"]
end

subgraph group_grp_coverage["Coverage and tooling"]
  node_docgen["Stub gen<br/>docs pipeline"]
  node_samples["Samples<br/>usage examples"]
  node_tests["Tests"]
  node_stubs_pkg["Stubs<br/>typed API"]
end

subgraph group_grp_release["Packaging"]
  node_packaging["Packaging<br/>build/release<br/>[pyproject.toml]"]
  node_versioning["Versioning<br/>release metadata"]
end

node_cad_host -->|"loads"| node_rx_loader
node_rx_loader -->|"initializes"| node_rx_core
node_rx_core -->|"enters"| node_host_entry
node_rx_core -->|"exposes"| node_api_db
node_rx_core -->|"exposes"| node_api_ed
node_rx_core -->|"exposes"| node_api_ge
node_rx_core -->|"exposes"| node_api_ui
node_rx_core -->|"exposes"| node_api_brx
node_rx_loader -->|"boots"| node_pyrx_pkg
node_pyrx_pkg -->|"publishes"| node_pkg_commands
node_pyrx_pkg -->|"publishes"| node_pkg_repl
node_pyrx_pkg -->|"publishes"| node_pkg_utils
node_pyrx_pkg -->|"starts"| node_pkg_hostinit
node_pyrx_pkg -->|"ships"| node_stubs_pkg
node_docgen -->|"generates"| node_stubs_pkg
node_tests -->|"validates"| node_pyrx_pkg
node_samples -->|"consumes"| node_pyrx_pkg
node_samples -->|"exercises"| node_rx_core
node_packaging -->|"packages"| node_pyrx_pkg
node_versioning -->|"feeds"| node_packaging
node_tests -->|"integration"| node_rx_core

click node_rx_loader "https://github.com/cext-dan/pyrx/tree/main/PyRxLoader"
click node_rx_core "https://github.com/cext-dan/pyrx/tree/main/PyRxCore"
click node_host_entry "https://github.com/cext-dan/pyrx/blob/main/PyRxCore/acrxEntryPoint.cpp"
click node_api_db "https://github.com/cext-dan/pyrx/blob/main/PyRxCore/PyDbDatabase.cpp"
click node_api_ed "https://github.com/cext-dan/pyrx/blob/main/PyRxCore/PyEdInput.cpp"
click node_api_ge "https://github.com/cext-dan/pyrx/blob/main/PyRxCore/PyGeCurve3d.cpp"
click node_api_ui "https://github.com/cext-dan/pyrx/blob/main/PyRxCore/PyUiPalette.cpp"
click node_api_brx "https://github.com/cext-dan/pyrx/blob/main/PyRxCore/PyBrxCore.cpp"
click node_pyrx_pkg "https://github.com/cext-dan/pyrx/tree/main/pyrx"
click node_pkg_commands "https://github.com/cext-dan/pyrx/blob/main/pyrx/commands.py"
click node_pkg_repl "https://github.com/cext-dan/pyrx/tree/main/pyrx/repl"
click node_pkg_utils "https://github.com/cext-dan/pyrx/tree/main/pyrx/utils"
click node_pkg_hostinit "https://github.com/cext-dan/pyrx/blob/main/pyrx/_host_init.py"
click node_docgen "https://github.com/cext-dan/pyrx/tree/main/pyrx/doc_utils"
click node_samples "https://github.com/cext-dan/pyrx/tree/main/PySamples"
click node_tests "https://github.com/cext-dan/pyrx/tree/main/tests"
click node_stubs_pkg "https://github.com/cext-dan/pyrx/tree/main/pyrx/doc_utils/stubs"
click node_packaging "https://github.com/cext-dan/pyrx/blob/main/pyproject.toml"
click node_versioning "https://github.com/cext-dan/pyrx/tree/main/Version"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cad_host,node_rx_loader,node_rx_core,node_host_entry,node_api_db,node_api_ed,node_api_ge,node_api_ui,node_api_brx toneBlue
class node_pyrx_pkg,node_pkg_commands,node_pkg_repl,node_pkg_utils,node_pkg_hostinit toneAmber
class node_docgen,node_samples,node_tests,node_stubs_pkg toneMint
class node_packaging,node_versioning toneRose
```

## Components

### Native runtime

Loadable CAD host modules and C++ binding layer

- **CAD host**: external host · AutoCAD and compatible CAD applications that load the modules
- [Loader](https://github.com/cext-dan/pyrx/tree/main/PyRxLoader): native bootstrap · Thin host-loaded module that initializes embedded Python and the PyRx runtime · `PyRxLoader`
- [PyRxCore](https://github.com/cext-dan/pyrx/tree/main/PyRxCore): native bindings · Main C++ binding layer exposing CAD SDK APIs to Python · `PyRxCore`
- [Entry points](https://github.com/cext-dan/pyrx/blob/main/PyRxCore/acrxEntryPoint.cpp): module init · ARX-style entry points and DLL startup for host integration · `PyRxCore/acrxEntryPoint.cpp`
- [DB wrappers](https://github.com/cext-dan/pyrx/blob/main/PyRxCore/PyDbDatabase.cpp): CAD database · Database, object, entity, table, and transaction wrappers · `PyRxCore/PyDbDatabase.cpp`
- [Editor wrappers](https://github.com/cext-dan/pyrx/blob/main/PyRxCore/PyEdInput.cpp): CAD editor · Command, prompt, selection, reactor, and user interaction wrappers · `PyRxCore/PyEdInput.cpp`
- [Geometry wrappers](https://github.com/cext-dan/pyrx/blob/main/PyRxCore/PyGeCurve3d.cpp): geometry kernel · 2D/3D geometry, curves, surfaces, and spatial helpers · `PyRxCore/PyGeCurve3d.cpp`
- [UI wrappers](https://github.com/cext-dan/pyrx/blob/main/PyRxCore/PyUiPalette.cpp): ui bridge · Palette, plot, graphics, and transient drawing integration · `PyRxCore/PyUiPalette.cpp`
- [BricsCAD APIs](https://github.com/cext-dan/pyrx/blob/main/PyRxCore/PyBrxCore.cpp): vendor extensions · BricsCAD-specific core, BIM, and Civil wrappers · `PyRxCore/PyBrxCore.cpp`

### Python API

Public package surface and runtime helpers

- [pyrx](https://github.com/cext-dan/pyrx/tree/main/pyrx): public package · Importable Python package exposing the runtime API and helpers · `pyrx`
- [Commands](https://github.com/cext-dan/pyrx/blob/main/pyrx/commands.py): python commands · Command registration and command-side utilities such as load, reload, debug, and pip entry points · `pyrx/commands.py`
- [REPL](https://github.com/cext-dan/pyrx/tree/main/pyrx/repl): interactive shell · Interactive console and REPL helpers for in-host Python execution · `pyrx/repl`
- [Runtime utils](https://github.com/cext-dan/pyrx/tree/main/pyrx/utils): python helpers · Reload, decorators, test runner, and wx integration helpers · `pyrx/utils`
- [Host init](https://github.com/cext-dan/pyrx/blob/main/pyrx/_host_init.py): startup glue · Startup and host-specific initialization used when the package is imported inside the CAD process · `pyrx/_host_init.py`

### Coverage and tooling

Samples, tests, stub generation, and support tooling

- [Stub gen](https://github.com/cext-dan/pyrx/tree/main/pyrx/doc_utils): docs pipeline · Docstring parsing and .pyi stub generation for the exposed APIs · `pyrx/doc_utils`
- [Samples](https://github.com/cext-dan/pyrx/tree/main/PySamples): usage examples · Domain-organized scripts demonstrating commands, APIs, reactors, geometry, wxPython, and vendor extensions · `PySamples`
- [Tests](https://github.com/cext-dan/pyrx/tree/main/tests): integration tests · Host-aware tests plus pure-Python helper tests organized by API area · `tests`
- [Stubs](https://github.com/cext-dan/pyrx/tree/main/pyrx/doc_utils/stubs): typed API · Generated and shipped .pyi surfaces for the public Python modules · `pyrx/doc_utils/stubs`

### Packaging

Build, versioning, and release boundary

- [Packaging](https://github.com/cext-dan/pyrx/blob/main/pyproject.toml): build/release · Python packaging and release configuration for shipping host-specific binaries and the package · `pyproject.toml`
- [Versioning](https://github.com/cext-dan/pyrx/tree/main/Version): release metadata · Version templates and generated package metadata for releases · `Version`

## Connections

- CAD host → Loader: loads · The CAD application loads the thin bootstrap module
- Loader → PyRxCore: initializes · Loader brings up the native runtime and bridges to the core binding layer
- PyRxCore → Entry points: enters · Core module is anchored by native entry points and DLL startup
- PyRxCore → DB wrappers: exposes · Database and object model bindings
- PyRxCore → Editor wrappers: exposes · Editor, command, and interaction bindings
- PyRxCore → Geometry wrappers: exposes · Geometry and spatial bindings
- PyRxCore → UI wrappers: exposes · Graphics and palette/UI bindings
- PyRxCore → BricsCAD APIs: exposes · Vendor-specific BricsCAD/Civil/BIM bindings
- Loader → pyrx: boots · Loader prepares the embedded Python runtime used by the package
- pyrx → Commands: publishes · Command layer is part of the public Python surface
- pyrx → REPL: publishes · Interactive execution helpers are exposed to users
- pyrx → Runtime utils: publishes · Runtime utility helpers are available from the package
- pyrx → Host init: starts · Package includes host-specific initialization hooks
- pyrx → Stubs: ships · Typed stubs are distributed alongside the package
- Stub gen → Stubs: generates · Doc utilities generate and maintain the shipped stub files
- Tests → pyrx: validates · Tests exercise the public Python API and helper modules
- Samples → pyrx: consumes · Samples demonstrate the package as the user-facing entry point
- Samples → PyRxCore: exercises · Samples also drive CAD integration through the native bindings
- Packaging → pyrx: packages · Build configuration assembles the Python package and binaries
- Versioning → Packaging: feeds · Version templates support the release process
- Tests → PyRxCore: integration · Host-aware tests cover the native binding layer against real CAD assets
