# ethereum/eips architecture

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

- Interactive diagram: https://gitdiagram.com/ethereum/eips
- Repository: https://github.com/ethereum/eips

## Overview

##### Project type and purpose
- This is a static documentation website built with Jekyll. Its sole purpose is to host, validate, and serve the collection of Ethereum Improvement Proposals (EIPs) as static HTML pages on GitHub Pages. Contributors propose and update EIPs as Markdown files; automated bots and validators enforce format and style; Jekyll transforms source files into the published site.

##### File structure
- Top-level directories:
- EIPS/ – all proposal Markdown files, organized by number.
- _includes/, _layouts/ – Jekyll template fragments and page layouts.
- assets/ – CSS, JSON test vectors, reference implementations, and other per-EIP assets.
- _data/, _config.yml, config/ – site configuration, metadata, linter/CI settings.
- .github/workflows/ – CI/CD definitions (PR validation, auto-merge bots, site build).
- Key config files: Gemfile/Gemfile.lock (Ruby deps), config files for eipw, HTMLProofer, codespell, markdownlint.

##### README for additional insights
- Build commands (`bundle exec jekyll serve`), local validator (`eipw`), CI bots (eip-review-bot), formatting checks (HTMLProofer, markdownlint, codespell).
- Deployment: whenever changes merge, GitHub Pages picks up the generated `_site` folder and publishes it at https://eips.ethereum.org/.

##### Main components
a. Content Store
– EIPS Markdown files
– YAML data (statuses.yaml)
– assets (CSS, JSON, PDFs, test vectors)
b. Static Site Generator
– Jekyll engine (Ruby) loading `_config.yml`, templates, includes, layouts
– Liquid rendering to HTML
c. CI Validation & Automation
– GitHub Actions workflows:
- PR linting/format checks (markdownlint, HTMLProofer, codespell)
- EIP rules enforcement (eipw)
- Auto-merge/eip-review-bot
– Renovate bot (dependency updates)
d. Deployment Platform
– GitHub Pages hosting the generated `_site`
e. External Services & Stakeholders
– Contributors (via GitHub PRs)
– Ethereum Magicians / Research links (for discussions)
– GitHub (source repo, Actions, Pages)
– Browsers (end users consuming the static site)

##### Relationships & data-flow
1. Contributor pushes/opens PR → GitHub triggers Actions.
2. CI checks run: eipw, markdownlint, codespell, HTMLProofer → report pass/fail.
3. auto-review-bot labels or auto-merges approved PRs.
4. On merge to main, GitHub Pages build (or prebuilt by CI) publishes HTML.
5. End user’s browser fetches HTML/CSS assets from GitHub Pages.

##### Architectural patterns & design principles
- Pipeline pattern: source → validation → build → deploy.
- Template/Content separation: content in Markdown + data in YAML; presentation in Liquid templates.
- Event-driven CI: pull_request and push events trigger validation and deployment.
- Infrastructure-as-code: workflows and config under version control.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph Contributors
        Contributor["Contributor"]:::external
    end

    subgraph "GitHub Repository"
        Repo["GitHub Repo"]:::external

        subgraph "Content Store"
            EIPFiles["EIP Markdown Files"]:::content
            StatusData["_data/statuses.yaml"]:::content
            Assets["Per-EIP Assets"]:::content
        end

        subgraph "Static Site Generator"
            Jekyll["Jekyll Engine"]:::processing
            ConfigYml["_config.yml"]:::processing
            Layouts["_layouts/"]:::processing
            Includes["_includes/"]:::processing
            RubyDeps["Gemfile & Gemfile.lock"]:::processing
            EipwCfg["config/eipw.toml"]:::processing
            MarkdownLint["config/.markdownlint.yaml"]:::processing
            Codespell["config/.codespell-whitelist"]:::processing
        end

        subgraph "CI Validation & Automation"
            Actions["GitHub Actions Workflows"]:::automation
            Renovate["Renovate Bot Config"]:::automation
            ReviewBot["Auto-Review Bots"]:::automation
        end
    end

    subgraph "Deployment Platform"
        Pages["GitHub Pages (CNAME)"]:::hosting
    end

    subgraph "End Users"
        Browser["Browser"]:::external
    end

    Contributor -->|pull_request / push| Repo
    Repo --> EIPFiles
    Repo --> StatusData
    Repo --> Assets
    Repo -->|trigger pull_request| Actions
    Renovate -->|dependency PRs| Repo
    Actions -->|label / merge approved| ReviewBot
    ReviewBot -->|auto-merge| Repo
    Repo -->|merge to main| Jekyll
    Jekyll -->|reads templates & content| ConfigYml
    Jekyll -->|reads templates & content| Layouts
    Jekyll -->|reads templates & content| Includes
    Jekyll -->|reads templates & content| RubyDeps
    Jekyll -->|applies rules| EipwCfg
    Jekyll -->|applies rules| MarkdownLint
    Jekyll -->|applies rules| Codespell
    Jekyll -->|processes content| EIPFiles
    Jekyll -->|processes data| StatusData
    Jekyll -->|processes assets| Assets
    Jekyll -->|builds _site| Pages
    Pages -->|serves site| Browser

    click EIPFiles "https://github.com/ethereum/eips/tree/master/EIPS/"
    click StatusData "https://github.com/ethereum/eips/blob/master/_data/statuses.yaml"
    click Assets "https://github.com/ethereum/eips/tree/master/assets/"
    click ConfigYml "https://github.com/ethereum/eips/blob/master/_config.yml"
    click Layouts "https://github.com/ethereum/eips/tree/master/_layouts/"
    click Includes "https://github.com/ethereum/eips/tree/master/_includes/"
    click RubyDeps "https://github.com/ethereum/eips/blob/master/Gemfile & Gemfile.lock"
    click EipwCfg "https://github.com/ethereum/eips/blob/master/config/eipw.toml"
    click MarkdownLint "https://github.com/ethereum/eips/blob/master/config/.markdownlint.yaml"
    click Codespell "https://github.com/ethereum/eips/blob/master/config/.codespell-whitelist"
    click Actions "https://github.com/ethereum/eips/blob/master/.github/workflows/ci.yml"
    click Renovate "https://github.com/ethereum/eips/blob/master/.github/renovate.json"
    click Pages "https://github.com/ethereum/eips/tree/master/CNAME"

    classDef content fill:#aadaff,stroke:#333,stroke-width:1px
    classDef processing fill:#aaffaa,stroke:#333,stroke-width:1px
    classDef automation fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef hosting fill:#e0b0ff,stroke:#333,stroke-width:1px
    classDef external fill:#dddddd,stroke:#333,stroke-width:1px
```
