# raphaelmeyer/crafting-interpreters architecture

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

- Interactive diagram: https://gitdiagram.com/raphaelmeyer/crafting-interpreters
- Repository: https://github.com/raphaelmeyer/crafting-interpreters

## Overview

##### Project Type and Purpose
- This repository contains two independent implementations of the Lox language from “Crafting Interpreters”:
a. **clox**: A bytecode‐based VM/interpreter written in C using CMake for build and simple unit specs.
b. **hlox**: A pure Haskell interpreter following the same language, structured around Cabal, with modules for scanning, parsing, resolution, and runtime.
- Purpose: Demonstrate language implementation techniques across two ecosystems.

##### File Structure Analysis
A. Top‐level
- .gitignore, LICENSE, README.md
- crafting‐interpreters.code‐workspace (IDE config)
B. clox/
- Build/config: CMakeLists.txt, CMakePresets.json, .clang-format
- src/:
– main.c (CLI entrypoint deciding REPL vs. file execution)
– debug.c/h (disassembler, logging)
– chunk.c/h (bytecode container, chunk specifications)
– memory.c/h (allocation, garbage collection stubs)
– value.c/h (value tagging, printing)
– *.spec.cc: unit tests for each module
- vendor/: third‐party code (if any)
C. hlox/
- TODO.md, crafting-interpreters.cabal, app/Main.hs (CLI entrypoint)
- src/Parser, src/Scanner, src/Resolver, src/Runtime, plus HLox.hs, Lox.hs glue modules
- test/: Hspec suites for scanner and integration
- Patterns: Both follow a classic compiler pipeline: Scanner → Parser → (for Haskell: Resolver) → Interpreter/VM → Output.

##### README Insights
- Minimal content; points back to the “Crafting Interpreters” book.

a. Main Components
- **Source Input**: CLI (main.c / Main.hs)
- **Scanner (Lexer)**: clox/src/… (embedded in chunk/main) & hlox/src/Scanner
- **Parser**: clox (part of main or a submodule) & hlox/src/Parser
- **Semantic Analysis / Resolver**: Only in hlox/src/Resolver
- **Bytecode Compiler / AST Evaluator**: clox/src/chunk + value modules vs. hlox’s AST evaluator in Runtime modules
- **Virtual Machine / Interpreter**: clox VM in chunk + debug; hlox’s Interpreter in Runtime/Interpreter.hs
- **Memory Management**: clox/src/memory; in Haskell GC is implicit
- **Tests**: spec files under clox/src and hlox/test
- **Build System**: CMake for clox, Cabal for hlox
b. Relationships & Data Flow
1. CLI component reads source text → feeds Scanner → emits token stream
2. Parser consumes tokens → builds AST
3. (Hlox only) Resolver walks AST → annotates scoping information
4. clox: Compiler emits bytecode chunks; hlox: Interpreter walks AST directly
5. VM/Interpreter executes code → utilizes memory module (clox) or Haskell runtime
6. Debug module (clox) can hook into VM to disassemble or trace
7. Test suites import each module layer to verify correctness
c. Architectural Patterns & Principles
- **Pipeline Architecture**: Clear phase boundaries—lexing, parsing, analysis, execution
- **Modularity**: Each concern in its own directory/module, facilitating testing
- **Single Responsibility**: Scanner never parses, Parser never executes, VM never lexes
- **Separation by Ecosystem**: C implementation emphasizes manual memory, Haskell emphasizes pure functions and type systems
d. Key Technologies & Frameworks
- C/CMake, clang-format for clox
- Haskell/GHC, Cabal, Hspec for hlox
- Unit testing harness (spec.cc files, Hspec)

##### Detail
- That components unique to one implementation (Resolver in hlox, chunk in clox) are clearly delineated

## Diagram (Mermaid)

```mermaid
graph TB
    %% C Implementation
    subgraph "C Implementation"
        CBuild["CMake / Clang-Format"]:::build
        CMain["main.c\n(CLI, Scanner, Parser)"]:::frontend
        CChunk["chunk.c / chunk.h\n(Bytecode Compiler)"]:::middle
        CVM["VM Execution"]:::backend
        CDebug["debug.c / debug.h\n(Debug Hooks)"]:::backend
        CMemory["memory.c / memory.h\n(Memory Management)"]:::backend
        CValue["value.c / value.h\n(Value Representation)"]:::backend

        CBuild --> CMain
        CMain -->|"Text"| CChunk
        CChunk -->|"Bytecode"| CVM
        CVM -->|"Executes"| CValue
        CVM -->|"Alloc/GC"| CMemory
        CVM -->|"Trace"| CDebug

        %% Tests
        CChunkSpec["chunk.spec.cc"]:::test
        CMainSpec["main.spec.cc"]:::test
        CValueSpec["value.spec.cc"]:::test

        CChunkSpec --> CChunk
        CMainSpec --> CMain
        CValueSpec --> CValue
    end

    %% Haskell Implementation
    subgraph "Haskell Implementation"
        HBuild["cabal file"]:::build
        HMain["Main.hs\n(CLI)"]:::frontend
        HHLox["HLox.hs\n(Lighting Pipeline)"]:::middle
        HLoxMod["Lox.hs\n(Pipeline Entry)"]:::middle
        HScanner["Scanner.hs"]:::frontend
        HToken["Token.hs"]:::frontend
        HParser["Parser.hs"]:::frontend
        HExpr["Expr.hs"]:::frontend
        HStmt["Stmt.hs"]:::frontend
        HLiteral["Literal.hs"]:::frontend
        HResolver["Resolver.hs"]:::middle
        HInterp["Interpreter.hs"]:::backend
        HEnv["Environment.hs"]:::backend
        HTypes["Types.hs"]:::backend
        HInst["Instance.hs"]:::backend
        HNative["Native.hs"]:::backend

        HBuild --> HMain
        HMain --> HHLox
        HHLox --> HLoxMod
        HLoxMod --> HScanner
        HScanner --> HParser
        HParser --> HResolver
        HResolver --> HInterp
        HInterp --> HEnv
        HInterp --> HTypes
        HInterp --> HInst
        HInterp --> HNative

        %% Tests
        HSpecScanner["ScannerSpec.hs"]:::test
        HSpec["Spec.hs"]:::test

        HSpecScanner --> HScanner
        HSpec --> HInterp
    end

    %% Click Events
    click CMain "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/clox/src/main.c"
    click CChunk "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/clox/src/chunk.c"
    click CChunk "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/clox/src/chunk.h"
    click CValue "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/clox/src/value.c"
    click CValue "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/clox/src/value.h"
    click CMemory "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/clox/src/memory.c"
    click CMemory "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/clox/src/memory.h"
    click CDebug "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/clox/src/debug.c"
    click CDebug "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/clox/src/debug.h"
    click CBuild "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/clox/CMakeLists.txt"
    click CBuild "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/clox/CMakePresets.json"
    click CBuild "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/clox/.clang-format"
    click CChunkSpec "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/clox/src/chunk.spec.cc"
    click CMainSpec "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/clox/src/main.spec.cc"
    click CValueSpec "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/clox/src/value.spec.cc"

    click HMain "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/hlox/app/Main.hs"
    click HHLox "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/hlox/src/HLox.hs"
    click HLoxMod "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/hlox/src/Lox.hs"
    click HScanner "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/hlox/src/Scanner/Scanner.hs"
    click HToken "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/hlox/src/Scanner/Token.hs"
    click HParser "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/hlox/src/Parser/Parser.hs"
    click HExpr "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/hlox/src/Parser/Expr.hs"
    click HStmt "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/hlox/src/Parser/Stmt.hs"
    click HLiteral "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/hlox/src/Parser/Literal.hs"
    click HResolver "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/hlox/src/Resolver/Resolver.hs"
    click HInterp "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/hlox/src/Runtime/Interpreter.hs"
    click HEnv "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/hlox/src/Runtime/Environment.hs"
    click HTypes "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/hlox/src/Runtime/Types.hs"
    click HInst "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/hlox/src/Runtime/Instance.hs"
    click HNative "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/hlox/src/Runtime/Native.hs"
    click HBuild "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/hlox/crafting-interpreters.cabal"
    click HSpecScanner "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/hlox/test/ScannerSpec.hs"
    click HSpec "https://github.com/raphaelmeyer/crafting-interpreters/blob/main/hlox/test/Spec.hs"

    %% Styles
    classDef build fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef frontend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef middle fill:#FFA500,stroke:#333,stroke-width:1px
    classDef backend fill:#FF6F61,stroke:#333,stroke-width:1px
    classDef test fill:#D3D3D3,stroke:#333,stroke-width:1px
```
