# neon-bindings/neon architecture

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

- Interactive diagram: https://gitdiagram.com/neon-bindings/neon
- Repository: https://github.com/neon-bindings/neon

## Overview

##### Main Components

a) Core Framework Components:
- Neon Core Library (crates/neon)
- Macro System (crates/neon-macros)
- Node.js Runtime Integration Layer
- Rust Runtime Layer

b) Supporting Tools:
- Create-Neon CLI Tool
- Cargo Artifact Copy Tool

##### Key Architectural Elements

**JavaScript Application Layer**
- ↕
- Node.js API
- ↕
**Neon Binding Layer (Bridge)**
- ↕
- Rust Runtime

##### Component Relationships

a) Data Flow:
- Type conversion and memory management paths
- Event handling and async operations flow

b) Core Systems:
- Context Management System
- Type System Bridge
- Memory Management
- Event Loop Integration
- Threading Model

##### Specific Implementation Details

Key subsystems (found in the crates/neon/src directory):
- Context System (/context)
- Event Handling (/event)
- Object System (/object)
- Type Implementation (/types_impl)
- System Bindings (/sys)

##### Important Features to Highlight

- Thread safety mechanisms
- Memory management between Rust and JavaScript
- Type conversion system
- Async/await support
- Error handling paths

##### Architectural Patterns to Emphasize

- FFI (Foreign Function Interface) pattern
- Bridge pattern for language interop
- Factory pattern for object creation
- Observer pattern for event handling

**[JavaScript Application]**
- ↓
**[Node.js Native API (N-API)]**
- ↓
**[Neon Binding Layer]**
- Type System
- Memory Management
- Context Management
- Event Handling
- ↓
**[Rust Implementation]**
- Safe Abstractions
- Threading Model
- Resource Management

Additional Considerations:

##### Memory management boundaries

Keep the abstraction level high enough to be understandable but detailed enough to show the sophisticated interop between Node.js and Rust. Focus on showing how the system maintains memory safety and type safety while allowing high-performance native code execution.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph JS ["JavaScript Layer"]
        JSApp[JavaScript Application]
        NodeAPI[Node.js Native API N-API]
    end

    subgraph Bridge ["Neon Binding Layer"]
        NeonCore["Neon Core Library"]:::core
        MacroSys["Macro System"]:::core
        TypeBridge["Type System Bridge"]:::bridge
        MemMgmt["Memory Management"]:::bridge
        ErrorHandle["Error Handling"]:::bridge
    end

    subgraph Runtime ["Runtime Layer"]
        Context["Context Management"]:::runtime
        EventSys["Event Handling"]:::runtime
        ObjSys["Object System"]:::runtime
        TypeImpl["Type Implementation"]:::runtime
        SysBind["System Bindings"]:::runtime
        ThreadMod["Threading Model"]:::runtime
        EventLoop["Event Loop Integration"]:::runtime
        AsyncSupport["Async/Await Support"]:::runtime
    end

    subgraph Tools ["Build Tools"]
        CreateNeon["Create-Neon CLI"]:::tools
        CargoCopy["Cargo Artifact Copy"]:::tools
    end

    %% Connections
    JSApp --> NodeAPI
    NodeAPI --> NeonCore
    NeonCore --> MacroSys
    NeonCore --> TypeBridge
    NeonCore --> MemMgmt
    NeonCore --> ErrorHandle
    
    TypeBridge --> Context
    TypeBridge --> TypeImpl
    MemMgmt --> ObjSys
    ErrorHandle --> EventSys
    
    Context --> ThreadMod
    EventSys --> EventLoop
    EventLoop --> AsyncSupport
    ObjSys --> SysBind

    CreateNeon -.-> NeonCore
    CargoCopy -.-> NeonCore

    %% Styles
    classDef core fill:#f96,stroke:#333
    classDef bridge fill:#9f6,stroke:#333
    classDef runtime fill:#f69,stroke:#333
    classDef tools fill:#69f,stroke:#333

    %% Click Events
    click NeonCore "https://github.com/neon-bindings/neon/blob/main/crates/neon/src/lib.rs"
    click MacroSys "https://github.com/neon-bindings/neon/blob/main/crates/neon-macros/src/lib.rs"
    click Context "https://github.com/neon-bindings/neon/blob/main/crates/neon/src/context/mod.rs"
    click EventSys "https://github.com/neon-bindings/neon/blob/main/crates/neon/src/event/mod.rs"
    click ObjSys "https://github.com/neon-bindings/neon/blob/main/crates/neon/src/object/mod.rs"
    click TypeImpl "https://github.com/neon-bindings/neon/blob/main/crates/neon/src/types_impl/mod.rs"
    click SysBind "https://github.com/neon-bindings/neon/blob/main/crates/neon/src/sys/mod.rs"
    click ThreadMod "https://github.com/neon-bindings/neon/blob/main/crates/neon/src/thread/mod.rs"
    click MemMgmt "https://github.com/neon-bindings/neon/blob/main/crates/neon/src/sys/mem.rs"
    click CreateNeon "https://github.com/neon-bindings/neon/blob/main/pkgs/create-neon/src/bin/create-neon.ts"
    click CargoCopy "https://github.com/neon-bindings/neon/blob/main/pkgs/cargo-cp-artifact/src/index.js"
    click EventLoop "https://github.com/neon-bindings/neon/blob/main/crates/neon/src/executor/mod.rs"
    click TypeBridge "https://github.com/neon-bindings/neon/blob/main/crates/neon/src/types_impl/extract/mod.rs"
    click ErrorHandle "https://github.com/neon-bindings/neon/blob/main/crates/neon/src/result/mod.rs"
    click AsyncSupport "https://github.com/neon-bindings/neon/blob/main/crates/neon/src/macro_internal/futures.rs"
```
