# crossgl/crosstl architecture

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

- Interactive diagram: https://gitdiagram.com/crossgl/crosstl
- Repository: https://github.com/crossgl/crosstl

## Overview

##### Project type and purpose
- CrossTL (crosstl) is an open-source universal programming language translator and compiler toolkit. It defines the CrossGL IR language (.cgl) and translates between CrossGL and various target languages/platforms (CUDA, HIP, Metal, DirectX/HLSL, OpenGL/GLSL, Vulkan/SPIRV, Rust, Mojo, Slang).
- The README describes a multi-stage translation pipeline: lexical analysis → syntax analysis → semantic analysis → IR generation (CrossGL AST) → optimization → backend code generation → post-processing/formatting.

##### File structure
- Top-level:
- setup.py, requirements.txt, setup.cfg → packaging and installation
- crosstl/ → main Python package
- examples/ and examples/output/ → sample .cgl inputs and generated target code
- tests/ → unit tests for translator and each backend
- crosstl/ contains:
- _crosstl.py → core translation orchestration
- formatter.py → code formatting and post-processing
- translator/lexer.py, parser.py, ast.py → lexical and syntax analysis, AST definitions
- translator/codegen/*.py → IR-to-backend codegen modules for each target
- backend/* → backend-specific parser, lexer, AST and CrossGL-to-CrossGL translators (used for reverse/import translation)
- Deployment script (deploy.sh) and CI workflows (GitHub Actions) indicate automated testing and release pipelines.

##### README for additional insights
- Architecture section lists seven pipeline stages.
- It emphasizes bidirectional translation (import/export).
- It highlights extensibility: adding new backends by implementing lexer/parser/AST/codegen modules.

##### Elements
- Labels: “CLI/API”, “Lexer”, “Parser”, “Semantic Analyzer/IR Generator”, “Optimizer”, “Codegen Dispatcher”, “Formatter”, “File Output”
- Right-to-left for import pipeline back into IR
- Front-end modules in blue
- Middle-end in green
- Back-end codegen in orange
- Import backends in purple
- Testing/Examples in gray
- Rectangles for components

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% DevOps components
    subgraph "DevOps" 
        CI["CI Workflows"]:::devops
        Packaging["Packaging & Installation"]:::devops
        DeployScript["Deployment Script"]:::devops
    end

    %% Entry point
    CLI["CLI / Library Entrypoint"]:::frontend

    %% Front-End Layer
    subgraph "Front-End" 
        Lexer["Lexical Analyzer"]:::frontend
        Parser["Parser"]:::frontend
        ASTDefs["AST Definitions"]:::frontend
    end

    %% Middle-End Layer
    subgraph "Middle-End"
        Semantic["Semantic Analyzer / IR Generator"]:::middle
        Optimizer["Optimization Passes"]:::middle
        Dispatcher["Codegen Dispatcher"]:::middle
        Formatter["Formatter / Post-Processor"]:::middle
    end

    %% Back-End Export
    subgraph "Back-End: Export (Code Generation)"
        CUDA_CG["CUDA Codegen"]:::backend
        HIP_CG["HIP Codegen"]:::backend
        Metal_CG["Metal Codegen"]:::backend
        DX_CG["DirectX/HLSL Codegen"]:::backend
        GLSL_CG["OpenGL/GLSL Codegen"]:::backend
        SPIRV_CG["Vulkan/SPIRV Codegen"]:::backend
        Rust_CG["Rust Codegen"]:::backend
        Mojo_CG["Mojo Codegen"]:::backend
        Slang_CG["Slang Codegen"]:::backend
    end

    %% Back-End Import
    subgraph "Back-End: Import (Reverse Translation)"
        Imp_CUDA["CUDA Import Backend"]:::import
        Imp_HIP["HIP Import Backend"]:::import
        Imp_Metal["Metal Import Backend"]:::import
        Imp_DX["DirectX Import Backend"]:::import
        Imp_GLSL["GLSL Import Backend"]:::import
        Imp_SPIRV["SPIRV Import Backend"]:::import
        Imp_Rust["Rust Import Backend"]:::import
        Imp_Mojo["Mojo Import Backend"]:::import
        Imp_Slang["Slang Import Backend"]:::import
        Imp_Torch["Experimental Torch Backend"]:::import
    end

    %% Output and Support
    FileOut["File Output"]:::storage
    Examples["Examples & Demonstrations"]:::devops
    Tests["Unit Tests"]:::devops

    %% Flow connections
    CLI --> Lexer
    Lexer --> Parser
    Parser --> ASTDefs
    ASTDefs --> Semantic
    Semantic --> Optimizer
    Optimizer --> Dispatcher
    Dispatcher --> Formatter
    Formatter --> FileOut

    %% Export backends invocation
    Dispatcher --> CUDA_CG
    Dispatcher --> HIP_CG
    Dispatcher --> Metal_CG
    Dispatcher --> DX_CG
    Dispatcher --> GLSL_CG
    Dispatcher --> SPIRV_CG
    Dispatcher --> Rust_CG
    Dispatcher --> Mojo_CG
    Dispatcher --> Slang_CG
    CUDA_CG --> Formatter
    HIP_CG --> Formatter
    Metal_CG --> Formatter
    DX_CG --> Formatter
    GLSL_CG --> Formatter
    SPIRV_CG --> Formatter
    Rust_CG --> Formatter
    Mojo_CG --> Formatter
    Slang_CG --> Formatter

    %% Import flow
    Imp_CUDA --> Semantic
    Imp_HIP --> Semantic
    Imp_Metal --> Semantic
    Imp_DX --> Semantic
    Imp_GLSL --> Semantic
    Imp_SPIRV --> Semantic
    Imp_Rust --> Semantic
    Imp_Mojo --> Semantic
    Imp_Slang --> Semantic
    Imp_Torch --> Semantic

    %% Supporting flows
    Examples -.-> CLI
    Tests -.-> CLI
    Tests -.-> Dispatcher
    Packaging --> CI
    DeployScript --> CI

    %% Click Events
    click CLI "https://github.com/crossgl/crosstl/blob/main/crosstl/_crosstl.py"
    click DeployScript "https://github.com/crossgl/crosstl/blob/main/deploy.sh"
    click Lexer "https://github.com/crossgl/crosstl/blob/main/crosstl/translator/lexer.py"
    click Parser "https://github.com/crossgl/crosstl/blob/main/crosstl/translator/parser.py"
    click ASTDefs "https://github.com/crossgl/crosstl/blob/main/crosstl/translator/ast.py"
    click Semantic "https://github.com/crossgl/crosstl/blob/main/crosstl/_crosstl.py"
    click Dispatcher "https://github.com/crossgl/crosstl/blob/main/crosstl/_crosstl.py"
    click Formatter "https://github.com/crossgl/crosstl/blob/main/crosstl/formatter.py"
    click CUDA_CG "https://github.com/crossgl/crosstl/blob/main/crosstl/translator/codegen/cuda_codegen.py"
    click HIP_CG "https://github.com/crossgl/crosstl/blob/main/crosstl/translator/codegen/hip_codegen.py"
    click Metal_CG "https://github.com/crossgl/crosstl/blob/main/crosstl/translator/codegen/metal_codegen.py"
    click DX_CG "https://github.com/crossgl/crosstl/blob/main/crosstl/translator/codegen/directx_codegen.py"
    click GLSL_CG "https://github.com/crossgl/crosstl/blob/main/crosstl/translator/codegen/GLSL_codegen.py"
    click SPIRV_CG "https://github.com/crossgl/crosstl/blob/main/crosstl/translator/codegen/SPIRV_codegen.py"
    click Rust_CG "https://github.com/crossgl/crosstl/blob/main/crosstl/translator/codegen/rust_codegen.py"
    click Mojo_CG "https://github.com/crossgl/crosstl/blob/main/crosstl/translator/codegen/mojo_codegen.py"
    click Slang_CG "https://github.com/crossgl/crosstl/blob/main/crosstl/translator/codegen/slang_codegen.py"
    click Imp_CUDA "https://github.com/crossgl/crosstl/blob/main/crosstl/backend/CUDA/CudaLexer.py"
    click Imp_HIP "https://github.com/crossgl/crosstl/blob/main/crosstl/backend/HIP/HipLexer.py"
    click Imp_Metal "https://github.com/crossgl/crosstl/blob/main/crosstl/backend/Metal/MetalLexer.py"
    click Imp_DX "https://github.com/crossgl/crosstl/blob/main/crosstl/backend/DirectX/DirectxLexer.py"
    click Imp_GLSL "https://github.com/crossgl/crosstl/blob/main/crosstl/backend/GLSL/OpenglLexer.py"
    click Imp_SPIRV "https://github.com/crossgl/crosstl/blob/main/crosstl/backend/SPIRV/VulkanLexer.py"
    click Imp_Rust "https://github.com/crossgl/crosstl/blob/main/crosstl/backend/Rust/RustLexer.py"
    click Imp_Mojo "https://github.com/crossgl/crosstl/blob/main/crosstl/backend/Mojo/MojoLexer.py"
    click Imp_Slang "https://github.com/crossgl/crosstl/blob/main/crosstl/backend/slang/SlangLexer.py"
    click Imp_Torch "https://github.com/crossgl/crosstl/blob/main/crosstl/backend/experimental/torch/torch_tracer.py"
    click Examples "https://github.com/crossgl/crosstl/tree/main/examples/"
    click Tests "https://github.com/crossgl/crosstl/tree/main/tests/"
    click Packaging "https://github.com/crossgl/crosstl/blob/main/setup.py"
    click CI "https://github.com/crossgl/crosstl/blob/main/.github/workflows/translator-tests.yml"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef middle fill:#90EE90,stroke:#333,stroke-width:1px
    classDef backend fill:#FFA500,stroke:#333,stroke-width:1px
    classDef import fill:#9370DB,stroke:#333,stroke-width:1px
    classDef devops fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef storage fill:#FFFFE0,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
