# kojix2/crython architecture

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

- Interactive diagram: https://gitdiagram.com/kojix2/crython
- Repository: https://github.com/kojix2/crython

## Overview

##### Main Components
- The Crystal Application Layer: This is where users embed Python code within their Crystal applications. It handles the session management (e.g., Crython.session), calling functions, and error handling.
- The Binding/Integration Layer: Represented by the “src/crython/libpython” directory, which interfaces with the Python C API (modules like “pyerrors”, “pythonrun”, “refcount”, etc.).
- The Data Type Conversion Modules: Split into two sub-components:
- Conversion from Crystal to Python – “src/crython/py2cr” (handling basic data types, collections, etc.).
- Conversion from Python to Crystal – “src/crython/cr2py” (with files like array.cr, bool.cr, complex.cr, etc.).
- The Error Management Component: Where Python exceptions are caught and converted to corresponding Crystal exceptions (“src/crython/error.cr” and parts in the libpython directory).
- Examples & Tests: Although not part of the runtime architecture, these confirm the intended usage patterns and help clarify the flow (see the “examples” and “spec” directories).

##### Relationships and Interactions
- The Crystal Application Layer (user code) sends requests to the high-level Crython API.
- The API then interacts with the Binding Layer to initialize or communicate with the Python interpreter.
- When data exchange is required, the system routes calls to the conversion modules (cr2py for preparing data for Python, and py2cr for bringing back Python objects as Crystal types).
- Errors generated during Python runtime are captured in the libpython or error modules and are passed back to the user’s context for handling.
- APIs such as “Crython.import”, “Crython.eval”, and the session block manage this orchestration.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Clear division between interfacing with Python (libpython), converting data types, and providing a simple API for users.
- Layered Architecture: The user-facing API (session management, module imports) sits on top of the integration layers (conversion and binding), which in turn abstract the lower-level Python interpreter operations.
- Modular Design: Each directory and module corresponds to a distinct functionality (type conversion, error handling) that can be updated independently.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    subgraph "User Layer"
        A("User Code / Crython API"):::user
    end

    %% Binding/Integration Layer
    subgraph "Binding/Integration Layer"
        B("Python Binding (libpython)"):::binding
        B1("pythonrun.cr"):::binding
        B2("pyerrors.cr"):::binding
        B3("refcount.cr"):::binding
        B --> B1
        B --> B2
        B --> B3
    end

    %% Data Type Conversion Modules
    subgraph "Data Type Conversions"
        subgraph "Crystal to Python Conversion (py2cr)"
            C("py2cr"):::conversion
            C1("basic.cr"):::conversion
            C2("collections.cr"):::conversion
            C --> C1
            C --> C2
        end
        subgraph "Python to Crystal Conversion (cr2py)"
            D("cr2py"):::conversion
            D1("array.cr"):::conversion
            D2("bool.cr"):::conversion
            D3("complex.cr"):::conversion
            D --> D1
            D --> D2
            D --> D3
        end
    end

    %% Error Management Component
    E("Error Management (error.cr)"):::error

    %% Examples & Tests
    subgraph "Examples & Tests"
        F("Examples"):::examples
        F1("Spec"):::examples
        F --> F1
    end

    %% Connections (Data Flow)
    A -->|"calls"| B
    B -->|"invokes"| C
    B -->|"invokes"| D
    B -->|"propagates"| E
    E -->|"reports"| A
    A -->|"demonstrates usage"| F

    %% Styles
    classDef user fill:#9ad,stroke:#333,stroke-width:2px;
    classDef binding fill:#afa,stroke:#333,stroke-width:2px;
    classDef conversion fill:#ff9,stroke:#333,stroke-width:2px;
    classDef error fill:#faa,stroke:#333,stroke-width:2px;
    classDef examples fill:#ccf,stroke:#333,stroke-width:2px;

    %% Click Events
    click A "https://github.com/kojix2/crython/blob/dev/src/crython.cr"
    click F "https://github.com/kojix2/crython/tree/dev/examples"
    click B "https://github.com/kojix2/crython/tree/dev/src/crython/libpython"
    click B1 "https://github.com/kojix2/crython/blob/dev/src/crython/libpython/pythonrun.cr"
    click B2 "https://github.com/kojix2/crython/blob/dev/src/crython/libpython/pyerrors.cr"
    click B3 "https://github.com/kojix2/crython/blob/dev/src/crython/libpython/refcount.cr"
    click C "https://github.com/kojix2/crython/tree/dev/src/crython/py2cr"
    click C1 "https://github.com/kojix2/crython/blob/dev/src/crython/py2cr/basic.cr"
    click C2 "https://github.com/kojix2/crython/blob/dev/src/crython/py2cr/collections.cr"
    click D "https://github.com/kojix2/crython/tree/dev/src/crython/cr2py"
    click D1 "https://github.com/kojix2/crython/blob/dev/src/crython/cr2py/array.cr"
    click D2 "https://github.com/kojix2/crython/blob/dev/src/crython/cr2py/bool.cr"
    click D3 "https://github.com/kojix2/crython/blob/dev/src/crython/cr2py/complex.cr"
    click E "https://github.com/kojix2/crython/blob/dev/src/crython/error.cr"
    click F1 "https://github.com/kojix2/crython/tree/dev/spec"
```
