# cisco/chezscheme architecture

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

- Interactive diagram: https://gitdiagram.com/cisco/chezscheme
- Repository: https://github.com/cisco/chezscheme

## Overview

##### Project type and purpose
- This is a programming-language implementation (Chez Scheme) comprising:
- A compiler (Scheme-to-native machine code)
- A run-time system (memory management, threading, I/O, exception handling)
- A programming environment (interactive shell/expeditor, debugger, profiler)
- Tooling for building, bootstrapping, testing, packaging, and documentation

##### File structure
- Top-level directories:
- c/             ← C source for compiler back-end, runtime, GC, FFI, primitives
- s/             ← Scheme source: compiler front-end, optimization passes (“nanopass”), boot code, libraries
- boot/          ← Bootstrapping Scheme image (petite.boot, scheme.boot, inc files)
- makefiles/     ← Platform-agnostic build logic (.zuo scripts, Makefile.in templates)
- .github/       ← CI workflows, build/test scripts
- examples/, mats/, tests… ← Example programs and test suites
- wininstall/    ← Windows installer definitions (WiX .wxs), packaging scripts
- unicode/       ← Data extraction scripts and Unicode database for text support

- Configuration files: configure, BUILDING, LICENSE, IMPLEMENTATION.md, README.md

##### Key insights from README
- Three principal runtime components: compiler, run-time system, programming environment
- Cross-platform support (Windows, Linux, macOS, BSDs, embedded architectures)
- Build and bootstrap process described in BUILDING and IMPLEMENTATION.md
- The build system uses “zuo” scripts alongside standard Makefiles

a. Main components
1. Source Layer
- User Scheme programs & libraries (examples/, s/, mats/)
- C sources for low-level system services (c/)
2. Compiler Layer
- Front-end (parser, AST) – in Scheme (s/)
- Nanopass pipelines – multiple transformation passes (s/)
- Back-end code generator – emits optimized machine code (c/)
3. Runtime System
- Garbage collector (c/gc-*.c)
- Threading, synchronization (c/thread.c/.h)
- I/O subsystem (c/io.c, compress-io.c)
- Exception & record management
- FFI interface to C (c/ffi.c, foreign.c)
4. Programming Environment
- Expeditor (interactive shell) (s/expeditor.ss, c/expeditor.c)
- Debugger, profiler, memory inspector
5. Build & Packaging
- Zuo scripts & Makefiles (makefiles/, configure)
- CI pipelines ( .github/workflows )
- Windows installer (wininstall/)
- Unicode data extraction (unicode/)
b. Relationships & data flow
- User invokes build scripts → zuo/Makefiles generate compiler & runtime artifacts
- Bootstrap process (boot/) → initial image loaded into runtime
- Compiler reads Scheme source → performs passes → emits native code → loaded into runtime
- Runtime executes native code → uses GC, threads, I/O, FFI to interact with OS and C libraries
- Expeditor interacts with compiler/runtime for REPL, debugging, profiling
- CI pipelines invoke build/test scripts → exercise examples/, mats/
c. Architectural patterns & principles
- Modular separation: front-end, middle-end (nanopass), back-end, runtime
- Bootstrapping via layered images, ensuring portability across architectures
- Data-driven automation: .zuo scripts and Makefile templates for cross-platform builds
- Clear layering: user code → compiler → runtime → OS
d. Key technologies & frameworks
- C (compiler back-end, runtime)
- Scheme (compiler front-end, passes, environment)
- Zuo build scripts (makefiles/lib.zuo)
- Makefile templates and autotools-style configure
- WiX toolset for Windows installers

- Compiler (e.g., blue)
- Runtime (e.g., green)
- Build system & CI (e.g., gray)
- User code & libraries (e.g., yellow)
- Source → Compiler → Native code → Runtime → OS
- Build scripts → Compiler & Runtime artifacts
- CI pipelines → Build & Test → Reports
- Connections with protocols or file formats (e.g., “AST”, “.o/.so”, “boot image”, “bytecode”)

##### Detailed capture of essential elements
- Front-end and nanopass pipeline in Scheme under s/
- Back-end code generator in C under c/
- GC strategies (gc-ocd, gc-oce, gc-par) as runtime modules
- Expeditor as the REPL interface
- Unicode data extraction feeding into text I/O subsystem
- Wininstall WiX modules generating MSI/MSM installers
- CI workflows (.github/workflows/*.yml and .sh) orchestrating build/test/release

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Code Layer
    subgraph "User Code & Libraries"
        direction TB
        UserScheme["Scheme Programs & Libraries"]:::usercode
        Examples["examples/, mats/, tests/"]:::usercode
    end

    %% Compiler Layer
    subgraph "Compiler Layer" 
        direction TB
        FrontEnd["Front-End (parser, AST)"]:::compiler
        Nanopass["Nanopass Pipeline"]:::compiler
        BackEnd["Back-End Code Generator"]:::compiler
    end

    %% Runtime System
    subgraph "Runtime System"
        direction TB
        GC["Garbage Collector"]:::runtime
        Thread["Threading & Sync"]:::runtime
        IO["I/O Subsystem"]:::runtime
        FFI["FFI Interface"]:::runtime
    end

    %% Programming Environment
    subgraph "Programming Environment"
        direction TB
        Expeditor["Expeditor (REPL)"]:::env
        DebugTools["Debugger & Profiler"]:::env
        BootImage["Bootstrapping Images & Code"]:::env
    end

    %% Build & CI
    subgraph "Build & Packaging"
        direction TB
        BuildScripts["Build & Bootstrap Scripts"]:::build
        CI["CI Workflows & Scripts"]:::build
        WinInstaller["Windows Installer Definitions"]:::build
        UnicodeData["Unicode Data Extraction"]:::build
    end

    %% Data & Control Flow
    UserScheme -->|"source"| FrontEnd
    Examples -->|"libraries"| Nanopass
    FrontEnd -->|"AST"| Nanopass
    Nanopass -->|"IR & Transforms"| BackEnd
    BackEnd -->|"machine code (.o/.so)"| GC
    BackEnd -->|"machine code"| Thread
    BackEnd -->|"machine code"| IO
    BackEnd -->|"machine code"| FFI
    GC -->|"memory"| BackEnd
    Thread -->|"threads"| BackEnd
    IO -->|"I/O ops"| BackEnd
    FFI -->|"calls C"| BackEnd
    BackEnd -->|"native code"| Expeditor
    Expeditor -->|"REPL"| BackEnd
    DebugTools -->|"debug/prof data"| BackEnd
    BootImage -->|"boot image"| Expeditor
    BuildScripts -->|"generate"| FrontEnd
    BuildScripts -->|"generate"| Nanopass
    BuildScripts -->|"generate"| BackEnd
    CI -->|"invoke build & test"| BuildScripts
    CI -->|"tests on"| Examples
    CI -->|"reports"| DebugTools
    WinInstaller -->|"package"| BackEnd
    UnicodeData -->|"data files"| IO

    %% Click Events
    click FrontEnd "https://github.com/cisco/chezscheme/blob/main/s/front.ss"
    click Nanopass "https://github.com/cisco/chezscheme/blob/main/s/cpnanopass.ss"
    click BackEnd "https://github.com/cisco/chezscheme/blob/main/c/main.c"
    click GC "https://github.com/cisco/chezscheme/blob/main/c/gc-ocd.c"
    click Thread "https://github.com/cisco/chezscheme/blob/main/c/thread.c"
    click IO "https://github.com/cisco/chezscheme/blob/main/c/io.c"
    click FFI "https://github.com/cisco/chezscheme/blob/main/c/ffi.c"
    click Expeditor "https://github.com/cisco/chezscheme/blob/main/s/expeditor.ss"
    click DebugTools "https://github.com/cisco/chezscheme/blob/main/s/debug.ss"
    click BootImage "https://github.com/cisco/chezscheme/blob/main/boot/pb/petite.boot"
    click BuildScripts "https://github.com/cisco/chezscheme/blob/main/build.zuo"
    click CI "https://github.com/cisco/chezscheme/blob/main/.github/workflows/ci.yml"
    click WinInstaller "https://github.com/cisco/chezscheme/blob/main/wininstall/product.wxs"
    click UnicodeData "https://github.com/cisco/chezscheme/blob/main/unicode/extract-common.ss"

    %% Styles
    classDef usercode fill:#f9f,stroke:#333,stroke-width:1px
    classDef compiler fill:#bbf,stroke:#333,stroke-width:1px
    classDef runtime fill:#bfb,stroke:#333,stroke-width:1px
    classDef env fill:#fbf,stroke:#333,stroke-width:1px
    classDef build fill:#ddd,stroke:#333,stroke-width:1px
```
