# stewori/jyni architecture

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

- Interactive diagram: https://gitdiagram.com/stewori/jyni
- Repository: https://github.com/stewori/jyni

## Overview

##### Project type and purpose
- JyNI is a middleware/library project (open-source tool) bridging Jython (Java-based Python) with native CPython extensions (C libraries).
- It allows users to load standard CPython C-extensions (e.g., ctypes, NumPy) into Jython without recompilation.

##### File-structure analysis
- Top level:
- JyNI-C       – Core C implementation of Python C-API shims and adapters
- JyNI-Java    – Java classes (JyNI.jar) exposing native functions to Jython via JNI
- JyNI-Lib     – Python-side modules to hook into Jython’s import system, ctypes, sqlite3, etc.
- JyNI-Loader  – Low-level C loader that sets up the JNI environment and loads libJyNI
- DemoExtension, JyNI-Demo, JyNI-Java tests – Example/test extensions and scripts
- makefile*    – Build scripts for various platforms
- Patterns:
- JNI boundary between Java and C
- Adapter pattern for wrapping/mirroring Jython objects to CPython structures
- Plugin-style loading of native modules via JyNI-Loader

##### Key points from README
- Architecture overview (Java ⇄ C boundary, Python C API coverage)
- Garbage-collection bridging between reference counting (C) and mark-and-sweep (Java)
- Build and install steps for different OSes

– Operating system / dynamic loader [grey layer under C]

– Python script (in Jython) → Jython core → import hook (JyNI-Lib) → calls into JyNI-Java
– JyNI-Java invokes JNI → JyNI-Loader → loads libJyNI
– libJyNI implements Python C API calls → marshals to Jython via JNI callbacks
– libJyNI loads CPython extension modules → extension code calls PyObject_* → routed back to libJyNI → JNI → Jython
– GC integration: Java GC signals → JyNI-Loader / libJyNI reconciles reference counts

c. Architectural patterns & design principles
– Adapter: wraps CPython API to Jython implementations
– Mirror vs. wrapper modes for built-in types (immutable vs. mutable)
– Plugin/loader abstraction for cross-platform dynamic loading
– Separation of concerns: Python-side, Java-side, C-side layers

d. Key technologies/frameworks
– Java (Jython 2.7.1)
– C (GCC/Clang/MSVC) with JNI headers
– Python (Jython’s import machinery and CPython 2.7 headers)
– Makefiles for cross-platform builds

##### Detail reminders
- Sub-layer (Loader vs. Core C shim) distinctly
- Demo/test extension as an example plugin
- Build time vs. runtime components if space allows

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Python Layer
    subgraph "Python Layer"
        direction TB
        PyScript["Python Script"]:::python
        JyNI_Lib["JyNI-Lib Modules<br/>(import hook, ctypes, sqlite3)"]:::python
    end

    %% Java Layer
    subgraph "Java Layer"
        direction TB
        Jython_VM["Jython VM<br/>(Java)"]:::java
        JyNI_Java["JyNI-Java (JyNI.jar & JNI bindings)"]:::java
    end

    %% Native Loader Layer
    subgraph "Loader Layer"
        direction TB
        JNILoader["JNI Loader<br/>(sets up JNI env, loads libJyNI)"]:::loader
    end

    %% Core C Shim Layer
    subgraph "Core C Layer"
        direction TB
        Core_Header["JyNI-C include/JyNI.h"]:::core
        Core_C["JyNI-C src/JyNI.c"]:::core
        Core_JNI_C["JyNI-C src/JyNI_JNI.c"]:::core
        Modules["CPython Modules Adapters<br/>(src/Modules/)"]:::core
        Objects["CPython Objects Adapters<br/>(src/Objects/)"]:::core
    end

    %% OS & Extensions
    subgraph "Extensions & OS"
        direction TB
        OS_Loader["OS Dynamic Loader"]:::os
        CP_Ext["CPython Extensions<br/>(e.g., NumPy)"]:::ext
        DemoExtension["Demo/Test Native Extension"]:::ext
        DemoScripts["Demo/Test Python Scripts"]:::python
        Makefiles["Makefiles & Scripts"]:::os
    end

    %% Flows
    PyScript -->|"runs on"| Jython_VM
    Jython_VM -->|"import hook"| JyNI_Lib
    JyNI_Lib -->|"calls Java interface"| JyNI_Java
    JyNI_Java -->|"JNI call"| JNILoader
    JNILoader -->|"loads"| Core_Header
    JNILoader -->|"loads"| Core_C
    JNILoader -->|"loads JNI bridge"| Core_JNI_C
    Core_C -->|"implements PyObject API"| Modules
    Core_C -->|"implements PyObject API"| Objects
    Core_C -->|"loads"| CP_Ext
    CP_Ext -->|"PyObject_* calls"| Core_C
    Core_C -->|"JNI callback"| JyNI_Java
    JyNI_Java -->|"returns result"| Jython_VM
    OS_Loader -->|"dynamic linking"| JNILoader
    DemoExtension -->|"example plugin"| Core_C
    DemoScripts -->|"tests via import hook"| JyNI_Lib
    Makefiles -->|"build scripts"| JNILoader

    %% Click Events
    click JyNI_Java "https://github.com/stewori/jyni/tree/master/JyNI-Java/"
    click JyNI_Lib "https://github.com/stewori/jyni/tree/master/JyNI-Lib/"
    click JNILoader "https://github.com/stewori/jyni/blob/master/JyNI-Loader/JyNILoader.c"
    click Core_Header "https://github.com/stewori/jyni/blob/master/JyNI-C/include/JyNI.h"
    click Core_C "https://github.com/stewori/jyni/blob/master/JyNI-C/src/JyNI.c"
    click Core_JNI_C "https://github.com/stewori/jyni/blob/master/JyNI-C/src/JyNI_JNI.c"
    click Modules "https://github.com/stewori/jyni/tree/master/JyNI-C/src/Modules/"
    click Objects "https://github.com/stewori/jyni/tree/master/JyNI-C/src/Objects/"
    click DemoExtension "https://github.com/stewori/jyni/tree/master/DemoExtension/"
    click DemoScripts "https://github.com/stewori/jyni/tree/master/JyNI-Demo/src/"
    click Makefiles "https://github.com/stewori/jyni/tree/master/makefile"

    %% Styles
    classDef java fill:#8ecae6,stroke:#0366d6,color:#000;
    classDef python fill:#ffeb8a,stroke:#b58900,color:#000;
    classDef loader fill:#c3e88d,stroke:#5a8f00,color:#000;
    classDef core fill:#2a9d8f,stroke:#264653,color:#fff;
    classDef ext fill:#f4a261,stroke:#e76f51,color:#000;
    classDef os fill:#d3d3d3,stroke:#777,color:#000;
```
