# ethereum/solc-bin architecture

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

## Overview

##### Project Type & Purpose
- This is an open-source “static asset management” tool, hosting current and historical builds of the Solidity compiler for multiple platforms (Emscripten-ASM.js, Emscripten-WASM, Linux, macOS, Windows, pure WASM).
- README makes clear it’s a repository of static binaries, mirrored to GitHub Pages and an S3 bucket (binaries.soliditylang.org), with automated workflows to fetch, generate indexes, and publish.

##### Key Architectural Components
A. Source Repository (GitHub)
- Stores:
– Platform directories (e.g. linux-amd64/, macosx-amd64/, emscripten-asmjs/, wasm/…) containing versioned binaries and list.{js,json,txt}
– “bin/” folder mirroring latest soljson.js builds
– CI config (.circleci/, .github/workflows/)
– Publishing scripts (add-nightly-and-push.sh, sync-s3.sh, update.mjs)
– Jekyll config (_config.yml) for GitHub Pages
- Exposes code and static assets via GitHub Pages (ethereum.github.io/solc-bin)

B. Continuous Integration / Automation
- CircleCI & GitHub Actions workflows:
– nightly-emscripten.yml: builds nightly Emscripten versions
– random-macosx-build.yml: periodically builds random macOS versions
– s3-mirror.yml: syncs content to S3 bucket
– t-bytecode-compare.yml: binary smoke tests/comparison
- Scripts invoked by CI:
– update.mjs: regenerates list.json/js/txt indexes per directory
– sync-s3.sh: pushes folder structure to AWS S3 (binaries.soliditylang.org)
– add-nightly-and-push.sh: adds new nightly build to “bin/” and commits

C. Package & Build Tooling
- package.json: Node.js dependencies for update.mjs & related scripts
- soljson.js: entry point for latest compiler distribution in top-level

D. Static Hosting / Distribution
- GitHub Pages: serves static directory structure & list files
- AWS S3 + CloudFront (binaries.soliditylang.org): primary HTTPS distribution mirror

##### Relationships & Data Flows
1. Developer or upstream Solidity release triggers CI workflows in GitHub Actions or CircleCI.
2. CI jobs fetch or build compiler binaries for each platform.
3. Binaries get checked into respective platform directories or into “bin/”, and update.mjs regenerates list.js/json/txt indexes.
4. CI commits updated index + binaries back to GitHub (or pushes a release tag).
5. sync-s3.sh workflow (triggered by push or schedule) uploads the complete tree to the AWS S3 bucket.
6. Jekyll (_config.yml) on GitHub Pages picks up directory tree to serve via HTTPS.
7. Client tools (npm-solc, Truffle, Hardhat, users) fetch compilers directly from GitHub Pages or binaries.soliditylang.org.

##### Architectural Patterns & Design Principles
- Static asset hosting (no dynamic back-end servers)
- “Infrastructure as code” for publishing pipelines
- Single repo, multi-platform directory layout with standard naming conventions per version
- Idempotent list generation (update.mjs) to ensure consistency of index files
- Separation of concerns:
- CI workflows handle build/test/publish
- Scripts handle indexing & synchronization
- GitHub Pages & S3 handle serving

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Repository
    subgraph "GitHub Repo" 
        direction TB
        Gitignore[".gitignore"]:::source
        License["LICENSE"]:::source
        Readme["README.md"]:::source
        JekyllConfig["_config.yml"]:::source
        SoljsonJs["soljson.js"]:::source
        PackageJson["package.json"]:::source
    end

    %% CI Engines
    subgraph "CI Pipelines"
        direction TB
        CircleCI["CircleCI"]:::ci
        GHActions["GitHub Actions"]:::ci
    end

    %% CI Configuration Files
    subgraph "CI Config Files"
        direction TB
        CIConfig[".circleci/config.yml"]:::source
        NightlyYaml[".github/workflows/nightly-emscripten.yml"]:::source
        RandomMacYaml[".github/workflows/random-macosx-build.yml"]:::source
        S3MirrorYaml[".github/workflows/s3-mirror.yml"]:::source
        TBytecodeYaml[".github/workflows/t-bytecode-compare.yml"]:::source
    end

    %% Scripts for Indexing & Sync
    subgraph "Scripts" 
        direction TB
        UpdateMjs["update.mjs"]:::scripts
        SyncS3["sync-s3.sh"]:::scripts
        AddNightly["add-nightly-and-push.sh"]:::scripts
    end

    %% Bin Directory
    subgraph "bin/" 
        direction TB
        BinListJs["list.js"]:::source
        BinListJson["list.json"]:::source
        BinListTxt["list.txt"]:::source
        LatestJs["soljson-latest.js"]:::source
        NightlyJs["soljson-nightly.js"]:::source
        VersionedJs["soljson-v*.js"]:::source
    end

    %% Platform Directories
    subgraph "Platform Directories"
        direction TB
        ASMjs["emscripten-asmjs/"]:::source
        Wasm32["emscripten-wasm32/"]:::source
        PureWasm["wasm/"]:::source
        Linux["linux-amd64/"]:::source
        Macos["macosx-amd64/"]:::source
        Windows["windows-amd64/"]:::source
    end

    %% Static Hosting
    subgraph "Static Hosting"
        direction TB
        GHPages["GitHub Pages"]:::hosting
        S3Bucket["AWS S3 + CloudFront"]:::hosting
    end

    %% Client
    Client["Client (npm-solc, Truffle, Hardhat)"]:::client

    %% Relationships
    Gitignore -->|source| CircleCI
    License -->|source| GHActions
    Readme -->|docs| GHPages

    CircleCI -->|uses config| CIConfig
    GHActions -->|uses configs| NightlyYaml & RandomMacYaml & S3MirrorYaml & TBytecodeYaml

    CircleCI -->|runs| UpdateMjs
    CircleCI -->|runs| SyncS3
    CircleCI -->|runs| AddNightly
    GHActions -->|runs| UpdateMjs
    GHActions -->|runs| SyncS3
    GHActions -->|runs| AddNightly

    UpdateMjs -->|updates indexes| BinListJs & BinListJson & BinListTxt & ASMjs & Wasm32 & PureWasm & Linux & Macos & Windows
    AddNightly -->|adds builds| LatestJs & NightlyJs & VersionedJs
    SyncS3 -->|sync to| S3Bucket

    %% Publishing
    Gitignore -->|commit binaries| ASMjs & Wasm32 & PureWasm & Linux & Macos & Windows & LatestJs & NightlyJs & VersionedJs
    Gitignore -.->|serves| GHPages

    %% Distribution to Client
    Client -->|fetches from| GHPages
    Client -->|fetches from| S3Bucket

    %% Click Events
    click Gitignore "https://github.com/ethereum/solc-bin/blob/gh-pages/.gitignore"
    click License "https://github.com/ethereum/solc-bin/tree/gh-pages/LICENSE"
    click Readme "https://github.com/ethereum/solc-bin/blob/gh-pages/README.md"
    click JekyllConfig "https://github.com/ethereum/solc-bin/blob/gh-pages/_config.yml"
    click SoljsonJs "https://github.com/ethereum/solc-bin/blob/gh-pages/soljson.js"
    click PackageJson "https://github.com/ethereum/solc-bin/blob/gh-pages/package.json"
    click CIConfig "https://github.com/ethereum/solc-bin/blob/gh-pages/.circleci/config.yml"
    click NightlyYaml "https://github.com/ethereum/solc-bin/blob/gh-pages/.github/workflows/nightly-emscripten.yml"
    click RandomMacYaml "https://github.com/ethereum/solc-bin/blob/gh-pages/.github/workflows/random-macosx-build.yml"
    click S3MirrorYaml "https://github.com/ethereum/solc-bin/blob/gh-pages/.github/workflows/s3-mirror.yml"
    click TBytecodeYaml "https://github.com/ethereum/solc-bin/blob/gh-pages/.github/workflows/t-bytecode-compare.yml"
    click UpdateMjs "https://github.com/ethereum/solc-bin/blob/gh-pages/update.mjs"
    click SyncS3 "https://github.com/ethereum/solc-bin/blob/gh-pages/sync-s3.sh"
    click AddNightly "https://github.com/ethereum/solc-bin/blob/gh-pages/add-nightly-and-push.sh"
    click BinListJs "https://github.com/ethereum/solc-bin/blob/gh-pages/bin/list.js"
    click BinListJson "https://github.com/ethereum/solc-bin/blob/gh-pages/bin/list.json"
    click BinListTxt "https://github.com/ethereum/solc-bin/blob/gh-pages/bin/list.txt"
    click LatestJs "https://github.com/ethereum/solc-bin/blob/gh-pages/bin/soljson-latest.js"
    click NightlyJs "https://github.com/ethereum/solc-bin/blob/gh-pages/bin/soljson-nightly.js"
    click VersionedJs "https://github.com/ethereum/solc-bin/blob/gh-pages/bin/soljson-v*.js"
    click ASMjs "https://github.com/ethereum/solc-bin/tree/gh-pages/emscripten-asmjs/"
    click Wasm32 "https://github.com/ethereum/solc-bin/tree/gh-pages/emscripten-wasm32/"
    click PureWasm "https://github.com/ethereum/solc-bin/tree/gh-pages/wasm/"
    click Linux "https://github.com/ethereum/solc-bin/tree/gh-pages/linux-amd64/"
    click Macos "https://github.com/ethereum/solc-bin/tree/gh-pages/macosx-amd64/"
    click Windows "https://github.com/ethereum/solc-bin/tree/gh-pages/windows-amd64/"

    %% Styles
    classDef source fill:#d0e7ff,stroke:#004b8d,color:#004b8d
    classDef ci fill:#d0ffd6,stroke:#0b6623,color:#0b6623
    classDef scripts fill:#e0e0ff,stroke:#4b0082,color:#4b0082
    classDef hosting fill:#ffe5b4,stroke:#cc8400,color:#cc8400
    classDef client fill:#f3d6ff,stroke:#800080,color:#800080
```
