# sampsyo/bril architecture

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

- Interactive diagram: https://gitdiagram.com/sampsyo/bril
- Repository: https://github.com/sampsyo/bril

## Overview

##### Project’s Core Purpose and Type
- This project is a compiler IR ecosystem for educational purposes.
- It centers on a canonical JSON representation of Bril, designed to be extended by numerous tools.
- Multiple language-specific implementations (interpreters, converters, backends) are provided demonstrating a language-agnostic design.

##### Pinpoint the Main Components by Examining the File Structure
- Documentation & Specs:
– The docs directory (with summaries, language reference, and tool instructions) supports learning and reference.
- IR Representation & Core Tools:
– The canonical IR is JSON-based.
– Tools such as the interpreter (deno-based “brili”) and text conversion tools (bril2json, bril2txt in Python) are central.
- Implementations in Different Languages:
– Directories like bril-llvm, bril-ocaml, bril-rs, bril-swift, bril-ts all provide different frontends/backends or utilities.
– They likely share the same IR so they form a heterogeneous ecosystem.
- Testing & Benchmarking Infrastructure:
– The test/ directory contains a comprehensive suite of tests using Turnt.
– The benchmarks/ directory contains performance and correctness tests of various programs written in Bril.
- Build & Deployment:
– Configuration files like Makefile, GitHub workflows, and various build scripts illustrate automation and continuous integration.

- Centerpiece – Bril IR Core:
- Frontend/Parsing Components:
- Interpreter/Execution Components:
– Mark how it interfaces by accepting JSON on stdin and producing output.
- Language-Specific Implementations:
– Represent separate nodes/components for each language’s implementation:
- “bril-rs” (Rust-based interpreters and transformation tools)
- “bril-ocaml”
- “bril-llvm”
- “bril-swift”
- “bril-ts”
– Connect these to the central “Bril IR” to indicate they all consume or produce IR.
- Testing & Benchmark Infrastructure:
– Add nodes for “Testing (Turnt)” and “Benchmark Suites”.
- Documentation & Community Tools:
– Include a “Docs” node that points to the centralized documentation, language references, and examples.
- Build, CI/CD and Deployment:
– Show a “Build & CI/CD” component that represents GitHub workflows (build.yaml, docs.yaml, rust.yaml) and Makefiles.
– Illustrate how this component orchestrates builds, tests, and deployments across the entire ecosystem.

##### Important Architectural and Design Aspects
- Data flow:
– Indicate interaction flow between testing, benchmarking, and tooling.
- Distinguish components by type:
- Integration points:
– Emphasize the extensibility and separation of concerns (parsing, interpreting, language-specific processing) in your layout.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Tools
    subgraph "Frontend Tools"
        txt("bril-txt"):::tool
        jsonTool("bril2json"):::tool
    end

    %% Core IR Representation
    IR("Bril IR (JSON)"):::core

    %% Language Implementations
    subgraph "Language Implementations"
        interp("Reference Interpreter (Deno)"):::lang
        rs("bril-rs"):::lang
        ocaml("bril-ocaml"):::lang
        llvm("bril-llvm"):::lang
        swift("bril-swift"):::lang
        ts("bril-ts"):::lang
    end

    %% Quality Assurance
    subgraph "Quality Assurance"
        tests("Tests (Turnt)"):::test
        benchmarks("Benchmark Suites"):::test
    end

    %% Infrastructure
    subgraph "Infrastructure"
        workflows("GitHub Workflows"):::ci
        makefile("Makefile"):::ci
    end

    %% Documentation
    docs("Docs"):::docs

    %% Connections from Frontend Tools to Core IR
    txt -->|"converts"| IR
    jsonTool -->|"converts"| IR

    %% Connections from Core IR to Language Implementations
    IR -->|"feeds"| interp
    IR -->|"feeds"| rs
    IR -->|"feeds"| ocaml
    IR -->|"feeds"| llvm
    IR -->|"feeds"| swift
    IR -->|"feeds"| ts

    %% Connections for Quality Assurance
    interp -->|"validated_by"| tests
    IR -->|"benchmarked_by"| benchmarks
    tests -->|"triggers"| benchmarks

    %% Connections from Documentation to Core IR Specification
    docs -->|"specifies"| IR

    %% Connections from Infrastructure to Tools and Quality Assurance
    workflows -->|"orchestrates"| txt
    workflows -->|"orchestrates"| jsonTool
    workflows -->|"orchestrates"| IR
    workflows -->|"orchestrates"| interp
    workflows -->|"orchestrates"| tests
    makefile -->|"builds"| txt
    makefile -->|"builds"| jsonTool
    makefile -->|"builds"| IR

    %% Class Definitions
    classDef core fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef tool fill:#87CEFA,stroke:#000,stroke-width:2px;
    classDef lang fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef test fill:#F08080,stroke:#000,stroke-width:2px;
    classDef docs fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef ci fill:#FFB6C1,stroke:#000,stroke-width:2px;

    %% Click Events
    click docs "https://github.com/sampsyo/bril/tree/main/docs/"
    click IR "https://github.com/sampsyo/bril/tree/main/benchmarks/core/"
    click txt "https://github.com/sampsyo/bril/blob/main/bril-txt/briltxt.py"
    click jsonTool "https://github.com/sampsyo/bril/tree/main/bril-rs/bril2json/"
    click interp "https://github.com/sampsyo/bril/blob/main/brili.ts"
    click rs "https://github.com/sampsyo/bril/tree/main/bril-rs/"
    click ocaml "https://github.com/sampsyo/bril/tree/main/bril-ocaml/"
    click llvm "https://github.com/sampsyo/bril/tree/main/bril-llvm/"
    click swift "https://github.com/sampsyo/bril/tree/main/bril-swift/"
    click ts "https://github.com/sampsyo/bril/tree/main/bril-ts/"
    click tests "https://github.com/sampsyo/bril/tree/main/test/"
    click benchmarks "https://github.com/sampsyo/bril/tree/main/benchmarks/"
    click workflows "https://github.com/sampsyo/bril/tree/main/.github/workflows/"
    click makefile "https://github.com/sampsyo/bril/tree/main/Makefile"
```
