# ivan-sergeyev/seymour architecture

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

- Interactive diagram: https://gitdiagram.com/ivan-sergeyev/seymour
- Repository: https://github.com/ivan-sergeyev/seymour

## Overview

##### Project type and purpose
- This is a formal-verification/math project written in Lean 4 whose goal is to verify Seymour’s decomposition theorem for regular matroids.
- Beyond the core proofs (under the Seymour/… tree), it includes a documentation “blueprint” (LaTeX + web), a small alternate blueprint, a Jekyll-based home page, build scripts, and CI workflows.

##### Main components
a. Source Code
- Lean 4 theorem files under `Seymour/…` and the root `Seymour.lean` entry point
- Blueprint generator sources under `blueprint/src` and `blueprint_2`
- Jekyll site under `home_page/`
- Utility scripts under `scripts/`
b. Build & Packaging
- Lake (`lakefile.toml`, `lake-manifest.json`, `lean-toolchain`) orchestrates compilation of Lean code and documentation
- Third‐party dependencies: Mathlib4, LeanProject template, leanblueprint, doc-gen4
c. Documentation Pipeline
- Lean code → doc-gen4 → generated HTML (dependency graph, API docs)
- Lean code → leanblueprint → LaTeX blueprint under `blueprint/src` → PDF + web version
- Alternate blueprint under `blueprint_2` (static LaTeX → PDF)
- Jekyll (`home_page/`) pulls markdown, built assets, and hosts via GitHub Pages
d. Continuous Integration
- `.github/workflows/build-project.yml`: runs `lake build`, documentation generation, blueprint build
- `.github/workflows/lint.yml`: runs `lake lint` checks
- `.github/workflows/update*.yml`: automatic dependency updates
e. External Services
- GitHub (repo, Actions, Pages)
- Online references (Truemper monograph, Oxley text, etc.)

##### Relationships & Data Flow
- Developer pushes code → GitHub Actions triggers Lake build → Lean proofs check → doc-gen4 + leanblueprint run → artifacts (HTML, PDF) output
- Lake fetches Mathlib4 and other dependencies from GitHub
- Generated docs & site assets are deployed to GitHub Pages
- Scripts (`update_mathlib`, `customize_template.py`) modify local templates or update library versions

##### Architectural patterns & design principles
- Modular organization of proofs by topic (Basic, Matrix, Matroid)
- Documentation-as-code: proofs double as source for docs
- Static site generation (Jekyll) for landing page
- CI-driven pipeline combining build, lint, test, doc generation, and deployment

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Source Layer
    subgraph "Source Layer"
        direction TB
        SeymourEntry["Seymour.lean"]:::code
        Basic["Seymour/Basic/*.lean"]:::code
        Matrix["Seymour/Matrix/*.lean"]:::code
        Matroid["Seymour/Matroid/**/*.lean"]:::code
        EasyDir["Seymour/EasyDirection.lean"]:::code
        HardDir["Seymour/HardDirection.lean"]:::code

        blueprint_src["blueprint/src"]:::code
        blueprint_2["blueprint_2"]:::code
        home_page["home_page/"]:::code
        scripts["scripts/"]:::code
    end

    %% Build Layer
    subgraph "Build Layer"
        direction TB
        Lake["Lake (lakefile.toml)"]:::build
        DocGen["doc-gen4"]:::build
        LBPrint["leanblueprint"]:::build
        JekyllGen["Jekyll"]:::build
    end

    %% Artifacts Layer
    subgraph "Artifacts Layer"
        direction TB
        HTMLDocs["HTML Docs"]:::docs
        PDFBlueprint["PDF Blueprint"]:::docs
        WebBlueprint["Web Blueprint"]:::docs
        JekyllSite["Jekyll Site"]:::docs
    end

    %% CI Layer
    subgraph "CI Layer"
        direction TB
        BuildWF["build-project.yml"]:::ci
        LintWF["lint.yml"]:::ci
        UpdateWF["update-*.yml"]:::ci
    end

    %% External Services
    subgraph "External"
        direction TB
        Mathlib4["Mathlib4"]:::external
        GitHub["GitHub"]:::external
        GitHubPages["GitHub Pages"]:::external
    end

    %% Connections Source -> Build
    SeymourEntry -->|compile| Lake
    Basic -->|compile| Lake
    Matrix -->|compile| Lake
    Matroid -->|compile| Lake
    EasyDir -->|compile| Lake
    HardDir -->|compile| Lake
    blueprint_src -->|input| LBPrint
    blueprint_src -->|input| Lake
    blueprint_2 -->|input| Lake
    home_page -->|input| JekyllGen
    scripts -->|invoke| Lake
    scripts -->|invoke| LintWF

    %% Dependencies
    Lake -->|pull| Mathlib4
    Lake -->|pull| GitHub
    Lake -->|run| DocGen
    Lake -->|run| LBPrint

    %% Build -> Artifacts
    DocGen -->|generate| HTMLDocs
    LBPrint -->|generate| PDFBlueprint
    LBPrint -->|generate| WebBlueprint
    HTMLDocs -->|assemble| JekyllGen
    home_page -->|content| JekyllGen
    JekyllGen -->|produce| JekyllSite

    %% CI orchestrates
    BuildWF -->|triggers| Lake
    BuildWF -->|triggers| DocGen
    BuildWF -->|triggers| LBPrint
    LintWF -->|triggers| Lake
    UpdateWF -->|triggers| scripts

    %% Deployment
    JekyllSite -->|deploy| GitHubPages
    BuildWF -->|status| GitHub
    LintWF -->|status| GitHub
    UpdateWF -->|status| GitHub

    %% Click Events
    click SeymourEntry "https://github.com/ivan-sergeyev/seymour/blob/main/Seymour.lean"
    click Basic "https://github.com/ivan-sergeyev/seymour/tree/main/Seymour/Basic"
    click Matrix "https://github.com/ivan-sergeyev/seymour/tree/main/Seymour/Matrix"
    click Matroid "https://github.com/ivan-sergeyev/seymour/tree/main/Seymour/Matroid"
    click EasyDir "https://github.com/ivan-sergeyev/seymour/blob/main/Seymour/EasyDirection.lean"
    click HardDir "https://github.com/ivan-sergeyev/seymour/blob/main/Seymour/HardDirection.lean"
    click blueprint_src "https://github.com/ivan-sergeyev/seymour/tree/main/blueprint/src"
    click blueprint_2 "https://github.com/ivan-sergeyev/seymour/tree/main/blueprint_2"
    click home_page "https://github.com/ivan-sergeyev/seymour/tree/main/home_page/"
    click scripts "https://github.com/ivan-sergeyev/seymour/tree/main/scripts/"
    click BuildWF "https://github.com/ivan-sergeyev/seymour/blob/main/.github/workflows/build-project.yml"
    click LintWF "https://github.com/ivan-sergeyev/seymour/blob/main/.github/workflows/lint.yml"
    click UpdateWF "https://github.com/ivan-sergeyev/seymour/blob/main/.github/workflows/update-dependencies.yml"

    %% Styles
    classDef code fill:#D6EAF8,stroke:#2980B9
    classDef build fill:#D5F5E3,stroke:#27AE60
    classDef docs fill:#FDEBD0,stroke:#D68910
    classDef ci fill:#F5B7B1,stroke:#C0392B
    classDef external fill:#E5E8E8,stroke:#95A5A6
```
