# cryspen/hax architecture

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

- Interactive diagram: https://gitdiagram.com/cryspen/hax
- Repository: https://github.com/cryspen/hax

## Overview

##### Project Type and Purpose
- Hax is a compiler-style tool (a Cargo subcommand) that takes Rust crates (restricted to a functional subset called “hacspec”) and translates them into formal back-end languages (F*, Coq, EasyCrypt, ProVerif). It consists of:
- A Rust-based CLI front end that hooks into `rustc` and/or uses a standalone “exporter” crate to extract the typed Rust THIR AST as JSON.
- An OCaml-based engine that ingests the JSON AST, runs a pipeline of simplification and elaboration phases, and dispatches to language-specific back ends.
- Auxiliary components: a JS driver + web playground, a Rust test harness for snapshot testing, examples, docs, and CI/deployment tooling (Nix, Docker, GitHub Actions).

##### High-Level Directory Structure
- Top-level crates:
- `cli/driver`, `cli/subcommands`: Rust code implementing `cargo hax`, orchestrating the workflow.
- `frontend/exporter`: Rust library/crate to extract the THIR AST to JSON.
- `engine/`: OCaml code organized as a library (`engine/lib/…`), a binary driver (`engine/bin/…`), and a set of back ends (`engine/backends/{coq,fstar,easycrypt,proverif}`).
- `test-harness/`: Rust crate for snapshot testing of `cargo hax` invocations.
- `cli/subcommands/engine_debug_webapp`: small web app (HTML+JS) for engine debugging in the browser.
- `docs/`, `examples/`: documentation and sample Rust crates.
- Build and deployment: Nix (`flake.nix`, `default.nix`), Docker (`.docker/`), GitHub workflows (`.github/workflows/`), `justfile`, etc.

##### Core System Components
A. Input Layer (Rust crate under test)
B. CLI Orchestration (Rust)
– “cargo hax” driver (uses `cli/driver`)
– Invokes the Rust exporter plugin (`frontend/exporter`) or calls into `rustc` to produce JSON AST
C. Exporter / Frontend (Rust)
– Parses/modifies THIR, outputs typed AST JSON
D. Engine Core (OCaml library)
– Pipeline of phases (`engine/lib/phases/*.ml`), AST utilities, analyses
E. Back End Plugins (OCaml modules under `engine/backends/`)
– Coq, F*, EasyCrypt, ProVerif, etc.
F. Output Layer
– Generated code/artifacts for the chosen backend
G. Test Harness & QA (Rust test-harness), Examples, Docs
H. Web Playground (JS driver + static site)

##### Architectural Patterns and Principles
- Pipeline architecture in the engine: discrete, named phases that successively transform the AST
- Plugin-style back ends: each target language is a separate module with a common interface
- Clear separation of concerns:
- Frontend (AST extraction)
- Core transformations (OCaml engine)
- Backend code generation
- Orchestration (Rust CLI)
- Cross-language FFI/IPC boundary between Rust and OCaml (via JSON + command-line invocation)
- Use of Nix/Docker/CI for reproducible builds and multi-platform support

##### Technologies, Frameworks, Libraries
- Rust crates: `cli/driver`, `frontend/exporter`, `test-harness`, examples, `hax-types`, `hax-lib`, etc.
- OCaml ecosystem: Dune build, `engine/lib/*`, `engine/backends/*`
- JavaScript: `engine/bin/js_driver.ml` → JS via js_of_ocaml, web static files under `cli/subcommands/engine_debug_webapp`
- Build and deployment: Nix Flakes, Docker, `just` command runner, GitHub Actions workflows

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    A["Rust Source Crate"]:::rust

    %% CLI Orchestration Layer
    subgraph "CLI Orchestration (Rust)" 
        direction TB
        B1["cli/driver"]:::rust
        B2["cli/subcommands"]:::rust
    end

    %% Exporter / Frontend Layer
    subgraph "Exporter / Frontend (Rust)" 
        direction TB
        C1["frontend/exporter"]:::rust
    end

    %% Engine Layer
    subgraph "Engine (OCaml)"
        direction TB
        subgraph "Engine Core (Library)" 
            direction TB
            D1["engine/lib"]:::ocaml
            D2["Phases (engine/lib/phases)"]:::ocaml
        end
        subgraph "Back Ends" 
            direction TB
            E1["Coq Backend"]:::ocaml
            E2["F* Backend"]:::ocaml
            E3["EasyCrypt Backend"]:::ocaml
            E4["ProVerif Backend"]:::ocaml
        end
    end

    %% Output Layer
    F["Generated Artifacts"]:::ocaml

    %% Test Harness & QA
    G["test-harness"]:::rust

    %% Web Playground
    subgraph "Web Playground (JS)" 
        direction TB
        H1["js_driver"]:::js
        H2["engine_debug_webapp"]:::js
    end

    %% Infrastructure
    subgraph "Infrastructure" 
        direction TB
        I1["Nix & justfile"]:::infra
        I2["Docker"]:::infra
        I3["CI Workflows"]:::infra
    end

    %% Data Flows
    A -->|"1. invoke"| B1
    B1 -->|"2. export AST"| C1
    C1 -->|"3. JSON AST"| D1
    D1 -->|pipeline| D2
    D2 -->|"4. to backends"| E1
    D2 -->|"4. to backends"| E2
    D2 -->|"4. to backends"| E3
    D2 -->|"4. to backends"| E4
    E1 -->|"code"| F
    E2 -->|"code"| F
    E3 -->|"code"| F
    E4 -->|"code"| F
    G -->|"5. test CLI"| B1
    H1 -->|"compile to JS"| D1
    H2 -->|"browser UI"| H1

    %% Click Events CLI Orchestration
    click B1 "https://github.com/cryspen/hax/blob/main/cli/driver/src/driver.rs"
    click B1 "https://github.com/cryspen/hax/blob/main/cli/driver/src/exporter.rs"
    click B1 "https://github.com/cryspen/hax/blob/main/cli/driver/src/callbacks_wrapper.rs"
    click B1 "https://github.com/cryspen/hax/blob/main/cli/driver/src/features.rs"
    click B2 "https://github.com/cryspen/hax/blob/main/cli/subcommands/src/cargo_hax.rs"

    %% Click Events Exporter
    click C1 "https://github.com/cryspen/hax/blob/main/frontend/exporter/src/lib.rs"
    click C1 "https://github.com/cryspen/hax/blob/main/frontend/exporter/src/body.rs"
    click C1 "https://github.com/cryspen/hax/blob/main/frontend/exporter/src/rustc_utils.rs"
    click C1 "https://github.com/cryspen/hax/blob/main/frontend/exporter/src/types/thir.rs"
    click C1 "https://github.com/cryspen/hax/blob/main/frontend/exporter/src/state.rs"

    %% Click Events Engine Core
    click D1 "https://github.com/cryspen/hax/blob/main/engine/lib/ast.ml"
    click D1 "https://github.com/cryspen/hax/blob/main/engine/lib/import_thir.ml"
    click D1 "https://github.com/cryspen/hax/blob/main/engine/lib/backend.ml"
    click D1 "https://github.com/cryspen/hax/blob/main/engine/lib/phase_utils.ml"
    click D2 "https://github.com/cryspen/hax/blob/main/engine/lib/phases/phase_cf_into_monads.ml"
    click D2 "https://github.com/cryspen/hax/blob/main/engine/lib/phases/phase_drop_blocks.ml"

    %% Click Events Back Ends
    click E1 "https://github.com/cryspen/hax/blob/main/engine/backends/coq/coq_backend.ml"
    click E1 "https://github.com/cryspen/hax/blob/main/engine/backends/coq/ssprove_backend.ml"
    click E2 "https://github.com/cryspen/hax/blob/main/engine/backends/fstar/fstar_backend.ml"
    click E2 "https://github.com/cryspen/hax/blob/main/engine/backends/fstar/fstar_ast.ml"
    click E3 "https://github.com/cryspen/hax/blob/main/engine/backends/easycrypt/easycrypt_backend.ml"
    click E4 "https://github.com/cryspen/hax/blob/main/engine/backends/proverif/proverif_backend.ml"

    %% Click Events Web Playground
    click H1 "https://github.com/cryspen/hax/blob/main/engine/bin/js_driver.ml"
    click H2 "https://github.com/cryspen/hax/blob/main/cli/subcommands/src/engine_debug_webapp/static/index.html"
    click H2 "https://github.com/cryspen/hax/blob/main/cli/subcommands/src/engine_debug_webapp/static/script.js"

    %% Click Events Test Harness
    click G "https://github.com/cryspen/hax/blob/main/test-harness/src/harness.rs"
    click G "https://github.com/cryspen/hax/blob/main/test-harness/src/command_hax_ext.rs"

    %% Click Events Infrastructure
    click I1 "https://github.com/cryspen/hax/blob/main/flake.nix"
    click I1 "https://github.com/cryspen/hax/tree/main/justfile"
    click I2 "https://github.com/cryspen/hax/tree/main/.docker/Dockerfile"
    click I3 "https://github.com/cryspen/hax/tree/main/.github/workflows/"

    %% Styles
    classDef rust fill:#D0E8FF,stroke:#0277BD,color:#000
    classDef ocaml fill:#FFE0B2,stroke:#EF6C00,color:#000
    classDef js fill:#C8E6C9,stroke:#2E7D32,color:#000
    classDef infra fill:#ECEFF1,stroke:#607D8B,color:#000
```
