# pschachte/wybe architecture

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

- Interactive diagram: https://gitdiagram.com/pschachte/wybe
- Repository: https://github.com/pschachte/wybe

## Overview

##### Project Type and Purpose
- The project is a compiler for the Wybe programming language. Its primary purpose is to transform Wybe source code (which combines declarative and imperative elements) into executable code using a pipeline of parsing, analysis, optimization, and code-generation passes.
- The README, along with files such as INSTALL.md and the user guide (WYBE.md), clarifies that the project is an early-stage compiler written in Haskell and leveraging LLVM.

##### Major Components
a. Frontend (Parsing & Lexical Analysis):
– This covers the scanner, parser, and AST construction modules (see files like src/Scanner.hs, src/Parser.hs, src/AST.hs).

b. Semantic Analysis & Intermediate Representations:
– Modules such as AliasAnalysis.hs, Analysis.hs, Normalise.hs, Unbranch.hs, Types.hs, etc., manage the semantic verification and intermediate representations.

c. Optimization / Transformation:
– Modules like Optimise.hs, Transform.hs, Expansion.hs, Flatten.hs, etc., perform optimization and code transformations.
– Link: From “Semantic Analysis” to “Optimizer/Transformer” labelled “apply optimization/transformation passes” (showing that the verified IR is processed to improve performance and prepare for code generation).

d. Code Generation / Backend:
– Key files such as Emit.hs, LLVM.hs, Macho.hs, and others are responsible for generating target code using external tools (LLVM infrastructure).
– Link: From “Optimizer/Transformer” to “Code Generation” labelled “generate executable or intermediate code” (explaining that the optimized IR is passed to backend modules to generate machine code or LLVM IR).

e. External Dependencies and Build/Tooling Components:
– Include build artifacts (Makefile, stack.yaml, wybe.cabal) and continuous integration configuration (.github/workflows for Ubuntu and macOS).
– Also add a link from “LLVM Compiler Infrastructure” to “Code Generation” labelled “external codegen dependency” (demonstrating that the compiler relies on LLVM for final code generation).

f. Library Support:
– The “wybelibs” directory (with files such as array.wybe, bool.wybe, etc.) contains libraries that may be linked or imported during compilation.

g. Testing and Documentation:
– The “test-cases” directory holds an extensive suite of test files (.wybe, .exp, and scripts) representing the regression and example cases used to verify the compiler.
– Link: From “Compiler” to “Test Cases” labelled “regression testing / verification” (this connection indicates that test inputs are used to validate compiler behavior).
– The “documentation” directory and README provide guidelines for users and contributors.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Source["Input Wybe Source Code"]:::external

    subgraph "Compiler Source (src)"
        FE["Frontend: Parser/Scanner/AST"]:::core
        SA["Semantic Analysis & IR"]:::core
        OPT["Optimizer/Transformer"]:::core
        BG["Backend Code Generation"]:::core
    end

    BuildTools["Build Tools/Configuration"]:::build
    Libraries["wybelibs (Language Libraries)"]:::lib
    TestCases["Test Cases"]:::external
    Documentation["Documentation"]:::doc
    LLVM["LLVM Compiler Infrastructure"]:::llvm

    %% Core Compilation Pipeline
    Source -->|"Lexical_analysis_and_parsing:_raw_source_processed_into_AST"| FE
    FE -->|"AST_produced;_semantic_checking_and_IR_construction"| SA
    SA -->|"IR_optimization_and_transformation"| OPT
    OPT -->|"convert_optimized_IR_to_target_code"| BG
    LLVM -->|"external_codegen_dependency:_compiler_relies_on_LLVM"| BG

    %% External Dependencies to Compiler Source
    BuildTools -->|"orchestrates_building_and_testing"| FE
    TestCases -->|"regression_testing/verification"| FE
    Documentation -->|"user_guide_&_design_documentation_reference"| FE
    Libraries -->|"language_libraries_support"| BG

    %% Click Events for Frontend (Parsing & Lexical Analysis)
    click FE "https://github.com/pschachte/wybe/blob/master/src/Scanner.hs"
    click FE "https://github.com/pschachte/wybe/blob/master/src/Parser.hs"
    click FE "https://github.com/pschachte/wybe/blob/master/src/AST.hs"

    %% Click Events for Semantic Analysis & Intermediate Representations
    click SA "https://github.com/pschachte/wybe/blob/master/src/AliasAnalysis.hs"
    click SA "https://github.com/pschachte/wybe/blob/master/src/Analysis.hs"
    click SA "https://github.com/pschachte/wybe/blob/master/src/Normalise.hs"
    click SA "https://github.com/pschachte/wybe/blob/master/src/Unbranch.hs"
    click SA "https://github.com/pschachte/wybe/blob/master/src/Types.hs"

    %% Click Events for Optimization / Transformation
    click OPT "https://github.com/pschachte/wybe/blob/master/src/Optimise.hs"
    click OPT "https://github.com/pschachte/wybe/blob/master/src/Transform.hs"
    click OPT "https://github.com/pschachte/wybe/blob/master/src/Expansion.hs"
    click OPT "https://github.com/pschachte/wybe/blob/master/src/Flatten.hs"

    %% Click Events for Code Generation / Backend
    click BG "https://github.com/pschachte/wybe/blob/master/src/Emit.hs"
    click BG "https://github.com/pschachte/wybe/blob/master/src/LLVM.hs"
    click BG "https://github.com/pschachte/wybe/blob/master/src/Macho.hs"

    %% Click Events for Build Tools/Configuration
    click BuildTools "https://github.com/pschachte/wybe/tree/master/Makefile"
    click BuildTools "https://github.com/pschachte/wybe/blob/master/stack.yaml"
    click BuildTools "https://github.com/pschachte/wybe/blob/master/wybe.cabal"
    click BuildTools "https://github.com/pschachte/wybe/tree/master/.github/workflows"

    %% Click Event for Library Support
    click Libraries "https://github.com/pschachte/wybe/tree/master/wybelibs"

    %% Click Event for Testing
    click TestCases "https://github.com/pschachte/wybe/tree/master/test-cases"

    %% Click Events for Documentation
    click Documentation "https://github.com/pschachte/wybe/tree/master/documentation"
    click Documentation "https://github.com/pschachte/wybe/blob/master/README.md"
    click Documentation "https://github.com/pschachte/wybe/blob/master/WYBE.md"
    click Documentation "https://github.com/pschachte/wybe/blob/master/INSTALL.md"

    %% Styles
    classDef external fill:#ABEBC6,stroke:#138D75,stroke-width:2px;
    classDef core fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef build fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef lib fill:#F5CBA7,stroke:#D35400,stroke-width:2px;
    classDef doc fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef llvm fill:#F1948A,stroke:#C0392B,stroke-width:2px;
```
