# ubolonton/denopy architecture

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

- Interactive diagram: https://gitdiagram.com/ubolonton/denopy
- Repository: https://github.com/ubolonton/denopy

## Overview

##### Project Type & Purpose
- The project is an inter-language bridging tool that lets Python run JavaScript code by embedding the deno_core engine.
- Its primary purpose is to provide a runtime (through denopy.Runtime) that executes blocking JavaScript calls from Python. It deliberately avoids async/await to simplify the integration across three languages (Python, Rust, and JavaScript).

##### File Structure
- Key Directories/Files:
- src: Contains the Rust source code, including the core logic in lib.rs and type definitions in types.rs.
- tests: Contains Python-based test scripts that exercise the functionality (calls, properties, threading, types).
- Cargo.toml and Cargo.lock: Define the Rust project dependencies and configuration.
- pyproject.toml: Likely configures the Python part (could be for packaging or building the native binding).
- .github/workflows/main.yml: Represents the CI pipeline for automated builds and tests.
- The existence of both Rust and Python configuration files indicates the project is a hybrid system (a Rust-based native extension with a Python interface).

##### Main Components
a. Python API Layer:
- Represents the user-facing module (denopy) with classes such as Runtime.
- Acts as the interface that Python code calls (as shown in the example in the README).
b. Rust Binding & Core:
- The Rust library serves as the binding layer, connecting the Python API with the underlying deno_core.
- This layer includes:
- The primary logic (in lib.rs) which likely wraps and configures deno_core.
- Type definitions (in types.rs) and additional business logic.
c. JavaScript Engine (deno_core / V8):
- Although not a separate codebase, this component is crucial. It is embedded by the Rust code and actually executes the JavaScript code.
d. Testing and CI:
- The tests directory (Python-based tests) that verify the correctness of API calls, property handling, threading, and type conversions.
- CI configuration under .github/workflows for continuous integration, ensuring the build and binding remain stable.

##### Relationships & Data Flow
- Python Application Code calls methods on the denopy.Runtime class.
- The Python code is handed off to the Rust binding (exposed as a native extension via a mechanism like PyO3 or cffi).
- The Rust layer interacts with deno_core (and by extension with V8) to evaluate the JavaScript.
- Results from the JavaScript execution flow back up through the Rust layer and return to the Python application.
- Tests verify each of these interactions, ensuring proper communication, type conversions, and error handling.

##### Architectural Patterns
- Layered Architecture: The division between the Python API, Rust binding, and the underlying JavaScript engine shows clear separation of concerns.
- Binding/Interop Pattern: Emphasis is on providing a seamless interface across two different runtime environments (Python and Rust/deno_core).
- CI/CD Integration: Automated test pipelines are in place for maintaining code quality.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Python API Layer
    subgraph "Python API Layer"
        PythonRuntime["denopy.Runtime"]:::python
    end

    %% Rust Binding Layer
    subgraph "Rust Binding Layer"
        LibRs["lib.rs"]:::rust
        TypesRs["types.rs"]:::rust
    end

    %% JavaScript Engine
    JS["deno_core/V8 Engine"]:::js

    %% Test Suite
    subgraph "Test Suite"
        T1["test_calls.py"]:::test
        T2["test_properties.py"]:::test
        T3["test_threading.py"]:::test
        T4["test_types.py"]:::test
    end

    %% CI Pipeline
    CI["CI Pipeline"]:::ci

    %% Rust Project Configuration
    subgraph "Rust Configuration"
        CargoToml["Cargo.toml"]:::config
        CargoLock["Cargo.lock"]:::config
    end

    %% Dataflow Connections
    PythonRuntime -->|"calls"| LibRs
    LibRs -->|"evaluates"| JS
    JS -->|"returns"| LibRs
    LibRs -->|"sends_result"| PythonRuntime

    %% Test Suite Interaction
    T1 ---|"validates"| PythonRuntime

    %% CI Pipeline Triggers & Monitoring
    CI -->|"triggers"| T1
    CI -->|"monitors"| CargoToml
    CI -->|"monitors"| CargoLock

    %% Click Events
    click PythonRuntime "https://github.com/ubolonton/denopy/blob/main/pyproject.toml"
    click LibRs "https://github.com/ubolonton/denopy/blob/main/src/lib.rs"
    click TypesRs "https://github.com/ubolonton/denopy/blob/main/src/types.rs"
    click T1 "https://github.com/ubolonton/denopy/blob/main/tests/test_calls.py"
    click T2 "https://github.com/ubolonton/denopy/blob/main/tests/test_properties.py"
    click T3 "https://github.com/ubolonton/denopy/blob/main/tests/test_threading.py"
    click T4 "https://github.com/ubolonton/denopy/blob/main/tests/test_types.py"
    click CI "https://github.com/ubolonton/denopy/blob/main/.github/workflows/main.yml"
    click CargoToml "https://github.com/ubolonton/denopy/blob/main/Cargo.toml"
    click CargoLock "https://github.com/ubolonton/denopy/blob/main/Cargo.lock"

    %% Styles
    classDef python fill:#a2d2ff,stroke:#000,stroke-width:2px;
    classDef rust fill:#ffaf87,stroke:#000,stroke-width:2px;
    classDef js fill:#ffd966,stroke:#000,stroke-width:2px;
    classDef test fill:#c9daf8,stroke:#000,stroke-width:2px;
    classDef ci fill:#f9cb9c,stroke:#000,stroke-width:2px;
    classDef config fill:#d9d2e9,stroke:#000,stroke-width:2px;
```
