# aspect-build/rules_deno architecture

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

- Interactive diagram: https://gitdiagram.com/aspect-build/rules_deno
- Repository: https://github.com/aspect-build/rules_deno

## Overview

##### Key Components
- Bazel Core & Workspaces: At the base, you have the WORKSPACE file and multiple top-level Bazel configuration files (.bazelrc, BUILD.bazel, WORKSPACE) that define the build environment.
- Aspect Configurations: The .aspect folder (with subdirectories for bazelrc, cli, and workflows) encapsulates configuration rules and scripts that set up the build environment. This represents custom configuration and CI/CD pipelines.
- Deno Toolchain Integration: The “deno” directory contains files like defs.bzl, dependencies.bzl, and toolchain-related Starlark files that define how Deno interacts with Bazel. This component is crucial for translating Deno tasks into Bazel actions.
- Example and Test Workspaces: Under the e2e directory you have sample workspaces that demonstrate the concrete use of these rules (such as the “deno_binary” examples and the Fresh application) as well as testing setups.
- Utility and Tool Directories: The tools folder (with buildifier, format, gazelle, etc.) provides supporting utilities that help maintain the build files and format/validate the repository.
- Documentation & Examples: The docs directory (along with the README and CONTRIBUTING files) gives context on usage, showcasing how the rules should be applied.

##### Out the Relationships and Interactions
- The Bazel Workspace (root-level WORKSPACE and BUILD files) is the entry point and ties together all components.
- The custom rules defined in the “deno” directory are loaded in BUILD files across the project (as seen in the usage examples in the README where “deno_binary” is used).
- The .aspect configurations influence how Bazel runs actions (for instance, using different bazelrc configurations for debugging, performance, etc.) and also guide CI/CD workflows.
- e2e sample workspaces demonstrate how users can integrate Deno_script execution with Bazel actions (for both testing using sh_test and building executables with deno_binary).
- Utility tools ensure that build definitions remain consistent and compliant via automated formatting and linting.

##### Architectural Patterns and Design Principles
- Modular Design: The project is separated into clear modules – configuration, rule definitions, examples, tests, and tooling. This separation encourages modularity and reusability.
- Build-Time vs. Run-Time Separation: There is a clear distinction between the configuration and transformation of source code at build-time (using genrule, for instance) and the Deno scripts that run at runtime (whether as binaries or tests).
- Extensibility: The simplicity of the “deno_binary” rule and use of filegroup for libraries indicates that the system is designed to easily extend for more complex build patterns as needed.
- Integration with External Tools: The use of pre-commit hooks, CI configurations (.gitlab-ci.yml), and build tools (tools/format, tools/gazelle) emphasizes a robust integration ecosystem to maintain project health.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraph for Bazel Workspace & Core Files
    subgraph "Bazel Workspace & Core Files"
        A1["WORKSPACE"]:::bazel
        A2["BUILD.bazel"]:::bazel
        A3[".bazelrc"]:::bazel
    end

    %% Subgraph for Aspect Configuration
    subgraph "Aspect Configuration"
        B1[".aspect"]:::aspect
        B2[".aspect/bazelrc"]:::aspect
        B3[".aspect/cli"]:::aspect
        B4[".aspect/workflows"]:::aspect
    end

    %% Subgraph for Deno Toolchain Integration
    subgraph "Deno Toolchain Integration"
        C1["deno/defs.bzl"]:::deno
        C2["deno/dependencies.bzl"]:::deno
        C3["deno/toolchain.bzl"]:::deno
        C4["deno/private"]:::deno
    end

    %% Subgraph for Example and Test Workspaces
    subgraph "Example and Test Workspaces"
        D1["e2e/workspace"]:::example
        D2["tests/hello_world.js"]:::example
        D3["tests/BUILD.bazel"]:::example
    end

    %% Subgraph for Utility and Tool Directories
    subgraph "Utility and Tool Directories"
        E1["tools/buildifier"]:::tools
        E2["tools/format"]:::tools
        E3["tools/gazelle"]:::tools
    end

    %% Subgraph for Documentation & External Resources
    subgraph "Documentation & External Resources"
        F1["docs"]:::docs
        F2["README.md"]:::docs
        F3["CONTRIBUTING.md"]:::docs
    end

    %% Interconnections between components
    A1 -->|"pulls_configs"| B1
    B1 -->|"defines_rules"| C1
    C1 -->|"triggers_build"| D1
    C1 -->|"runs_tests"| D2
    D1 -->|"includes"| D3
    E1 -->|"formats"| A2
    F1 -->|"provides_guidance"| A1

    %% Click Events for Bazel Workspace & Core Files
    click A1 "https://github.com/aspect-build/rules_deno/tree/main/WORKSPACE"
    click A2 "https://github.com/aspect-build/rules_deno/blob/main/BUILD.bazel"
    click A3 "https://github.com/aspect-build/rules_deno/blob/main/.bazelrc"

    %% Click Events for Aspect Configuration
    click B1 "https://github.com/aspect-build/rules_deno/blob/main/.aspect"
    click B2 "https://github.com/aspect-build/rules_deno/tree/main/.aspect/bazelrc"
    click B3 "https://github.com/aspect-build/rules_deno/tree/main/.aspect/cli"
    click B4 "https://github.com/aspect-build/rules_deno/tree/main/.aspect/workflows"

    %% Click Events for Deno Toolchain Integration
    click C1 "https://github.com/aspect-build/rules_deno/blob/main/deno/defs.bzl"
    click C2 "https://github.com/aspect-build/rules_deno/blob/main/deno/dependencies.bzl"
    click C3 "https://github.com/aspect-build/rules_deno/blob/main/deno/toolchain.bzl"
    click C4 "https://github.com/aspect-build/rules_deno/tree/main/deno/private"

    %% Click Events for Example and Test Workspaces
    click D1 "https://github.com/aspect-build/rules_deno/tree/main/e2e/workspace"
    click D2 "https://github.com/aspect-build/rules_deno/blob/main/tests/hello_world.js"
    click D3 "https://github.com/aspect-build/rules_deno/blob/main/tests/BUILD.bazel"

    %% Click Events for Utility and Tool Directories
    click E1 "https://github.com/aspect-build/rules_deno/tree/main/tools/buildifier"
    click E2 "https://github.com/aspect-build/rules_deno/tree/main/tools/format"
    click E3 "https://github.com/aspect-build/rules_deno/tree/main/tools/gazelle"

    %% Click Events for Documentation & External Resources
    click F1 "https://github.com/aspect-build/rules_deno/tree/main/docs"
    click F2 "https://github.com/aspect-build/rules_deno/blob/main/README.md"
    click F3 "https://github.com/aspect-build/rules_deno/blob/main/CONTRIBUTING.md"

    %% Style definitions for color coding
    classDef bazel fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef aspect fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef deno fill:#F08080,stroke:#000,stroke-width:2px;
    classDef example fill:#FFFFE0,stroke:#000,stroke-width:2px;
    classDef tools fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef docs fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
