# jpype-project/jpype architecture

> Architecture diagram of the GitHub repository jpype-project/jpype, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jpype-project/jpype
- Repository: https://github.com/jpype-project/jpype

## Overview

##### Main Components

a) Core Bridge Components:
- Python Runtime (CPython)
- Java Virtual Machine (JVM)
- Native Interface Layer (JNI)
- JPype Core Bridge

b) Key Architectural Layers:
- Python Interface Layer
- Type Conversion System
- Memory Management
- Java Class Loading System
- Proxy System

##### Component Relationships

**[Python Application]**
- ↕
**[Python Interface Layer (jpype/*.py)]**
- ↕
**[JPype Core Bridge]**
- ↙         ↘
**[JNI Layer]  [Memory Management]**
- ↓            ↓
**[Java Virtual Machine]**

##### Detailed Component Breakdown

a) Python Interface Layer (jpype/):
- Core initialization (_jinit.py)
- Type system (_jclass.py, _jarray.py)
- Collection interfaces (_jcollection.py)
- Exception handling (_jexception.py)

b) Native Bridge (native/):
- JNI implementations
- Type conversions
- Memory management
- Reference handling

c) Java Components (native/java/):
- Class management
- Proxy implementation
- Reference queue
- Custom class loading

##### Special Features to Highlight

- Bidirectional type conversion system
- Reference queue for garbage collection
- Dynamic proxy generation
- Class loading and reflection capabilities
- Thread synchronization

##### Implementation Details

- Type conversion flows
- Memory management cycles
- Exception handling paths
- Thread management

##### Type system integration

This system design should reflect JPype's unique architecture as a bridge between Python and Java, emphasizing its shared memory approach and native-level integration between the two virtual machines.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Legend
        PY[Python Component]:::python
        JV[Java Component]:::java
        NB[Native Bridge Component]:::native
        SR[Shared Resource]:::shared
        style Legend fill:none,stroke:#666
    end

    subgraph "Python Layer"
        PyApp[Python Application]:::python
        InterfaceLayer["Python Interface Layer"]:::python
        click InterfaceLayer "https://github.com/jpype-project/jpype/tree/master/jpype/"
        
        subgraph "Interface Components"
            TypeSystem["Type System"]:::python
            click TypeSystem "https://github.com/jpype-project/jpype/blob/master/jpype/_jclass.py"
            ExceptionHandler["Exception Handler"]:::python
            click ExceptionHandler "https://github.com/jpype-project/jpype/blob/master/jpype/_jexception.py"
            ThreadMgr["Thread Manager"]:::python
            click ThreadMgr "https://github.com/jpype-project/jpype/blob/master/jpype/_jthread.py"
            ProxyPy["Proxy System (Python)"]:::python
            click ProxyPy "https://github.com/jpype-project/jpype/blob/master/jpype/_jproxy.py"
        end
    end

    subgraph "Native Bridge Layer"
        CoreBridge["JPype Core Bridge"]:::native
        click CoreBridge "https://github.com/jpype-project/jpype/tree/master/native/python/"
        JNILayer["JNI Interface"]:::native
        click JNILayer "https://github.com/jpype-project/jpype/tree/master/native/common/"
        
        subgraph "Native Components"
            MemoryMgr["Memory Manager"]:::native
            click MemoryMgr "https://github.com/jpype-project/jpype/blob/master/native/common/include/jp_gc.h"
            NativeTypes["Native Type System"]:::native
            click NativeTypes "https://github.com/jpype-project/jpype/blob/master/native/common/include/jp_*type.h"
            ThreadControl["Thread Controller"]:::native
            click ThreadControl "https://github.com/jpype-project/jpype/blob/master/native/common/jp_monitor.cpp"
        end
    end

    subgraph "Java Layer"
        JVM["Java Virtual Machine"]:::java
        
        subgraph "Java Components"
            ClassLoader["Class Loading System"]:::java
            click ClassLoader "https://github.com/jpype-project/jpype/tree/master/native/java/org/jpype/classloader/"
            ProxyJava["Proxy System (Java)"]:::java
            click ProxyJava "https://github.com/jpype-project/jpype/tree/master/native/java/org/jpype/proxy/"
            RefManager["Reference Manager"]:::java
            click RefManager "https://github.com/jpype-project/jpype/tree/master/native/java/org/jpype/ref/"
            JavaException["Exception Proxy"]:::java
            click JavaException "https://github.com/jpype-project/jpype/blob/master/native/java/org/jpype/PyExceptionProxy.java"
        end
    end

    %% Connections
    PyApp --> InterfaceLayer
    InterfaceLayer --> TypeSystem & ExceptionHandler & ThreadMgr & ProxyPy
    TypeSystem & ExceptionHandler & ThreadMgr & ProxyPy --> CoreBridge
    CoreBridge --> JNILayer
    CoreBridge --> MemoryMgr
    JNILayer --> NativeTypes
    JNILayer --> ThreadControl
    JNILayer --> JVM
    MemoryMgr --> RefManager
    JVM --> ClassLoader & ProxyJava & RefManager & JavaException

    %% Styles
    classDef python fill:#3776AB,color:white
    classDef java fill:#B07219,color:white
    classDef native fill:#9B30FF,color:white
    classDef shared fill:#3CB371,color:white
```
