# cysharp/zlinq architecture

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

- Interactive diagram: https://gitdiagram.com/cysharp/zlinq
- Repository: https://github.com/cysharp/zlinq

## Overview

##### Main Components
- Core Library Module (ZLinq)
- Contains the central implementation (the ValueEnumerable<TEnumerator, T> struct, the IValueEnumerator<T> interface, and all the extension methods for LINQ operators such as Where, Select, Sum, etc.).
- Implements key performance patterns:
◦ Struct-based enumerators (with support for “ref struct” in .NET 9+).
◦ Optimizations like TryGetNext, TryGetSpan, TryCopyTo.

- Specialized Adapters/Extensions:
- ZLinq.FileSystem: Provides LINQ-to-Tree capabilities for the file-system (traversing DirectoryInfo, FileInfo, etc.).
- ZLinq.Json: Supports LINQ operations on tree-structured JSON objects (using System.Text.Json’s JsonNode).
- ZLinq.Unity: Adapts the core LINQ functionality to Unity’s GameObject and Transform hierarchies.
- ZLinq.Godot: Similar adapter for Godot Node objects.
- ZLinq.DropInGenerator: A source generation tool that automatically adds drop-in replacements for System.Linq methods.

- Benchmarking and Sandbox Environment:
- The “sandbox” directory houses benchmarking projects – these simulate different LINQ operations (e.g., performance benchmarks using BenchmarkDotNet) to measure and showcase zero-allocation and SIMD-enabled operations.

- Test Suite:
- The “tests” directory includes multiple test projects that exercise both the compatibility (by running System.Linq tests as a drop-in replacement) and the correctness of LINQ operations with ZLinq.

##### Relationships and Interactions
- The Core Library serves as the foundation – every specialized module (like FileSystem, Json, Unity, Godot) depends on it for the basic LINQ transformation mechanics.
- The DropInGenerator acts as an intercept layer between the consumer’s code and the core LINQ methods, ensuring that when developers use familiar LINQ operators, ZLinq implementations are called instead.
- Benchmarks and Tests are “clients” of the core functionality and specialized adapters—they “call into” the library to verify performance and correctness.
- The core and adapter libraries expose extension methods (such as AsValueEnumerable, Where, Select, etc.) which are used by the client code. Their high compatibility with System.Linq is demonstrated explicitly by running over 9000 tests from the dotnet/runtime’s repository.

##### Architectural Patterns and Design Principles
- Modular design: The project is split into multiple subprojects (core, adapters, benchmark, tests), each addressing a specific concern. This separation of concerns enhances maintainability and clarity.
- High-performance design: Using struct-based enumerators and ref structs (where applicable) to minimize runtime allocations and copy costs.
- Extensibility: With drop-in replacement via a source generator and extensible “Tree” querying interfaces (ITraverser<T>) for file system, JSON, and game engine objects.
- Cross-Platform Targeting: The project supports a variety of environments ranging from standard .NET platforms to specialized game engines, which is also reflected in the file tree (directories like src/ZLinq.Unity, src/ZLinq.Godot).

##### Relevant Technologies, Frameworks, and Libraries
- .NET (multiple target frameworks including netstandard and .NET 8/9)
- BenchmarkDotNet (for the benchmarking projects in the sandbox directory)
- Source Generation (via the DropInGenerator to generate IL code during compile-time)
- Unity and Godot integration (with platform-specific projects and assets under src folder)
- Standard C# language features (e.g., ref structs, extension methods, async/await if needed)

##### Putting It All Together
- Split “Core ZLinq Library” into sub-components:
- “ValueEnumerable & IValueEnumerator (Core Data Structures)”
- “LINQ Operator Extensions (Where, Select, Sum, SIMD-enabled methods, etc.)”
- Separate blocks for the specialized adapters (FileSystem, Json, Unity, Godot), each connected to the core, representing platform-specific extensions.

– All key modules, their relationships, and how external consumers use ZLinq.
– The conceptual flow from generic LINQ query invocation through both the core high-performance implementation and the specialized modules.
– The modular architecture that cleanly separates core functionality from benchmarking, testing, and platform-specific adaptations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client Code"]:::client
    DropGen["Drop-In Generator (Source Generation)"]:::generator
    Core["Core ZLinq Library"]:::core
    CDS["ValueEnumerable & IValueEnumerator (Core Data Structures)"]:::core
    Ops["LINQ Operator Extensions (Where,Select,Sum,Simd-enabled)"]:::core
    FS["ZLinq.FileSystem"]:::adapter
    J["ZLinq.Json"]:::adapter
    Unity["ZLinq.Unity"]:::adapter
    Godot["ZLinq.Godot"]:::adapter
    Bench["Benchmark Suite"]:::benchmark
    Tests["Test Suite"]:::test

    Client -->|"uses"| DropGen
    DropGen -->|"invokes"| Core
    Core --> CDS
    Core --> Ops
    Core -->|"provides extensions to"| FS
    Core -->|"provides extensions to"| J
    Core -->|"provides extensions to"| Unity
    Core -->|"provides extensions to"| Godot
    Bench -->|"measures"| Core
    Tests -->|"validates"| Core

    click Core "https://github.com/cysharp/zlinq/tree/main/src/ZLinq"
    click CDS "https://github.com/cysharp/zlinq/tree/main/src/ZLinq/Linq"
    click Ops "https://github.com/cysharp/zlinq/tree/main/src/ZLinq/Simd"
    click FS "https://github.com/cysharp/zlinq/blob/main/src/ZLinq.FileSystem"
    click J "https://github.com/cysharp/zlinq/blob/main/src/ZLinq.Json"
    click Unity "https://github.com/cysharp/zlinq/blob/main/src/ZLinq.Unity"
    click Godot "https://github.com/cysharp/zlinq/blob/main/src/ZLinq.Godot"
    click DropGen "https://github.com/cysharp/zlinq/blob/main/src/ZLinq.DropInGenerator"
    click Bench "https://github.com/cysharp/zlinq/tree/main/sandbox/Benchmark"
    click Tests "https://github.com/cysharp/zlinq/tree/main/tests"

    classDef client fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef core fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef adapter fill:#f9844a,stroke:#333,stroke-width:2px;
    classDef benchmark fill:#577590,stroke:#333,stroke-width:2px;
    classDef test fill:#f94144,stroke:#333,stroke-width:2px;
    classDef generator fill:#a8dadc,stroke:#333,stroke-width:2px;
```
