# dhanunjaya-elluri/narwhals architecture

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

- Interactive diagram: https://gitdiagram.com/dhanunjaya-elluri/narwhals
- Repository: https://github.com/dhanunjaya-elluri/narwhals

## Overview

##### Main Components

a) Core Components:
- Input Layer (Native DataFrames)
- Translation Layer
- Narwhals API Layer
- Output Layer (Native DataFrames)

b) Supported Backend Systems:
- Full API Support Systems (cuDF, Modin, pandas, Polars, PyArrow)
- Lazy-only Systems (Dask)
- Interchange Protocol Systems (DuckDB, Ibis, Vaex)

**┌─────────────────────────────────────────────────────────┐**
- Client Applications                    │
- ┘
- ↕
**┌─────────────────────────────────────────────────────────┐**
- Input Interface                       │
- (narwhals.from_native converter)              │
- ┘
- ↕
**┌─────────────────────────────────────────────────────────┐**
- Narwhals Core Layer                    │
- ┬───────────────────────────────┤
- Expression Engine   │      Type System              │
- ┼───────────────────────────────┤
- DataFrame Operations  │      Series Operations        │
- ┴───────────────────────────────┘
- ↕
**┌─────────────────────────────────────────────────────────┐**
- Backend Implementation                    │
- ┬───────────┬────────────┬───────────────────┤
- ┴───────────┴────────────┴───────────────────┘
- ↕
**┌─────────────────────────────────────────────────────────┐**
- Output Interface                      │
- (narwhals.to_native converter)              │
- ┘

##### Important Elements to Highlight

a) Core Features:
- Zero-dependency architecture
- Lazy and eager evaluation paths
- Expression-based operations
- Type system compatibility

b) Integration Points:
- DataFrame Interchange Protocol support
- Backend-specific optimizations
- API translation mechanisms

##### Data Flow Representation

How data moves through the system:

##### Implementation Details

- Relationship between _arrow, _dask, _polars, etc. implementations
- How the stable API versioning works
- Relationship between DataFrame, Series, and Expression components

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client["Client Applications"]
        CA[Client Apps]
    end

    subgraph Input["Input Interface"]
        IC["from_native Converter"]:::input
    end

    subgraph Core["Narwhals Core Layer"]
        direction TB
        EE["Expression Engine"]:::core
        TS["Type System"]:::core
        DFO["DataFrame Operations"]:::core
        SO["Series Operations"]:::core
        GB["Group By Operations"]:::core
        SCH["Schema Management"]:::core
        SEL["Selector System"]:::core
        DEP["Dependencies Management"]:::core
        TL["Translation Layer"]:::core
    end

    subgraph Backend["Backend Implementation Layer"]
        direction TB
        PD["Pandas"]:::backend
        PL["Polars"]:::backend
        AR["Arrow"]:::backend
        DK["Dask"]:::backend
        DB["DuckDB"]:::backend
        IB["Ibis"]:::backend
        IC_P["Interchange Protocol"]:::backend
    end

    subgraph Output["Output Interface"]
        OC["to_native Converter"]:::output
    end

    %% Connections
    CA --> IC
    IC --> Core
    Core --> Backend
    Backend --> OC
    OC --> CA

    %% Internal Core Connections
    EE --> DFO
    EE --> SO
    TS --> DFO
    TS --> SO
    TL --> DFO
    TL --> SO
    GB --> DFO
    SCH --> DFO
    SEL --> DFO
    DEP --> DFO

    %% Styling
    classDef core fill:#a8d1f0,stroke:#333
    classDef input fill:#90EE90,stroke:#333
    classDef output fill:#98FB98,stroke:#333
    classDef backend fill:#FFA07A,stroke:#333

    %% Click Events
    click EE "https://github.com/Dhanunjaya-Elluri/narwhals/blob/main/narwhals/expr.py"
    click TS "https://github.com/Dhanunjaya-Elluri/narwhals/blob/main/narwhals/dtypes.py"
    click DFO "https://github.com/Dhanunjaya-Elluri/narwhals/blob/main/narwhals/dataframe.py"
    click SO "https://github.com/Dhanunjaya-Elluri/narwhals/blob/main/narwhals/series.py"
    click GB "https://github.com/Dhanunjaya-Elluri/narwhals/blob/main/narwhals/group_by.py"
    click SCH "https://github.com/Dhanunjaya-Elluri/narwhals/blob/main/narwhals/schema.py"
    click SEL "https://github.com/Dhanunjaya-Elluri/narwhals/blob/main/narwhals/selectors.py"
    click DEP "https://github.com/Dhanunjaya-Elluri/narwhals/blob/main/narwhals/dependencies.py"
    click TL "https://github.com/Dhanunjaya-Elluri/narwhals/blob/main/narwhals/translate.py"
    click PL "https://github.com/Dhanunjaya-Elluri/narwhals/tree/main/narwhals/_polars/"
    click AR "https://github.com/Dhanunjaya-Elluri/narwhals/tree/main/narwhals/_arrow/"
    click DK "https://github.com/Dhanunjaya-Elluri/narwhals/tree/main/narwhals/_dask/"
    click DB "https://github.com/Dhanunjaya-Elluri/narwhals/tree/main/narwhals/_duckdb/"
    click IB "https://github.com/Dhanunjaya-Elluri/narwhals/tree/main/narwhals/_ibis/"
    click IC_P "https://github.com/Dhanunjaya-Elluri/narwhals/tree/main/narwhals/_interchange/"
```
