# reasonml/reason architecture

> Architecture diagram of the GitHub repository reasonml/reason, 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/reasonml/reason
- Repository: https://github.com/reasonml/reason

## Overview

##### Main Components
- Build & CI Infrastructure:
– Include the GitHub workflows (in the .github/workflows/ directory), the various build configuration files (Makefile, dune, esy.json/opam files, flake.nix), and the build systems (dune, esy, opam, nix). These nodes show how the system is built, tested, and integrated.
- Core Language Tools & Libraries:
– Components such as the parsers and compilers: look in src/ for directories like “reason-parser”, “refmt” (the formatting tool), “refmttype” (type formatting) and “menhir-recover” (error recovery in parsing).
– “reason-merlin” is another component (found in src/reason-merlin) providing integration with editor tools, offering IDE support.
- Developer Tools & REPL:
– The “rtop” directory contains components for an interactive top-level (REPL) environment.
- Vendored/External Dependencies:
– The “vendored-omp” directory holds an integrated version of an external tool set (likely for OCaml migrations and parsetree transformations).
- Documentation & Testing:
– The “docs” folder (along with docs/site and several markdown documents) offers contributor and user documentation.
– The “test” directory incorporates various tests (across multiple OCaml versions) and also supports continuous validation of components.
- Integration & External Services:
– There’s a “js” folder indicating a JavaScript integration or tool (e.g., a Reason-compatible Node.js module).
– The package.json and npm-related files show that the project is also distributed via an npm package (@esy-ocaml/reason).

##### Relationships and Interactions
- The Core Language Tools (parsers, formatters, error recovery modules) are at the heart of the system; they interact closely with the developer tools (like rtop and reason-merlin) which provide interfaces for interactive editing and debugging.
- The build systems (dune, esy, opam) coordinate compilation, packaging, and dependency management for all core modules.
- CI/CD components (GitHub workflows, nix files) interact with the repository components to run tests and build the project.
- The documentation and tests are connected to almost every component to ensure that changes in the core libraries can be validated and understood by both contributors and end users.

##### Architectural Patterns/Design Principles
- Modularization: The directory structure separates concerns clearly (parsing, formatting, REPL, editor integration) which suggests a modular architecture.
- Layered Architecture: Lower layers provide the compiler and parsing abilities, while upper layers expose these capabilities to interactive tools (e.g., rtop, reason-merlin) and user interfaces.
- Integration with Multiple Build/Dependency Ecosystems: The availability of build files for dune, esy, opam, and even npm shows that the project is designed to be interoperable within both the OCaml and JavaScript ecosystems.

##### Relevant Technologies/Frameworks
- OCaml and Reason: The core language and its ecosystem.
- Dune Build System: For compiling OCaml code.
- OPAM and Esy: For package management and dependency handling.
- Menhir: Recognizable by “menhir-recover” implying parser error recovery using the Menhir parsing toolkit.
- Integration with JS: Use of npm and the “js” directory indicates JS toolchain aspects.
- CI/CD: Azure, CircleCI, and GitHub Actions workflows.

##### Specific Elements
- Incorporate labels for external dependencies (npm, opam packages) and show the connection between these dependencies and the build/integration systems.
- A high-level “ecosystem” node that connects the OCaml and JavaScript ecosystems through libraries like reason and appropriate packaging systems.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Build & CI Infrastructure
    subgraph "Build/CI Infrastructure"
        A["CI Workflows (.github/workflows)"]:::build
        B["Build Configurations (Makefile, dune, dune-project, esy.json, flake.nix, opam)"]:::build
    end

    %% Core Language Tools & Libraries
    subgraph "Core Language Tools & Libraries"
        C["reason-parser"]:::core
        D["refmt"]:::core
        E["refmttype"]:::core
        F["menhir-recover"]:::core
        G["reason-merlin"]:::core
    end

    %% Developer Tools & REPL
    subgraph "Developer Tools & REPL"
        H["rtop"]:::developer
    end

    %% Vendored/External Dependencies
    subgraph "Vendored/External Dependencies"
        I["vendored-omp"]:::vendor
    end

    %% Documentation & Testing
    subgraph "Documentation & Testing"
        J["docs"]:::doc
        K["test"]:::doc
    end

    %% Integration & External Services
    subgraph "Integration & External Services"
        L["js integration"]:::integration
        M["package.json"]:::integration
    end

    %% Relationships
    A --> B
    B -->|"builds"| C
    B -->|"builds"| H
    B -->|"triggers"| J
    B -->|"triggers"| K
    C -->|"parses"| D
    C -->|"errorRecovery"| F
    D -->|"formats"| E
    C -->|"integrates"| G
    I -->|"providesDeps"| C
    C -->|"feeds"| H
    C -->|"integrates"| L
    G --> H
    L --> M

    %% Click Events
    click A "https://github.com/reasonml/reason/tree/master/.github/workflows/"
    click B "https://github.com/reasonml/reason/tree/master/Makefile"
    click C "https://github.com/reasonml/reason/tree/master/src/reason-parser/"
    click D "https://github.com/reasonml/reason/tree/master/src/refmt/"
    click E "https://github.com/reasonml/reason/tree/master/src/refmttype/"
    click F "https://github.com/reasonml/reason/tree/master/src/menhir-recover/"
    click G "https://github.com/reasonml/reason/tree/master/src/reason-merlin/"
    click H "https://github.com/reasonml/reason/tree/master/rtop/"
    click I "https://github.com/reasonml/reason/tree/master/src/vendored-omp/"
    click J "https://github.com/reasonml/reason/tree/master/docs/"
    click K "https://github.com/reasonml/reason/tree/master/test/"
    click L "https://github.com/reasonml/reason/tree/master/js/"
    click M "https://github.com/reasonml/reason/blob/master/package.json"

    %% Styles
    classDef build fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef core fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef developer fill:#a9dfbf,stroke:#229954,stroke-width:2px;
    classDef vendor fill:#f5cba7,stroke:#d35400,stroke-width:2px;
    classDef doc fill:#d2b4de,stroke:#7d3c98,stroke-width:2px;
    classDef integration fill:#f7dc6f,stroke:#d4ac0d,stroke-width:2px;
```
