# lemmih/lhc architecture

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

- Interactive diagram: https://gitdiagram.com/lemmih/lhc
- Repository: https://github.com/lemmih/lhc

## Overview

##### Project Type and Purpose
- LHC is a domain‐specific compiler toolchain: it takes Haskell 2010 source code, runs it through parsing, scope resolution, type checking, desugaring, core optimization, and IR lowering (to Bedrock), then emits LLVM IR.
- It also provides a minimal runtime system (RTS) with semispace garbage collection, exception support hooks, and optional libffi integration.

##### File Structure
- Top‐level “src” directory: contains the compiler driver and pipeline orchestration (Main.hs, CoreToBedrock.hs, RTS.hs).
- “bedrock” directory: Bedrock IR library (parsing, pretty‐printing, LLVM codegen, storage layouts, node sizing).
- “haskell-crux”: desugaring library for Core transformations.
- “packages/lhc-prim”: minimal base library for generated code.
- “rts”: the runtime system C code (semispace GC, stats, API).
- “libffi”: Haskell FFI bindings and examples for foreign calls.
- “tigr”: an experimental interpreter front end (separate tool).
- “examples” and “test”: user programs and test harness.

##### README for Additional Insights
- README shows the six‐stage pipeline with named libraries:
Parsing (haskell-src-exts) → Name resolution (haskell-scope) → Type-checking (haskell-tc) → Desugaring (haskell-crux) → Optimizing Core (LHC Core) → Bedrock IR → LLVM IR.
- It mentions “--keep-intermediate-files” to inspect each stage.

##### Main Components and Their Interactions
a. Compiler Front End (Haskell → Core):
- CLI/Driver (src/Main.hs, Interactive.hs)
- Parser (haskell-src-exts)
- Name Resolution (haskell-scope)
- Type Checking (haskell-tc)
- Desugaring (haskell-crux)
b. Core Optimizer and IR Lowering (Core → Bedrock):
- Core optimizer modules (src/Compiler/CoreToBedrock.hs and bedrock/src/Data/Bedrock/…)
- Simplification, inlining, register introduction, storage layout, node sizing, inline‐by‐cost.
c. Backend (Bedrock → LLVM):
- Bedrock LLVMGen (bedrock/src/Data/Bedrock/LLVMGen.hs)
- Pretty printing of .ll files
d. Runtime System and Libraries:
- RTS (rts/gc/semispace.c, api.c, stats.c)
- lhc-prim base library (packages/lhc-prim)
- libffi bindings (for foreign calls)
e. Tools/Tests/Examples:
- Example programs (`examples/`) compiled by CLI
- Test suite under `test/` and `lhc-regress`

##### Architectural Patterns and Design Principles
- Pipeline architecture: linear stages, each with its own library.
- Clear separation of concerns: front end vs optimizer vs backend vs runtime.
- Pluggable storage strategies: semi-space, fixed, etc., via typeclasses in bedrock.
- Modular Haskell libraries for each compilation phase.

##### Essential Architectural Elements to Capture
- Separation between front end, optimizer, backend, and runtime.
- Intermediate IR boundaries (Haskell AST, Core, Bedrock IR, LLVM IR).
- Pluggable GC/storage modules in bedrock.
- Integration of RTS C code and lhc-prim library at link time.
- External toolchain dependencies (Stack, LLVM, cabal-install).

[Source.hs] → (Parser) → (Resolver) → (Type Checker) → (Desugarer) → (Core Optimizer) → (Bedrock IR Generator) → (LLVMGen) → [output.ll]
↳ Link with (lhc-prim) + (RTS: GC, stats, API) + (libffi)

## Diagram (Mermaid)

```mermaid
graph TB
    %% CLI/Driver
    subgraph "CLI / Driver"
        CLI["Compiler Driver\n(src/Main.hs\nsrc/Interactive.hs)"]:::frontend
    end
    click CLI "https://github.com/lemmih/lhc/blob/master/src/Main.hs"
    click CLI "https://github.com/lemmih/lhc/blob/master/src/Interactive.hs"

    %% Front-End Stages
    subgraph "Front End" 
        Parser["Parser\n(haskell-src-exts)"]:::frontend
        Resolver["Name Resolver\n(haskell-scope)"]:::frontend
        TypeChecker["Type Checker\n(haskell-tc)"]:::frontend
        Desugar["Desugarer\n(haskell-crux)"]:::frontend
    end
    click Desugar "https://github.com/lemmih/lhc/blob/master/haskell-crux/src/Language/Haskell/Crux.hs"
    click Desugar "https://github.com/lemmih/lhc/blob/master/haskell-crux/src/Language/Haskell/Crux/*.hs"

    %% Optimizer & IR Lowering
    subgraph "Core & IR Lowering"
        CoreOpt["Core Optimizer\n(src/Compiler/CoreToBedrock.hs)"]:::optimizer
        BedrockCompile["Bedrock Compile\n(bedrock/src/Data/Bedrock/Compile.hs)"]:::optimizer
    end
    click CoreOpt "https://github.com/lemmih/lhc/blob/master/src/Compiler/CoreToBedrock.hs"
    click BedrockCompile "https://github.com/lemmih/lhc/blob/master/bedrock/src/Data/Bedrock/Compile.hs"

    %% Bedrock IR Library
    subgraph "Bedrock IR Library"
        BedrockCore["Core Library\n(bedrock/src/Data/Bedrock.hs)"]:::optimizer
        LLVMGen["LLVMGen\n(bedrock/src/Data/Bedrock/LLVMGen.hs)"]:::backend
        PrettyPrint["PrettyPrint\n(bedrock/src/Data/Bedrock/PrettyPrint.hs)"]:::backend
        StorageSemi["SemiSpace Storage\n(bedrock/src/Data/Bedrock/Storage/SemiSpace.hs)"]:::optimizer
        StorageFixed["Fixed Storage\n(bedrock/src/Data/Bedrock/Storage/Fixed.hs)"]:::optimizer
        StoragePlug["Pluggable Storage\n(bedrock/src/Data/Bedrock/Storage/Pluggable.hs)"]:::optimizer
    end
    click BedrockCore "https://github.com/lemmih/lhc/blob/master/bedrock/src/Data/Bedrock.hs"
    click LLVMGen "https://github.com/lemmih/lhc/blob/master/bedrock/src/Data/Bedrock/LLVMGen.hs"
    click PrettyPrint "https://github.com/lemmih/lhc/blob/master/bedrock/src/Data/Bedrock/PrettyPrint.hs"
    click StorageSemi "https://github.com/lemmih/lhc/blob/master/bedrock/src/Data/Bedrock/Storage/SemiSpace.hs"
    click StorageFixed "https://github.com/lemmih/lhc/blob/master/bedrock/src/Data/Bedrock/Storage/Fixed.hs"
    click StoragePlug "https://github.com/lemmih/lhc/blob/master/bedrock/src/Data/Bedrock/Storage/Pluggable.hs"

    %% Runtime & Libraries
    subgraph "Runtime & Libraries"
        RTS["Runtime System\n(src/RTS.hs)"]:::runtime
        GC["GC Semispace C\n(rts/gc/semispace.c)"]:::runtime
        APIc["RTS API\n(rts/api.c)"]:::runtime
        Stats["RTS Stats\n(rts/stats.c)"]:::runtime
        Prim["lhc-prim Library\n(packages/lhc-prim)"]:::runtime
        LibFFI["libffi Bindings\n(libffi/Foreign/LibFFI)"]:::runtime
    end
    click RTS "https://github.com/lemmih/lhc/blob/master/src/RTS.hs"
    click GC "https://github.com/lemmih/lhc/blob/master/rts/gc/semispace.c"
    click APIc "https://github.com/lemmih/lhc/blob/master/rts/api.c"
    click Stats "https://github.com/lemmih/lhc/blob/master/rts/stats.c"
    click Prim "https://github.com/lemmih/lhc/blob/master/packages/lhc-prim/src/LHC/Prelude.hs"
    click Prim "https://github.com/lemmih/lhc/blob/master/packages/lhc-prim/src/LHC/Prim.hs"
    click LibFFI "https://github.com/lemmih/lhc/blob/master/libffi/Foreign/LibFFI.hs"
    click LibFFI "https://github.com/lemmih/lhc/blob/master/libffi/Foreign/LibFFI/*.hs"
    click LibFFI "https://github.com/lemmih/lhc/blob/master/libffi/Foreign/LibFFI/Internal.hsc"
    click LibFFI "https://github.com/lemmih/lhc/blob/master/libffi/Foreign/LibFFI/FFITypes.hs"

    %% Tools & Tests
    subgraph "Tools, Examples & Tests"
        Examples["Examples\n(examples/*.hs)"]:::tools
        Tests["Test Suite\n(test/ & lhc-regress/)"]:::tools
    end

    %% Data Flow Connections
    CLI -->|reads source.hs| Parser
    Parser -->|AST| Resolver
    Resolver -->|Scoped AST| TypeChecker
    TypeChecker -->|Typed AST| Desugar
    Desugar -->|Core| CoreOpt
    CoreOpt -->|Core| BedrockCore
    BedrockCore -->|Bedrock IR| BedrockCompile
    BedrockCompile -->|Bedrock IR| LLVMGen
    LLVMGen -->|LLVM IR| Output["output.ll"]:::backend

    %% Linking
    Output -->|links with| Prim
    Output -->|links with| RTS
    Output -->|links with| LibFFI

    %% Tools/Test Flow
    CLI --> Examples
    CLI --> Tests

    %% Styles
    classDef frontend fill:#cfe2f3,stroke:#0366d6,color:#0366d6;
    classDef optimizer fill:#d9ead3,stroke:#6aa84f,color:#274e13;
    classDef backend fill:#fce5cd,stroke:#e69138,color:#7f6000;
    classDef runtime fill:#e7e6e6,stroke:#888888,color:#444444;
    classDef tools fill:#fff2cc,stroke:#d9b44a,color:#735c0f;
```
