# microsoft/ivy architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/ivy
- Repository: https://github.com/microsoft/ivy

## Overview

##### Main Components
- Core Ivy Engine – This is the heart of the system. It encompasses modules for parsing (ivy_parser.py, ivy_lexer.py), logic and type inference (ivy_logic.py, ivy_logic_parser.py, ivy_typeinfer.py, and related utilities) and AST management (e.g., ivy_ast.py).
- Ivy Compiler/Interpreter Layers – With files like ivy_compiler.py, ivy_to_cpp.py, and ivy_to_md.py, these modules translate or compile Ivy specifications into other forms (or even C++ code for verification).
- Interactive and Visualization Modules – Look at modules such as ivy_graph_ui.py, tk_ui.py, and JavaScript components (in ivy/js) for interactive diagramming and visualization. These handle the interactive sessions and visual representation of proofs.
- External Integration Points – Identify integrations with external solvers and tools. Submodules like “submodules/z3” indicate dependencies on the Z3 SMT solver, while “submodules/picotls” are used for other protocols. Also, the use of external libraries (for example, for graphical components) is evident.
- Documentation and Examples – The “doc” directory with numerous markdown and Ivy example files demonstrates a strong emphasis on guiding users through Ivy’s features, while the “examples” directory shows use cases spanning protocol designs that the tool can verify.
- Testing Infrastructure – With a comprehensive “test” directory covering a wide range of Ivy test cases and scenarios, it’s clear that automated tests (and even property or model checking tests) are central to validating Ivy’s functionality.
- User Interface & IDE Integration – The “vs/ext” directory indicates integration with Visual Studio (or other IDEs) via custom extensions, and “notebooks” provide interactive environments.

##### Out Relationships and Data Flows
- How the user (or developer) interacts with Ivy via command-line or interactive UI components.
- The input (protocol specifications) is funneled into the parser, building an Abstract Syntax Tree (AST).
- This AST is processed by the type inference and logic modules to generate proofs or verification condition outputs.
- The proof generation and validation step communicates with external components (such as the Z3 solver) to check correctness.
- After verification, interactive visualization modules present the proof’s progress/results to the user.
- Ancillary components (documentation, examples, and tests) support development and user guidance.

##### Architectural Patterns & Design Principles
- Modular Design – Each part (front-end for parsing/logic, interactive visualization, backend integration with solvers) is well separated and can be individually updated or extended.
- Layered Architecture – There is a clear layering from input (user interface) to processing (compiler, type inference and logic engine) and finally to output (visualizations, compiled code, or proofs).
- Integration with External Services – The design leverages external libraries (e.g., Z3 through its submodule) to handle heavy lifting in SMT solving and automated reasoning.

- Then, illustrate the connection from the Logic Engine to “External SMT Solver (Z3)” and any other integrated services.
- On another branch, include the documentation and interactive visualization components (graphical UI modules, notebook interfaces, VS extensions).
- Optionally, indicate the “Test Suite” as a separate module interacting with almost every component to validate functionality.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    UDE("User/Developer"):::input
    CLI("UI/Command-Line Interfaces"):::ui

    %% Core Ivy Engine Subgraph
    subgraph "Core Ivy Engine"
        CORE1("Ivy Parser"):::core
        CORE2("Ivy Logic"):::core
        CORE3("Ivy Logic Parser"):::core
        CORE4("Ivy AST"):::core
        CORE5("Type Inference"):::core
    end

    %% Ivy Compiler/Interpreter Layers Subgraph
    subgraph "Ivy Compiler/Interpreter Layers"
        COMP1("Ivy Compiler"):::compiler
        COMP2("Ivy to C++"):::compiler
        COMP3("Ivy to MD"):::compiler
    end

    %% Interactive and Visualization Modules Subgraph
    subgraph "Interactive and Visualization Modules"
        VIZ1("Ivy Graph UI"):::viz
        VIZ2("TK UI"):::viz
        VIZ3("JavaScript UI"):::viz
    end

    %% External Integration Points Subgraph
    subgraph "External Integration Points"
        EXT1("Z3 SMT Solver"):::external
        EXT2("Picotls"):::external
    end

    %% Documentation and Examples Subgraph
    subgraph "Documentation and Examples"
        DOC1("Documentation"):::doc
        DOC2("Examples"):::doc
    end

    %% Testing Infrastructure
    TEST1("Test Suite"):::test

    %% User Interface & IDE Integration Subgraph
    subgraph "User Interface & IDE Integration"
        IDE1("VS Extensions"):::ide
        IDE2("Notebooks"):::ide
    end

    %% Connections
    UDE -->|"uses"| CLI
    CLI -->|"sends specifications"| CORE1
    CLI -->|"initiates interactive sessions"| VIZ1
    CORE1 -->|"builds AST"| CORE4
    CORE1 -->|"triggers type analysis"| CORE5
    CORE2 -->|"processes logic"| CORE4
    CORE3 -->|"assists logic parsing"| CORE2
    CORE4 -->|"feeds verification queries"| EXT1
    CORE5 -->|"supports logic engine"| CORE2
    CORE2 -->|"provides proof data"| VIZ1
    CORE1 -->|"passes AST"| COMP1
    COMP1 -->|"translates to C++"| COMP2
    COMP1 -->|"translates to Markdown"| COMP3
    COMP2 -->|"outputs verification code"| VIZ1
    COMP3 -->|"outputs documentation format"| DOC1
    TEST1 ---|"validates"| CORE1
    TEST1 ---|"validates"| COMP1
    TEST1 ---|"validates"| VIZ2
    DOC2 ---|"guides usage of"| IDE1
    CLI ---|"integrated in"| IDE2
    DOC1 ---|"assists"| UDE

    %% Styles
    classDef input fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef ui fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef core fill:#82e0aa,stroke:#333,stroke-width:2px;
    classDef compiler fill:#d1f2eb,stroke:#333,stroke-width:2px;
    classDef viz fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef external fill:#f5cba7,stroke:#333,stroke-width:2px;
    classDef doc fill:#fcf3cf,stroke:#333,stroke-width:2px;
    classDef test fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef ide fill:#d7bde2,stroke:#333,stroke-width:2px;

    %% Click Events for Core Ivy Engine
    click CORE1 "https://github.com/microsoft/ivy/blob/master/ivy/ivy_parser.py"
    click CORE2 "https://github.com/microsoft/ivy/blob/master/ivy/ivy_logic.py"
    click CORE3 "https://github.com/microsoft/ivy/blob/master/ivy/ivy_logic_parser.py"
    click CORE4 "https://github.com/microsoft/ivy/blob/master/ivy/ivy_ast.py"
    click CORE5 "https://github.com/microsoft/ivy/blob/master/ivy/type_inference.py"

    %% Click Events for Ivy Compiler/Interpreter Layers
    click COMP1 "https://github.com/microsoft/ivy/blob/master/ivy/ivy_compiler.py"
    click COMP2 "https://github.com/microsoft/ivy/blob/master/ivy/ivy_to_cpp.py"
    click COMP3 "https://github.com/microsoft/ivy/blob/master/ivy/ivy_to_md.py"

    %% Click Events for Interactive and Visualization Modules
    click VIZ1 "https://github.com/microsoft/ivy/blob/master/ivy/ivy_graph_ui.py"
    click VIZ2 "https://github.com/microsoft/ivy/blob/master/ivy/tk_ui.py"
    click VIZ3 "https://github.com/microsoft/ivy/tree/master/ivy/js/"

    %% Click Events for External Integration Points
    click EXT1 "https://github.com/microsoft/ivy/tree/master/submodules/z3"
    click EXT2 "https://github.com/microsoft/ivy/tree/master/submodules/picotls"

    %% Click Events for Documentation and Examples
    click DOC1 "https://github.com/microsoft/ivy/tree/master/doc/"
    click DOC2 "https://github.com/microsoft/ivy/tree/master/examples/"

    %% Click Events for Testing Infrastructure
    click TEST1 "https://github.com/microsoft/ivy/tree/master/test/"

    %% Click Events for User Interface & IDE Integration
    click IDE1 "https://github.com/microsoft/ivy/tree/master/vs/ext"
    click IDE2 "https://github.com/microsoft/ivy/tree/master/notebooks/"
```
