# ethereum/beacon-apis architecture

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

## Overview

##### Project type and purpose
- This is an “open-source tool” repository that defines and publishes the Ethereum Beacon Chain REST API specification.
- It consists of OpenAPI/Swagger YAML files (under apis/ and types/), build-and-bundle scripts, static assets, and CI/CD workflows to produce a browsable documentation site.

##### File structure
- Top-level directories:
- apis/          – OpenAPI fragment files, organized by endpoint namespaces (beacon, builder, config, etc.).
- types/         – Reusable schema definitions for various protocol versions.
- dist/          – Bundled Swagger-UI assets and generated HTML/CSS/JS for the API browser.
- .github/       – CI/CD workflows: linting, spellcheck, test, build, pre-release, release, deploy.
- params/, README, beacon-node-oapi.yaml – entrypoint for the full API definition and render instructions.
- Key files:
- beacon-node-oapi.yaml – top-level OpenAPI definition that references all apis/ and types/ fragments.
- index.html            – landing page for the static API browser.
- .github/workflows/*.yaml – CI pipelines that run redocly lint, bundle, version tagging, and GitHub Pages deployment.

##### README for additional insights
- The repo produces a REST interface spec for beacon nodes; result is a static site served via any HTTP server.
- Uses Redocly CLI to lint and bundle.
- GitHub Actions automate testing, versioning, and publishing under stable or pre-release tags.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Spec Source
    subgraph "Spec Source" 
        direction TB
        Apis["apis/"]:::code
        Types["types/"]:::code
        Params["params/index.yaml"]:::code
        TopAPI["beacon-node-oapi.yaml"]:::code
    end

    %% Bundler/Linter
    subgraph "Bundler/Linter" 
        direction TB
        RedoclyCLI["Redocly CLI"]:::tool
        RedoclyConfig[".redocly.yml"]:::code
        LocalDevServer["Local HTTP Server"]:::runtime
    end

    %% CI/CD Workflows
    subgraph "CI/CD Workflows" 
        direction TB
        MainWF["main.yml"]:::tool
        SpellcheckWF["spellcheck.yml"]:::tool
        PreReleaseWF["pre-release.yaml"]:::tool
        ReleaseWF["release.yaml"]:::tool
        DeployWF["deploy.yaml"]:::tool
    end

    %% Static Site Output
    subgraph "Static Site Output"
        direction TB
        Dist["dist/"]:::code
        Index["index.html"]:::code
    end

    %% Hosting & Consumption
    subgraph "Hosting & Consumption"
        direction TB
        GitHubPages["GitHub Pages"]:::hosting
        CustomServer["Custom HTTP Server"]:::hosting
        Browser["End-user Browser"]:::consumer
    end

    %% Flows
    Apis -->|"source fragments"| RedoclyCLI
    Types -->|"schemas"| RedoclyCLI
    Params -->|"parameters"| RedoclyCLI
    TopAPI -->|"entrypoint spec"| RedoclyCLI

    RedoclyCLI -->|"bundles spec"| Dist
    RedoclyCLI -->|"uses config"| RedoclyConfig
    LocalDevServer -->|"serves dist/ for dev"| Index

    MainWF -->|"on push/PR"| RedoclyCLI
    SpellcheckWF -->|"spellcheck"| MainWF
    MainWF -->|"runs lint & bundle"| RedoclyCLI
    PreReleaseWF -->|"on tag pre-release"| ReleaseWF
    ReleaseWF -->|"publish artifacts"| DeployWF
    DeployWF -->|"deploy dist/ to"| GitHubPages

    Dist -->|"served by"| GitHubPages
    Dist -->|"served by"| CustomServer
    Index -->|"loaded by"| Browser

    %% Click Events
    click Apis "https://github.com/ethereum/beacon-apis/tree/master/apis/"
    click Types "https://github.com/ethereum/beacon-apis/tree/master/types/"
    click Params "https://github.com/ethereum/beacon-apis/blob/master/params/index.yaml"
    click TopAPI "https://github.com/ethereum/beacon-apis/blob/master/beacon-node-oapi.yaml"
    click RedoclyConfig "https://github.com/ethereum/beacon-apis/blob/master/.redocly.yml"
    click MainWF "https://github.com/ethereum/beacon-apis/blob/master/.github/workflows/main.yml"
    click SpellcheckWF "https://github.com/ethereum/beacon-apis/blob/master/.github/workflows/spellcheck.yml"
    click PreReleaseWF "https://github.com/ethereum/beacon-apis/blob/master/.github/workflows/pre-release.yaml"
    click ReleaseWF "https://github.com/ethereum/beacon-apis/blob/master/.github/workflows/release.yaml"
    click DeployWF "https://github.com/ethereum/beacon-apis/blob/master/.github/workflows/deploy.yaml"
    click Dist "https://github.com/ethereum/beacon-apis/tree/master/dist/"
    click Index "https://github.com/ethereum/beacon-apis/blob/master/index.html"

    %% Styles
    classDef code fill:#D0E8FF,stroke:#1C7ED6,color:#1C7ED6
    classDef tool fill:#E6F4EA,stroke:#2F9E44,color:#2F9E44
    classDef hosting fill:#FFF4DB,stroke:#F08C00,color:#F08C00
    classDef runtime fill:#F0EBFF,stroke:#7048E8,color:#7048E8
    classDef consumer fill:#F8F9FA,stroke:#495057,color:#495057
```
