# ethereum/remix-ide architecture

> Architecture diagram of the GitHub repository ethereum/remix-ide, 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/remix-ide
- Repository: https://github.com/ethereum/remix-ide

## Overview

##### Project Type & Purpose
- Type: Static documentation site (Sphinx + Read-the-Docs).
- Purpose: Provide user/developer documentation for the Remix IDE platform, with internationalization (i18n) support, theme customization, and a plugin-centric docs structure.

##### File Structure
- Top level
- `.readthedocs.yaml` – RTD build configuration
- `README.md` – high-level instructions
- `docs/` – Sphinx documentation source
- Inside `docs/`
- `conf.py` – Sphinx config (extensions, theme, JS/CSS includes)
- `.rst` / `.md` content files – user-facing docs
- `_static/` – CSS & JS overrides for theming
- `_build/` – generated output (HTML, gettext catalogs)
- `locale/` – `.po`/.pot translation files
- `Makefile`/`make.bat` – build scripts
- `requirements.txt` – Python dependencies
- CI & Translation
- `crowdin.yml` – Crowdin sync configuration
- Locale directories under `docs/locale/…` for supported languages

##### Important README Insights
- Build steps use a Python venv with `sphinx`, `sphinx_rtd_theme`, `myst-parser`.
- Custom theming is applied via CSS (`fonts.css`, `tokens.css`, `custom.css`) and JS (`constants.js`, `utils.js`, `loaders.js`, `initialize.js`).
- Hosting is on Read-the-Docs with a badge & configuration; local testing via `python3 -m http.server`.
- Translators use Crowdin; do not edit `.po`/`.pot` locally.

##### Main Components
A. Developer Workstation
- Python Virtual Environment (venv)
- Git & GitHub repo clone
- Editor/IDE
B. Source Repository (GitHub)
- `docs/` directory (content + config + static + locale)
- CI config (`.readthedocs.yaml`, `crowdin.yml`)
C. Build Toolchain
- Sphinx Parser & Builder
- Extensions: myst-parser, sphinx_rtd_theme
- Makefile / `make html`
D. Static Asset Pipeline
- CSS & JS overrides in `_static/`
- Transpiled / copied by Sphinx into `_build/html/_static/`
E. Internationalization
- `.pot` extraction into `docs/_build/gettext/`
- `.po` files under `docs/locale/<lang>/LC_MESSAGES/`
- Crowdin synchronizes translations back into repo
F. Output Artifacts
- HTML files under `docs/_build/html/`
- Served locally via `http.server` or remotely on Read-the-Docs
G. External Services
- Read-the-Docs build servers
- Crowdin (translation management)
- Optional: GitHub Actions or other CI for PR checks

##### Relationships & Interactions
- Developer → GitHub: push/pull content & config
- GitHub → Read-the-Docs: pushes trigger RTD build via `.readthedocs.yaml`
- Sphinx Builder (local or RTD)
- Reads `docs/*` (content + `conf.py`)
- Applies CSS/JS from `_static/`
- Generates HTML & gettext catalogs
- Crowdin ↔ `docs/locale/*`:
- Crowdin pulls new `.pot` files
- Translators update `.po` on Crowdin
- Crowdin pushes new `.po` back into repo
- Final HTML → Web UI (remix-ide.readthedocs.io)

##### Important Architectural Patterns & Principles
- Static Site Generation (SSG) via Sphinx
- Separation of concerns:
- Content (`.md`/`.rst`) vs theming (`CSS`/`JS`) vs configuration (`conf.py`)
- I18n pipeline extracted & managed externally
- Plugin-centric docs: each doc module loosely maps to a Remix plugin or feature

- Arrowheads indicating data flow (push, pull, build output)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Environment
    subgraph "Developer Environment"
        direction TB
        DevGit["Git & GitHub Clone"]:::code
        DevIDE["Editor/IDE"]:::code
        DevVenv(["Python Virtual Environment"]):::process
    end

    %% Source Repository
    subgraph "Source Repository"
        direction TB
        RTDConfig[".readthedocs.yaml"]:::code
        click RTDConfig "https://github.com/ethereum/remix-ide/blob/master/.readthedocs.yaml"
        CrowdinConfig["crowdin.yml"]:::code
        click CrowdinConfig "https://github.com/ethereum/remix-ide/blob/master/crowdin.yml"
        Readme["README.md"]:::code
        click Readme "https://github.com/ethereum/remix-ide/blob/master/README.md"
        subgraph "docs/"
            direction TB
            Conf["conf.py"]:::code
            click Conf "https://github.com/ethereum/remix-ide/blob/master/docs/conf.py"
            Content[".rst / .md Files"]:::code
            click Content "https://github.com/ethereum/remix-ide/blob/master/docs/*.rst"
            click Content "https://github.com/ethereum/remix-ide/blob/master/docs/*.md"
            MakeUnix["Makefile"]:::code
            click MakeUnix "https://github.com/ethereum/remix-ide/tree/master/docs/Makefile"
            MakeWin["make.bat"]:::code
            click MakeWin "https://github.com/ethereum/remix-ide/blob/master/docs/make.bat"
            Req["requirements.txt"]:::code
            click Req "https://github.com/ethereum/remix-ide/blob/master/docs/requirements.txt"
        end
    end

    %% Static Asset Pipeline
    subgraph "Static Asset Pipeline"
        direction TB
        subgraph "_static/css"
            CSSCustom["custom.css"]:::asset
            click CSSCustom "https://github.com/ethereum/remix-ide/blob/master/docs/_static/css/custom.css"
            CSSFonts["fonts.css"]:::asset
            click CSSFonts "https://github.com/ethereum/remix-ide/blob/master/docs/_static/css/fonts.css"
            CSSTokens["tokens.css"]:::asset
            click CSSTokens "https://github.com/ethereum/remix-ide/blob/master/docs/_static/css/tokens.css"
        end
        subgraph "_static/js"
            JSConst["constants.js"]:::asset
            click JSConst "https://github.com/ethereum/remix-ide/blob/master/docs/_static/js/constants.js"
            JSInit["initialize.js"]:::asset
            click JSInit "https://github.com/ethereum/remix-ide/blob/master/docs/_static/js/initialize.js"
            JSLoad["loaders.js"]:::asset
            click JSLoad "https://github.com/ethereum/remix-ide/blob/master/docs/_static/js/loaders.js"
            JSUtils["utils.js"]:::asset
            click JSUtils "https://github.com/ethereum/remix-ide/blob/master/docs/_static/js/utils.js"
            JSCook["cookbook-integration.js"]:::asset
            click JSCook "https://github.com/ethereum/remix-ide/blob/master/docs/_static/js/cookbook-integration.js"
        end
        subgraph "_static/fonts"
            Fonts["Helvetica.ttc"]:::asset
            click Fonts "https://github.com/ethereum/remix-ide/blob/master/docs/_static/fonts/Helvetica.ttc"
        end
        AssetsImg["_static/img/"]:::asset
        click AssetsImg "https://github.com/ethereum/remix-ide/tree/master/docs/_static/img/"
    end

    %% Internationalization
    subgraph "Internationalization (docs/locale)"
        direction TB
        PotExtract["gettext *.pot"]:::process
        click PotExtract "https://github.com/ethereum/remix-ide/blob/master/docs/_build/gettext/*.pot"
        subgraph "Locales"
            ES["es/LC_MESSAGES/*.po"]:::code
            click ES "https://github.com/ethereum/remix-ide/blob/master/docs/locale/es/LC_MESSAGES/*.po"
            FR["fr/LC_MESSAGES/*.po"]:::code
            click FR "https://github.com/ethereum/remix-ide/blob/master/docs/locale/fr/LC_MESSAGES/*.po"
            IT["it/LC_MESSAGES/*.po"]:::code
            click IT "https://github.com/ethereum/remix-ide/blob/master/docs/locale/it/LC_MESSAGES/*.po"
            KR["ko_KR/LC_MESSAGES/*.po"]:::code
            click KR "https://github.com/ethereum/remix-ide/blob/master/docs/locale/ko_KR/LC_MESSAGES/*.po"
            RU["ru_RU/LC_MESSAGES/*.po"]:::code
            click RU "https://github.com/ethereum/remix-ide/blob/master/docs/locale/ru_RU/LC_MESSAGES/*.po"
            CN["zh_CN/LC_MESSAGES/*.po"]:::code
            click CN "https://github.com/ethereum/remix-ide/blob/master/docs/locale/zh_CN/LC_MESSAGES/*.po"
        end
    end

    %% Build & CI
    subgraph "Build & CI"
        direction TB
        SphinxBuilder(["Sphinx Parser & Builder"]):::process
        MakeHTML(["make html"]):::process
        I18nExtract(["Extract Translations"]):::process
        CIReadthedocs(("Read-the-Docs Build")):::external
        click CIReadthedocs "https://github.com/ethereum/remix-ide/blob/master/.readthedocs.yaml"
        CICrowdin(("Crowdin Sync")):::external
        click CICrowdin "https://github.com/ethereum/remix-ide/blob/master/crowdin.yml"
    end

    %% Hosting & Delivery
    subgraph "Hosting & Delivery"
        direction TB
        HTML["HTML Output (_build/html/)"]:::code
        WebUI(("remix-ide.readthedocs.io")):::external
        LocalServer(["python3 -m http.server"]):::process
    end

    %% Data Flows
    DevGit -->|push/pull| RTDConfig
    DevGit -->|push/pull| CrowdinConfig
    DevGit -->|push/pull| Readme
    DevGit -->|push/pull| Conf
    DevGit -->|edit| Content
    DevVenv -->|provides| SphinxBuilder

    RTDConfig --> CIReadthedocs
    CrowdinConfig --> CICrowdin

    CIReadthedocs --> SphinxBuilder
    CICrowdin --> ES
    CICrowdin --> FR
    CICrowdin --> IT
    CICrowdin --> KR
    CICrowdin --> RU
    CICrowdin --> CN

    SphinxBuilder -->|reads| Conf
    SphinxBuilder -->|reads| Content
    SphinxBuilder -->|applies| CSSCustom
    CSSCustom --> SphinxBuilder
    SphinxBuilder -->|applies| JSConst
    JSConst --> SphinxBuilder
    SphinxBuilder -->|reads assets| AssetsImg
    SphinxBuilder --> MakeHTML
    MakeHTML --> PotExtract
    PotExtract --> ES
    PotExtract --> FR
    SphinxBuilder --> HTML

    HTML --> WebUI
    HTML --> LocalServer

    %% Styles
    classDef code fill:#D0E7FF,stroke:#1696D2,stroke-width:1px
    classDef process fill:#DFFFD0,stroke:#5A9F00,stroke-width:1px
    classDef asset fill:#FFE8B0,stroke:#E08E00,stroke-width:1px
    classDef external fill:#E0E0E0,stroke-dasharray: 5 5,stroke:#888888,stroke-width:1px
    class DevGit,DevIDE,DevVenv code
    class SphinxBuilder,MakeHTML,I18nExtract process
    class AssetsImg asset
    class CIReadthedocs,CICrowdin,WebUI external
```
