# higherorderco/bend architecture

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

- Interactive diagram: https://gitdiagram.com/higherorderco/bend
- Repository: https://github.com/higherorderco/bend

## Overview

##### Project Type and Purpose
- This project is a compiler/interpreter for Bend—a high-level, massively parallel programming language. Bend is unique in that it can generate and execute code on the CPU (via Rust and C interpreters) as well as on NVIDIA GPUs (through CUDA).
- The README emphasizes massively parallel execution, code generation (converted to standalone C or CUDA), and the integration with the HVM2 runtime.
- The project supports several modes of execution (sequential via Rust, parallel via C, and massively parallel via CUDA).

##### File Structure
- Top-level files such as Cargo.toml, src/, tests/, docs/, and examples/ show that this is a Rust-based project with an emphasis on language processing and code generation.
- The src/ directory is subdivided into several modules:
- “fun” – Contains the core language functions, the parser, builtins, and a series of transformation passes (in “transform” subdirectory) for tasks like desugaring, resolution, and linearizing matches.
- “hvm” – Implements reductions, inlining, mutual recursion analysis, and similar low-level operations. This module likely bridges produced intermediate representations with the HVM2 runtime.
- “imp” – Contains utilities for an intermediate language (“imp”) and related transformation (e.g., “to_fun” suggests converting code from one representation to another).
- “imports” – Handles package loading and module imports.
- “net” – Contains the core net or intermediate representation (possibly after converting ASTs into a computational graph) and its conversion routines.
- Other directories (docs, tests, examples) help validate the behavior by running various language programs (like bitonic_sort, parallel_sum, etc.).

##### Key Components and Their Interactions
- CLI/Driver: The user interface (invoked via “bend run”, “bend run-c”, “bend run-cu”, etc.) is the entry point. It parses command-line arguments, selects the interpreter mode, and passes the source file for processing.
- Frontend:
- Parser (src/fun/parser.rs) reads the Bend source code. The “fun” directory shows that builtins and initial representation are handled here.
- Type Checking (in src/fun/check/) ensures that the language’s type rules are applied.
- Core Transformation Pipeline:
- Multiple transformation phases in src/fun/transform (e.g., desugaring various language constructs such as match definitions, use-blocks, and lambda expressions).
- The transformation passes then produce an intermediate “net” representation (found in src/net) that is closer to the execution model.
- Intermediate and Backend Components:
- The “hvm” module performs optimizations like eta-reduction, inlining, recursion analysis, and pruning—preparing the program for efficient execution.
- The “imp” and “imports” modules act as bridges: “imp” looks to transform the code further, while “imports” handle package resolution and integration.
- Code Generation and Runtime Integration:
- The project includes provisions to generate executable code in C or CUDA (to leverage parallel hardware), and it integrates with the HVM2 runtime (an external tool installed via cargo) to execute or further optimize the code.
- Testing & Examples:
- A large collection of tests (in tests/golden_tests and related directories) ensures that each translation phase, error condition, and execution mode is thoroughly validated.
- The docs folder and examples illustrate how to write Bend code and how the tool is used.

##### Architectural Patterns and Design Principles
- The design follows a layered architecture:
- The Frontend (parsing and type checking) is separated from transformation passes.
- Multiple transformation modules (e.g., desugaring, resolution, linearization) embody the compiler’s pipeline—each operating on a progressively lower-level intermediate representation.
- The design is modular: Each component is isolated in its own namespace (e.g., “fun”, “hvm”, “imp”) to allow independent evolution and testing.
- Emphasis on non-blocking parallel processing is implicit in the execution engines (sequential vs. parallel vs. CUDA), with the runtime selection abstracted away by the CLI interface.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface"
        A["CLI/Driver"]:::cli
    end

    subgraph "Frontend"
        B["Parser & Lexer"]:::frontend
        C["Type Check Module"]:::frontend
        D["Builtins Module"]:::frontend
    end

    subgraph "Transformation Pipeline"
        E["Transformation Pipeline"]:::transform
    end

    subgraph "Intermediate & Optimization"
        F["Intermediate (Net) Representation"]:::intermediate
        G["HVM Module"]:::intermediate
    end

    subgraph "Backends"
        H["Code Generation Bridge"]:::backend
    end

    subgraph "Supporting Modules"
        I["Imports & Package Loader"]:::support
    end

    A -->|"processes"| B
    B -->|"generates AST"| C
    C -->|"applies types"| D
    D -->|"prepares for transformation"| E
    E -->|"produces net representation"| F
    F -->|"optimized by"| G
    G -->|"converts to executable code"| H
    H -->|"integrates packages"| I

    click A "https://github.com/higherorderco/bend/blob/main/src/main.rs"
    click B "https://github.com/higherorderco/bend/blob/main/src/fun/parser.rs"
    click C "https://github.com/higherorderco/bend/tree/main/src/fun/check/"
    click D "https://github.com/higherorderco/bend/blob/main/src/fun/builtins.rs"
    click E "https://github.com/higherorderco/bend/tree/main/src/fun/transform/"
    click F "https://github.com/higherorderco/bend/tree/main/src/net/"
    click G "https://github.com/higherorderco/bend/tree/main/src/hvm/"
    click H "https://github.com/higherorderco/bend/tree/main/src/imp/"
    click I "https://github.com/higherorderco/bend/tree/main/src/imports/"

    classDef cli fill:#ffd1dc,stroke:#b30047,stroke-width:2px;
    classDef frontend fill:#cceeff,stroke:#004c99,stroke-width:2px;
    classDef transform fill:#d0f0c0,stroke:#2e8b57,stroke-width:2px;
    classDef intermediate fill:#fddde6,stroke:#d2691e,stroke-width:2px;
    classDef backend fill:#e0ffff,stroke:#008b8b,stroke-width:2px;
    classDef support fill:#fffacd,stroke:#b8860b,stroke-width:2px;
```
