# scikit-hep/awkward architecture

> Architecture diagram of the GitHub repository scikit-hep/awkward, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/scikit-hep/awkward
- Repository: https://github.com/scikit-hep/awkward
- Video tour (about a minute): https://gitdiagram.com/scikit-hep/awkward/video

## Overview

Awkward Array is a Python library for dynamically typed, nested and variable-sized data, providing NumPy-like operations and compiled performance. The principal workflow is to construct or import an Awkward array, represent it with nested content layouts, apply operations such as slicing or reductions, and obtain a new array or convert it to another ecosystem. The README documents broad interoperability and backend support; the graph includes those branches by their tree paths. Only limited implementation excerpts were supplied, so some subsystem wiring is intentionally left unspecified.

Main entry points: [`src/awkward/operations`](https://github.com/scikit-hep/awkward/tree/main/src/awkward/operations) (Array operations), [`src/awkward/contents`](https://github.com/scikit-hep/awkward/tree/main/src/awkward/contents) (Content layouts), [`src/awkward/__init__.py`](https://github.com/scikit-hep/awkward/blob/main/src/awkward/__init__.py) (Public API), [`src/awkward/operations/ak_from_iter.py`](https://github.com/scikit-hep/awkward/blob/main/src/awkward/operations/ak_from_iter.py) (Array construction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Array API"]
  node_public["Public API<br/>[__init__.py]"]
  node_construct["Array construction<br/>[ak_from_iter.py]"]
  node_operations["Array operations"]
end

subgraph group_layouts["Data model"]
  node_highlevel["High-level arrays<br/>[highlevel.py]"]
  node_contents["Content layouts"]
  node_indices["Layout indices<br/>[index.py]"]
  node_forms["Type forms"]
end

subgraph group_compute["Compute runtime"]
  node_backends["Backend dispatch"]
  node_kernels["Kernel interface<br/>[_kernels.py]"]
end

subgraph group_interop["Interoperability"]
  node_connectors["External connectors"]
  node_arrow["Arrow conversion"]
  node_raggedin["RaggedTensor import"]
  node_raggedout["RaggedTensor export"]
end

subgraph group_native["Native components"]
  node_cpu["CPU kernels"]
  node_cpp["C++ runtime"]
  node_builder["C++ builders"]
  node_forth["Forth execution"]
  node_io["JSON I/O<br/>[json.cpp]"]
end

node_user(("Python user"))
node_tensorflow(("TensorFlow"))
node_externaldata(("External data sources"))
node_result(("Array result"))

node_user -->|"calls"| node_public
node_public -->|"exposes"| node_construct
node_public -->|"exposes"| node_operations
node_construct -->|"constructs"| node_highlevel
node_operations -->|"operates on"| node_contents
node_operations -->|"dispatches by"| node_backends
node_highlevel -->|"wraps"| node_contents
node_contents -->|"uses"| node_indices
node_contents -->|"describes"| node_forms
node_contents -->|"invokes"| node_kernels
node_kernels -->|"dispatches"| node_cpu
node_cpu -->|"uses"| node_cpp
node_construct -->|"builds"| node_builder
node_operations -.->|"executes via"| node_forth
node_operations -->|"uses"| node_io
node_operations -.->|"integrates"| node_connectors
node_connectors -.->|"includes"| node_arrow
node_externaldata -.->|"provides data"| node_connectors
node_tensorflow -.->|"provides tensor"| node_raggedin
node_raggedin -->|"builds layout"| node_contents
node_contents -->|"supplies layout"| node_raggedout
node_raggedout -.->|"creates tensor"| node_tensorflow
node_operations -->|"returns array"| node_result

click node_public "https://github.com/scikit-hep/awkward/blob/main/src/awkward/__init__.py"
click node_construct "https://github.com/scikit-hep/awkward/blob/main/src/awkward/operations/ak_from_iter.py"
click node_operations "https://github.com/scikit-hep/awkward/tree/main/src/awkward/operations"
click node_highlevel "https://github.com/scikit-hep/awkward/blob/main/src/awkward/highlevel.py"
click node_contents "https://github.com/scikit-hep/awkward/tree/main/src/awkward/contents"
click node_indices "https://github.com/scikit-hep/awkward/blob/main/src/awkward/index.py"
click node_forms "https://github.com/scikit-hep/awkward/tree/main/src/awkward/forms"
click node_backends "https://github.com/scikit-hep/awkward/tree/main/src/awkward/_backends"
click node_kernels "https://github.com/scikit-hep/awkward/blob/main/src/awkward/_kernels.py"
click node_cpu "https://github.com/scikit-hep/awkward/tree/main/awkward-cpp/src/cpu-kernels"
click node_cpp "https://github.com/scikit-hep/awkward/tree/main/awkward-cpp/src/libawkward"
click node_builder "https://github.com/scikit-hep/awkward/tree/main/awkward-cpp/src/libawkward/builder"
click node_forth "https://github.com/scikit-hep/awkward/tree/main/awkward-cpp/src/libawkward/forth"
click node_io "https://github.com/scikit-hep/awkward/blob/main/awkward-cpp/src/libawkward/io/json.cpp"
click node_connectors "https://github.com/scikit-hep/awkward/tree/main/src/awkward/_connect"
click node_arrow "https://github.com/scikit-hep/awkward/tree/main/src/awkward/_connect/pyarrow"
click node_raggedin "https://github.com/scikit-hep/awkward/blob/main/src/awkward/operations/ak_from_raggedtensor.py"
click node_raggedout "https://github.com/scikit-hep/awkward/blob/main/src/awkward/operations/ak_to_raggedtensor.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public,node_construct,node_operations,node_user toneBlue
class node_highlevel,node_contents,node_indices,node_forms toneAmber
class node_backends,node_kernels toneMint
class node_connectors,node_arrow,node_raggedin,node_raggedout toneRose
class node_cpu,node_cpp,node_builder,node_forth,node_io,node_tensorflow,node_externaldata,node_result toneIndigo
```

## Components

### Array API

- [Public API](https://github.com/scikit-hep/awkward/blob/main/src/awkward/__init__.py): `src/awkward/__init__.py`
- [Array construction](https://github.com/scikit-hep/awkward/blob/main/src/awkward/operations/ak_from_iter.py): `src/awkward/operations/ak_from_iter.py`
- [Array operations](https://github.com/scikit-hep/awkward/tree/main/src/awkward/operations): `src/awkward/operations`

### Data model

- [High-level arrays](https://github.com/scikit-hep/awkward/blob/main/src/awkward/highlevel.py): `src/awkward/highlevel.py`
- [Content layouts](https://github.com/scikit-hep/awkward/tree/main/src/awkward/contents): `src/awkward/contents`
- [Layout indices](https://github.com/scikit-hep/awkward/blob/main/src/awkward/index.py): `src/awkward/index.py`
- [Type forms](https://github.com/scikit-hep/awkward/tree/main/src/awkward/forms): `src/awkward/forms`

### Compute runtime

- [Backend dispatch](https://github.com/scikit-hep/awkward/tree/main/src/awkward/_backends): `src/awkward/_backends`
- [Kernel interface](https://github.com/scikit-hep/awkward/blob/main/src/awkward/_kernels.py): `src/awkward/_kernels.py`

### Interoperability

- [External connectors](https://github.com/scikit-hep/awkward/tree/main/src/awkward/_connect): `src/awkward/_connect`
- [Arrow conversion](https://github.com/scikit-hep/awkward/tree/main/src/awkward/_connect/pyarrow): `src/awkward/_connect/pyarrow`
- [RaggedTensor import](https://github.com/scikit-hep/awkward/blob/main/src/awkward/operations/ak_from_raggedtensor.py): `src/awkward/operations/ak_from_raggedtensor.py`
- [RaggedTensor export](https://github.com/scikit-hep/awkward/blob/main/src/awkward/operations/ak_to_raggedtensor.py): `src/awkward/operations/ak_to_raggedtensor.py`

### Native components

- [CPU kernels](https://github.com/scikit-hep/awkward/tree/main/awkward-cpp/src/cpu-kernels): `awkward-cpp/src/cpu-kernels`
- [C++ runtime](https://github.com/scikit-hep/awkward/tree/main/awkward-cpp/src/libawkward): `awkward-cpp/src/libawkward`
- [C++ builders](https://github.com/scikit-hep/awkward/tree/main/awkward-cpp/src/libawkward/builder): `awkward-cpp/src/libawkward/builder`
- [Forth execution](https://github.com/scikit-hep/awkward/tree/main/awkward-cpp/src/libawkward/forth): `awkward-cpp/src/libawkward/forth`
- [JSON I/O](https://github.com/scikit-hep/awkward/blob/main/awkward-cpp/src/libawkward/io/json.cpp): `awkward-cpp/src/libawkward/io/json.cpp`

### Other components

- **Python user**
- **TensorFlow**
- **External data sources**
- **Array result**

## Connections

- Python user → Public API: calls
- Public API → Array construction: exposes
- Public API → Array operations: exposes
- Array construction → High-level arrays: constructs
- Array operations → Content layouts: operates on
- Array operations → Backend dispatch: dispatches by
- High-level arrays → Content layouts: wraps
- Content layouts → Layout indices: uses
- Content layouts → Type forms: describes
- Content layouts → Kernel interface: invokes
- Kernel interface → CPU kernels: dispatches
- CPU kernels → C++ runtime: uses
- Array construction → C++ builders: builds
- Array operations → Forth execution: executes via
- Array operations → JSON I/O: uses
- Array operations → External connectors: integrates
- External connectors → Arrow conversion: includes
- External data sources → External connectors: provides data
- TensorFlow → RaggedTensor import: provides tensor
- RaggedTensor import → Content layouts: builds layout
- Content layouts → RaggedTensor export: supplies layout
- RaggedTensor export → TensorFlow: creates tensor
- Array operations → Array result: returns array