# moratori/clover architecture

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

- Interactive diagram: https://gitdiagram.com/moratori/clover
- Repository: https://github.com/moratori/clover

## Overview

##### Main Components
- Core Proof Engine: Representing the heart of the system that performs logical proofs, including implementation of the Knuth-Bendix completion algorithm and resolution-based inference. This includes modules such as:
– The resolution module (e.g., src/resolution.lisp)
– Completion/rewrite module (e.g., src/rewrite.lisp & src/simplify.lisp)
– Unification and term manipulation (e.g., src/unify.lisp, src/substitute.lisp, src/termorder.lisp)
- Parsing & Conversion: Modules that take input expressions and convert them into internal representations (e.g., src/parser.lisp, src/converter.lisp)
- Search Algorithms: Components for exploring derivations and proofs using algorithms like A*, DFS, IDDFS (e.g., src/search/astar.lisp, src/search/dfs.lisp, src/search/iddfs.lisp, src/search/extractor.lisp, src/search/common.lisp)
- User Interface & REPL: Components managing command-line interaction, batch execution, and user inputs (e.g., src/ui/main.lisp, src/ui/repl.lisp, src/ui/batch.lisp, src/ui/util.lisp)
- Utility & Support Modules: Including logging, error management, and additional utility functions (e.g., src/util.lisp, src/conditions.lisp, src/property.lisp, src/multicompletion.lisp, src/multiprocess.lisp)

##### Relationships and Interactions
- Input Handling: The user enters expressions via either the REPL or by passing a file in batch mode. The UI module (CLI front-end) then sends this data to the Parser.
- Transformation Pipeline: The Parser interprets the input into internal data structures, then passes these to the Converter for any required normalization.
- Proof Engine Interaction: Once parsed, the internal representations are sent to the proof engine, which branches out to the different strategies:
– Resolution algorithm for logical expressions.
– Term rewriting and completion algorithms for equality proofs.
The Search modules support these by handling the search space (via DFS, A*, etc.) during the proof process.
- Result Reporting: After processing, the engine returns a result (proof found, non-provable, irreducible form, etc.) that is handled by the UI and either displayed on the command line or saved if Graphviz code for a proof tree is generated.
- Testing & CI: A test suite (located in the tests directory) interacts with the modules through similar interfaces to ensure correctness. Continuous integration files (like .travis.yml and .github workflows) imply automated testing and release management flows.

##### Architectural Patterns & Design Principles
- Modular Decomposition: The system is organized into logically separated modules (parsing, conversion, search, rewriting, and UI), each encapsulated in its own file or directory.
- Pipeline Design: There is a linear flow from input -> parsing -> proof engine -> UI, with branching for different proof techniques.
- Functional Decomposition: Each component (for example, each search algorithm like A*, DFS, IDDFS) has a clear single responsibility.
- Extensibility: The design allows for potential extensions. For example, adding new search strategies or interactive commands in the REPL is straightforward given the modular design.

##### Relevant Technologies & Libraries
- Common Lisp: The primary language used across the system.
- Quicklisp/ASDF: Build and dependency management is likely handled through ASDF systems, as seen with files like clover.asd.
- Roswell: Build scripts related to Roswell (a Lisp installer/launcher) indicate the environment required to run the project.
- CI/CD & Testing Tools: GitHub workflows, Travis CI configurations, and shell scripts (like run-all-tests.sh) sustain quality and releases.
- Graphviz: There is an option to output the proof tree in Graphviz format, indicating integration with external visualization tools.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface & REPL Subgraph
    subgraph "User Interface & REPL"
        UI_main["Main UI"]
        UI_repl["REPL"]
        UI_batch["Batch Execution"]
        UI_util["UI Utilities"]
        UIAll["User Interface Aggregate"]
    end

    %% Parsing & Conversion Subgraph
    subgraph "Parsing & Conversion"
        Parser["Parser"]
        Converter["Converter"]
    end

    %% Core Proof Engine Subgraph
    subgraph "Core Proof Engine"
        PStart["Proof Engine Start"]
        
        subgraph "Resolution / Rewrite"
            resolution["Resolution Module"]
            rewrite["Rewrite Module"]
            simplify["Simplify Module"]
        end
        
        subgraph "Unification"
            unify["Unification - Unify"]
            substitute["Unification - Substitute"]
            termorder["Unification - Term Order"]
        end
        
        subgraph "Search Algorithms"
            astar["A* Search"]
            dfs["DFS Search"]
            iddfs["IDDFS Search"]
            extractor["Extractor"]
            common["Common Search"]
        end
        
        PEnd["Proof Outcome"]
    end

    %% Utility & Support Modules Subgraph
    subgraph "Utility & Support Modules"
        U_util["Util"]
        U_conditions["Conditions"]
        U_property["Property"]
        U_multicompletion["MultiCompletion"]
        U_multiprocess["MultiProcess"]
    end

    %% Connections between major components
    UIAll -->|"input_expressions"| Parser
    Parser -->|"parse_tokens"| Converter
    Converter -->|"parsed_data"| PStart

    %% Branching from Proof Engine Start to Resolution/Rewrite modules
    PStart -->|"resolve"| resolution
    PStart -->|"rewrite"| rewrite
    PStart -->|"simplify"| simplify

    %% Branching from Proof Engine Start to Unification modules
    PStart -->|"unify"| unify
    PStart -->|"substitute"| substitute
    PStart -->|"term_order"| termorder

    %% Branching from Proof Engine Start to Search Algorithms modules
    PStart -->|"astar"| astar
    PStart -->|"dfs"| dfs
    PStart -->|"iddfs"| iddfs
    PStart -->|"extract"| extractor
    PStart -->|"common"| common

    %% Convergence: Each branch sends its result to Proof Outcome
    resolution -->|"result"| PEnd
    rewrite -->|"result"| PEnd
    simplify -->|"result"| PEnd
    unify -->|"result"| PEnd
    substitute -->|"result"| PEnd
    termorder -->|"result"| PEnd
    astar -->|"result"| PEnd
    dfs -->|"result"| PEnd
    iddfs -->|"result"| PEnd
    extractor -->|"result"| PEnd
    common -->|"result"| PEnd

    %% Proof Outcome is sent back to the User Interface
    PEnd -->|"proof_result"| UIAll

    %% Utility & Support dashed connections supporting UI and Proof Engine
    UIAll -.->|"logging/errors"| U_util
    PStart -.->|"logging"| U_util

    %% Click Events for User Interface & REPL modules
    click UI_main "https://github.com/moratori/clover/blob/master/src/ui/main.lisp"
    click UI_repl "https://github.com/moratori/clover/blob/master/src/ui/repl.lisp"
    click UI_batch "https://github.com/moratori/clover/blob/master/src/ui/batch.lisp"
    click UI_util "https://github.com/moratori/clover/blob/master/src/ui/util.lisp"

    %% Click Events for Parsing & Conversion modules
    click Parser "https://github.com/moratori/clover/blob/master/src/parser.lisp"
    click Converter "https://github.com/moratori/clover/blob/master/src/converter.lisp"

    %% Click Events for Core Proof Engine - Resolution / Rewrite
    click resolution "https://github.com/moratori/clover/blob/master/src/resolution.lisp"
    click rewrite "https://github.com/moratori/clover/blob/master/src/rewrite.lisp"
    click simplify "https://github.com/moratori/clover/blob/master/src/simplify.lisp"

    %% Click Events for Core Proof Engine - Unification
    click unify "https://github.com/moratori/clover/blob/master/src/unify.lisp"
    click substitute "https://github.com/moratori/clover/blob/master/src/substitute.lisp"
    click termorder "https://github.com/moratori/clover/blob/master/src/termorder.lisp"

    %% Click Events for Core Proof Engine - Search Algorithms
    click astar "https://github.com/moratori/clover/blob/master/src/search/astar.lisp"
    click dfs "https://github.com/moratori/clover/blob/master/src/search/dfs.lisp"
    click iddfs "https://github.com/moratori/clover/blob/master/src/search/iddfs.lisp"
    click extractor "https://github.com/moratori/clover/blob/master/src/search/extractor.lisp"
    click common "https://github.com/moratori/clover/blob/master/src/search/common.lisp"

    %% Click Events for Utility & Support Modules
    click U_util "https://github.com/moratori/clover/blob/master/src/util.lisp"
    click U_conditions "https://github.com/moratori/clover/blob/master/src/conditions.lisp"
    click U_property "https://github.com/moratori/clover/blob/master/src/property.lisp"
    click U_multicompletion "https://github.com/moratori/clover/blob/master/src/multicompletion.lisp"
    click U_multiprocess "https://github.com/moratori/clover/blob/master/src/multiprocess.lisp"

    %% Styles for color-coding
    classDef ui fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef parser fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef engine fill:#abebc6,stroke:#333,stroke-width:2px;
    classDef search fill:#f7dc6f,stroke:#333,stroke-width:2px;
    classDef util fill:#f5b7b1,stroke:#333,stroke-width:2px;

    class UI_main,UI_repl,UI_batch,UI_util,UIAll ui;
    class Parser,Converter parser;
    class PStart,PEnd,resolution,rewrite,simplify,unify,substitute,termorder engine;
    class astar,dfs,iddfs,extractor,common search;
    class U_util,U_conditions,U_property,U_multicompletion,U_multiprocess util;
```
