# teorth/equational_theories architecture

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

- Interactive diagram: https://gitdiagram.com/teorth/equational_theories
- Repository: https://github.com/teorth/equational_theories

## Overview

##### Main Components
- Core Formal Verification Engine – The Lean files (found under “equational_theories”, “Generated”, and related Lean source files). This is where the formal definitions, theorems, and verification proofs are developed using Lean and built via Lake.
- Data Management & Storage – The “data” directory holds raw inputs (edge lists, outcomes, CSV/JSON files), forcing rules, dual equations, and lists of magmas and equations. This component is the seed for the graph of implications.
- Scripted Processing & Analysis – The “scripts” folder contains many scripts (in Python, Ruby, etc.) that:
– Process implications extracted from Lean (e.g. extract_implications, process_implications)
– Explore magma structures (explore_magma, gather_small_magmas)
– Generate visualizations and graphs (generate_image, generate_graphviz_graph, transitive_reduction)
– Interface with external automated provers (Z3, Prover9/Mace4, Vampire, etc.)
- Document & Blueprint Components – The “blueprint” and “paper” directories hold LaTeX source files that document the theory, results, and overall research narrative.
- Web Front–Ends & Visualization – Directories like “home_page”, “widget”, “tools/fme”, and “graphiti” provide interactive dashboards, equation explorers, graph visualizations, and finite magma explorers. These components transform processed data and proof outcomes into visual and interactive formats.
- Miscellaneous Supporting Elements – Commentary (notes on individual equations in Markdown), GitHub configurations (workflows, CI/CD), and configuration files (lakefile.toml, flake.nix) which support integration and collaborative development.

##### Relationships & Data Flow
– Data originates from the “data” directory and/or is generated by manual input. Processing scripts extract, analyze, and transform this data.
– The Lean proofs (and the Generated directory) are continuously updated based on both human-written formalizations and results produced by automated scripts.
– Communication between these areas is orchestrated by automated tasks (in “scripts”) and integrated workflows (GitHub Actions and documented CI scripts).
– External dependencies (e.g. interactive theorem provers, external solvers like Z3) play a role in validating or refuting proposed implications, and their results are then reintegrated into the project’s Lean code base and visualization tools.

##### Architectural Patterns & Design Principles
– Modularity is central: separate directories for formal proofs, data, scripts, documentation, and web UX keep concerns distinct.
– There is a pipeline-like data flow: raw data → processing scripts → Lean verification → generation of derived artifacts → web-based dashboards.
– Emphasis on reproducibility and automation is evident with continuous integration workflows and automated updates (e.g., “update-dependencies.yml”, “update-labels.yml”).
– Multiple languages work together: Lean for theorem proving, Python and Ruby for scripting and data manipulation, LaTeX for scholarly documents, and Elm/TypeScript for visualization.

##### Relevant Technologies, Frameworks, and Libraries
– Lean (via lake build) for formal proofs and validation.
– Python/Ruby for scripting tasks (data extraction, transitive closure, graph generation).
– LaTeX (with accompanying .sty files and chapter files) for the paper/blueprint.
– Web technologies: HTML, CSS/SCSS, Elm, TypeScript/React (for the widget) to provide interactive interfaces.
– External theorem provers (Z3, Prover9/Mace4, Vampire) interfaced through scripts.
– GitHub Actions and Nix/flake for build automation and dependency management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface & External Integration"
        U("User/Researcher"):::user
        EP("External Provers"):::ci
    end

    subgraph "Web & Visualization"
        WH("Home Page"):::web
        WGT("Widget (Hasse Diagram)"):::web
        TFM("Finite Magma Explorer"):::web
    end

    subgraph "Processing Pipeline"
        D("Data Storage & Input"):::storage
        S("Scripted Processing & Analysis"):::proc
        L("Core Formal Verification (Lean)"):::proc
        E1("equational_theories"):::proc
        E2("Generated Proofs"):::proc
        BP("Blueprint Documents"):::doc
        PP("Paper Documents"):::doc
    end

    subgraph "CI/CD & Configurations"
        CI(".github (CI/CD)"):::ci
        LK("lakefile.toml"):::ci
        FN("flake.nix"):::ci
        CMT("Commentary"):::ci
    end

    %% Connections between User and Web Visualization
    U -->|"access"| WH
    U -->|"access"| WGT
    U -->|"access"| TFM

    %% Processing Pipeline connections
    D -->|"data_provenance"| S
    S -->|"updates"| L
    S -->|"documentation_input"| BP
    S -->|"documentation_input"| PP
    L -->|"produces_artifacts"| WH
    L -->|"produces_artifacts"| TFM
    EP -->|"validates"| L

    %% CI/CD connections to Processing Pipeline
    CI -->|"triggers"| S
    LK -->|"configures"| S
    FN -->|"configures"| S
    CMT -->|"provides_context"| BP
    CMT -->|"provides_context"| PP

    %% Internal structure of the Core Formal Verification Engine
    L -.->|"contains"| E1
    L -.->|"contains"| E2

    %% Styles
    classDef user fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef web fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef proc fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef storage fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef doc fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef ci fill:#FFA07A,stroke:#333,stroke-width:2px;

    %% Click Events
    click E1 "https://github.com/teorth/equational_theories/tree/main/equational_theories/"
    click E2 "https://github.com/teorth/equational_theories/tree/main/equational_theories/Generated"
    click D "https://github.com/teorth/equational_theories/tree/main/data/"
    click S "https://github.com/teorth/equational_theories/tree/main/scripts/"
    click BP "https://github.com/teorth/equational_theories/tree/main/blueprint/"
    click PP "https://github.com/teorth/equational_theories/tree/main/paper/"
    click WH "https://github.com/teorth/equational_theories/tree/main/home_page/"
    click WGT "https://github.com/teorth/equational_theories/tree/main/widget/"
    click TFM "https://github.com/teorth/equational_theories/tree/main/tools/fme/"
    click CI "https://github.com/teorth/equational_theories/tree/main/.github/"
    click LK "https://github.com/teorth/equational_theories/blob/main/lakefile.toml"
    click FN "https://github.com/teorth/equational_theories/blob/main/flake.nix"
    click CMT "https://github.com/teorth/equational_theories/tree/main/commentary/"
```
