# webyrd/barliman architecture

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

- Interactive diagram: https://gitdiagram.com/webyrd/barliman
- Repository: https://github.com/webyrd/barliman

## Overview

##### Core system components
- UI / Editor Layer – Represented by the Cocoa application. This layer includes the main editor window, code entry pane(s), and test input/output fields. (Files in the “cocoa/Barliman” directory, Xcode project files, .xcodeproj)
- Synthesis Engine – A backend component that uses miniKanren-based relational interpreters and performs program synthesis based on partial definitions and tests (see “mk-and-rel-interp” directories in the cocoa subfolder, and additional synthesis experiments in “interpreter_experiments” and “interactive_editor_ideas”).
- External Process Controller – This component manages the launching and cleanup of external Chez Scheme processes. It dispatches queries (each test is evaluated in parallel by spawning instances of Chez Scheme) and collects their results.
- Semantics / Language Definitions – The project supports dynamic language definitions (the “miniScheme” language) and allows users to customize the semantics. Represent these rules as a separate module that feeds into the synthesis engine.
- Test and Example Suite – Multiple directories (e.g., “talk_examples_20161203”, “interesting_examples”, “paper_prototypes”) contain example programs, animated demonstrations, and test cases. These provide both demonstration of functionality and validation of the synthesis.
- Website/Documentation Module – The “.io.livecode.ch” directory contains web site components (HTML, JSON defaults, header/footer text) for hosting documentation or interactive examples.

##### Relationships and data flow between components
A. The UI Layer (Cocoa editor) is the primary point of interaction:
– It captures user input (code defining functions and tests).
– On changes, it sends a synthesis request to the Synthesis Engine.
B. The Synthesis Engine then parses the editor’s partial code and test inputs.
– It constructs miniKanren queries that encapsulate what the complete definition should be.
– It communicates with the External Process Controller to launch one or several Chez Scheme processes.
C. The External Process Controller manages these processes:
– It passes queries to Chez Scheme (located at /usr/local/bin/scheme per the README).
– It collects synthesized “best guesses” or error signals, and then conveys these back to the Synthesis Engine.
E. The Test/Example Suite and Documentation modules serve both as inputs (predefined test cases) and outputs (screenshots, animated demos) that help further validate and illustrate the system.

##### Architectural patterns and design principles
- Modular separation: Clearly designate separate modules for UI, synthesis logic, external process management, and language semantics.
- Parallel processing: Indicate that multiple Chez Scheme instances run in parallel for test evaluations, which is a critical performance and resource management element.
- Extensibility: Emphasize that the language semantics engine is configurable (users can add new language definitions) and that tests/examples can drive both synthesis and “auto-repair” functionalities.
- Resource management: Note cleanup responsibilities (e.g., killing stray Scheme processes) and the interplay between real-time user editing and heavy backend computations.

– Optionally, show configuration/layout elements for “Test Suite / Example Manager” and “Web Documentation Builder” (from the .io.livecode.ch directory).

##### Detail each component
– Include annotations such as “Handles interactive editing and displays real-time synthesis feedback” for the UI.
– For the synthesis engine, note “Receives partial definitions & tests, utilizes miniKanren relational interpreter, analyzes test compatibility.”
– For the external process controller, note “Manages parallel Chez Scheme sessions for code evaluation and synthesis.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI / Editor Layer
    subgraph "UI / Editor Layer"
        UI1["Cocoa/Swift (Barliman Editor)\nHandles interactive editing and real-time synthesis feedback"]:::ui
        UI2["Xcode Project\n(Barliman.xcodeproj)"]:::ui
    end

    %% Synthesis Engine
    subgraph "Synthesis Engine"
        SYN1["MiniKanren-based Synthesis Engine\nReceives partial definitions & tests, utilizes relational interpreters"]:::synth
        SYN2["mk-and-rel-interp\n(Relational Interpreter)"]:::synth
        SYN3["interpreter_experiments\n(Synthesis Experiments)"]:::synth
        SYN4["interactive_editor_ideas\n(Experimental Synthesis Ideas)"]:::synth
    end

    %% External Process Controller
    subgraph "External Process Controller"
        PROC["Chez Scheme Process Manager\nManages spawning and cleanup of external Chez Scheme processes"]:::process
    end

    %% Semantics / Language Definitions
    subgraph "Semantics / Language Definitions"
        SEM["MiniScheme Language Semantics\nImplements dynamic interpreter semantics"]:::semantics
    end

    %% Test and Example Suite
    subgraph "Test and Example Suite"
        TEST1["talk_examples_20161203\n(Example Programs)"]:::test
        TEST2["interesting_examples\n(Additional Examples)"]:::test
        TEST3["paper_prototypes\n(Prototype Tests)"]:::test
    end

    %% Website/Documentation Module
    subgraph "Website/Documentation Module"
        DOC["Web Documentation & Interactive Examples\nHosts website components for docs"]:::docs
    end

    %% Connections
    UI1 -->|"synthesis_request"| SYN1
    SYN1 -->|"sends_query"| PROC
    PROC -->|"returns_result"| SYN1
    SYN1 -->|"uses_semantics"| SEM
    TEST1 -.->|"provides_test_input"| SYN1
    TEST2 -.->|"provides_test_input"| SYN1
    TEST3 -.->|"provides_test_input"| SYN1
    DOC -.->|"guides_synthesis"| SYN1
    SYN1 -->|"updates_ui"| UI1

    %% Click Events for UI / Editor Layer
    click UI1 "https://github.com/webyrd/barliman/tree/master/cocoa/Barliman"
    click UI2 "https://github.com/webyrd/barliman/blob/master/cocoa/Barliman.xcodeproj"
    
    %% Click Events for Synthesis Engine
    click SYN2 "https://github.com/webyrd/barliman/tree/master/cocoa/Barliman/mk-and-rel-interp"
    click SYN3 "https://github.com/webyrd/barliman/tree/master/interpreter_experiments"
    click SYN4 "https://github.com/webyrd/barliman/tree/master/interactive_editor_ideas"
    
    %% Click Event for External Process Controller
    click PROC "https://github.com/webyrd/barliman/blob/master/cocoa/Barliman/RunSchemeOperation.swift"
    
    %% Click Event for Semantics / Language Definitions
    click SEM "https://github.com/webyrd/barliman/blob/master/cocoa/Barliman/mk-and-rel-interp/interp-dynamic.scm"
    
    %% Click Events for Test and Example Suite
    click TEST1 "https://github.com/webyrd/barliman/tree/master/talk_examples_20161203"
    click TEST2 "https://github.com/webyrd/barliman/tree/master/interesting_examples"
    click TEST3 "https://github.com/webyrd/barliman/tree/master/paper_prototypes"
    
    %% Click Event for Website/Documentation Module
    click DOC "https://github.com/webyrd/barliman/blob/master/.io.livecode.ch"

    %% Styles
    classDef ui fill:#f9c,stroke:#333,stroke-width:2px;
    classDef synth fill:#ccf,stroke:#333,stroke-width:2px;
    classDef process fill:#fc9,stroke:#333,stroke-width:2px;
    classDef semantics fill:#cfc,stroke:#333,stroke-width:2px;
    classDef test fill:#ff9,stroke:#333,stroke-width:2px;
    classDef docs fill:#c9f,stroke:#333,stroke-width:2px;
```
