# tc39/ecma262 architecture

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

- Interactive diagram: https://gitdiagram.com/tc39/ecma262
- Repository: https://github.com/tc39/ecma262

## Overview

##### Project type and purpose
- This is neither a web-app front-end nor a microservice architecture, but a **documentation-site build pipeline** for the ECMAScript® language spec.
- The repo holds the **source** (Markdown, HTML, tables, proposals), **build scripts**, and **CI/CD workflows** that produce and publish the human-readable spec at https://tc39.es/ecma262/.

##### File structure
- Top-level “content” folders and files:
- `*.md` (stage0.md, withdrawn-proposals.md, biblio/README.md)
- `spec.html` and pre-rendered tables in root.
- `img/` holds static assets.
- Build logic in:
- `package.json` & `package-lock.json` (npm scripts, dependencies)
- `scripts/` (shell & JS helpers: auto-deploy, check-commit, publish-biblio, spellcheck)
- CI/CD in `.github/workflows/`:
- Linting/format enforcement (enforce-format.yml)
- Type checking (esmeta-typecheck.yml)
- Spellcheck (spellcheck.yml)
- Build & preview (build.yml, preview.yml, preview-build.yml)
- Publishing (deploy.yml, publish-biblio.yml)

##### README for additional insights
- The “Developing the Specification” section spells out the local build commands (`npm run build`, `npm run watch`) and output directory (`out/`).
- References external services: GitHub Actions, the TC39 process, and Searchfox for history.

- **Source Content**: Markdown, HTML, tables, proposals under root & `biblio/`.
- **Build Engine**: Node.js + npm + scripts in `scripts/`.
- **Output Artifact**: Generated spec site in `out/`.
- **CI/CD Orchestrator**: GitHub Actions workflows in `.github/workflows/`.
- **External Services**:
- GitHub (repo hosting, Actions runner)
- TC39 publishing endpoints (https://tc39.es/ecma262/)
- Searchfox (source history reference)
b. Relationships & interactions:
- Content → Build Engine (npm scripts invoke `scripts/*.js` & shell scripts) → Output Artifact.
- GitHub commit/PR → CI/CD workflows (lint, typecheck, build) → on success → deploy to TC39 site or publish biblio.
- Manual tug: contributors edit Markdown → PR → CI checks → merge → triggers deploy.
c. Architectural patterns & principles:
- **Static-site generator** pattern: content + build pipeline = final HTML.
- **CI-as-code**: every stage (format, type, spell, build, deploy) defined as GitHub Actions.
- **Modular scripts**: small, single-purpose scripts in `scripts/`.
d. Key technologies, frameworks, libraries:
- Node.js, npm
- GitHub Actions
- esmeta (typechecker)
- custom JS & shell utilities for biblio, snapshots, spellcheck

##### Final advice
- Be as **granular as makes sense**: surface each subcomponent (e.g. lint, typecheck, spellcheck workflows) without over-splitting.
- **full flow** from “author writes spec” through “published HTML onsite.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Content
    subgraph "Source Content" 
        SC1["stage0.md"] 
        SC2["withdrawn-proposals.md"]
        SC3["spec.html"]
        SC4["table-binary-unicode-properties-of-strings.html"]
        SC5["table-binary-unicode-properties.html"]
        SC6["table-nonbinary-unicode-properties.html"]
        SC7["biblio/README.md"]
        SC8["biblio/package.json"]
    end

    %% Build Engine
    subgraph "Build Engine"
        BE1["package.json"]
        BE2["package-lock.json"]
        BE3["scripts/auto-deploy.sh"]
        BE4["scripts/check-commit.js"]
        BE5["scripts/check-form.js"]
        BE6["scripts/insert_snapshot_warning.js"]
        BE7["scripts/publish-biblio.sh"]
        BE8["scripts/publish-preview.js"]
        BE9["scripts/snapshot_warning.css"]
        BE10["scripts/snapshot_warning.html"]
        BE11["scripts/spellcheck.mjs"]
    end

    %% Output Artifact
    subgraph "Output Artifact"
        OUT["out/"]
    end

    %% CI/CD Orchestrator
    subgraph "CI/CD Orchestrator"
        WF1[".github/workflows/enforce-format.yml"]
        WF2[".github/workflows/esmeta-typecheck.yml"]
        WF3[".github/workflows/spellcheck.yml"]
        WF4[".github/workflows/build.yml"]
        WF5[".github/workflows/preview.yml"]
        WF6[".github/workflows/preview-build.yml"]
        WF7[".github/workflows/deploy.yml"]
        WF8[".github/workflows/publish-biblio.yml"]
        WF9[".github/workflows/ipr.yml"]
        WF10[".github/workflows/require-allow-edits.yml"]
    end

    %% External Services
    subgraph "External Services"
        EXT1["GitHub (repo & Actions)"]
        EXT2["TC39 site (ecma262)"]
        EXT3["Searchfox"]
    end

    %% Developer
    DEV["Developer"]

    %% Local Developer Flow
    DEV -->|"npm install"| BE1
    DEV -->|"npm run build"| OUT
    DEV -->|"npm run watch"| OUT
    EXT3 -.->|history lookup| DEV

    %% Build Flow
    SC1 & SC2 & SC3 & SC4 & SC5 & SC6 & SC7 & SC8 -->|"content input"| BE1
    BE1 & BE2 & BE3 & BE4 & BE5 & BE6 & BE7 & BE8 & BE9 & BE10 & BE11 -->|"build pipeline"| OUT

    %% CI Flow
    EXT1 -->|"push/PR triggers"| WF1
    WF1 -->|"on success"| WF2
    WF2 -->|"on success"| WF3
    WF3 -->|"on success"| WF4
    WF4 -->|"calls npm run build"| BE1
    WF4 -->|"build output"| OUT
    WF4 -->|"on success"| WF7
    WF7 -->|"deploy artifact"| EXT2
    WF8 -->|"publish biblio"| EXT2

    %% Styles
    classDef source fill:#d0e1f9,stroke:#0a3d62
    classDef build fill:#d1f2a5,stroke:#196f3d
    classDef output fill:#aed6f1,stroke:#1b4f72
    classDef ci fill:#fadbd8,stroke:#641e16
    classDef external fill:#f2f3f4,stroke:#7b7d7d
    classDef dev fill:#f9e79f,stroke:#7d6608

    class SC1,SC2,SC3,SC4,SC5,SC6,SC7,SC8 source
    class BE1,BE2,BE3,BE4,BE5,BE6,BE7,BE8,BE9,BE10,BE11 build
    class OUT output
    class WF1,WF2,WF3,WF4,WF5,WF6,WF7,WF8,WF9,WF10 ci
    class EXT1,EXT2,EXT3 external
    class DEV dev

    %% Click Events
    click SC1 "https://github.com/tc39/ecma262/blob/main/stage0.md"
    click SC2 "https://github.com/tc39/ecma262/blob/main/withdrawn-proposals.md"
    click SC3 "https://github.com/tc39/ecma262/blob/main/spec.html"
    click SC4 "https://github.com/tc39/ecma262/blob/main/table-binary-unicode-properties-of-strings.html"
    click SC5 "https://github.com/tc39/ecma262/blob/main/table-binary-unicode-properties.html"
    click SC6 "https://github.com/tc39/ecma262/blob/main/table-nonbinary-unicode-properties.html"
    click SC7 "https://github.com/tc39/ecma262/blob/main/biblio/README.md"
    click SC8 "https://github.com/tc39/ecma262/blob/main/biblio/package.json"
    click BE1 "https://github.com/tc39/ecma262/blob/main/package.json"
    click BE2 "https://github.com/tc39/ecma262/blob/main/package-lock.json"
    click BE3 "https://github.com/tc39/ecma262/blob/main/scripts/auto-deploy.sh"
    click BE4 "https://github.com/tc39/ecma262/blob/main/scripts/check-commit.js"
    click BE5 "https://github.com/tc39/ecma262/blob/main/scripts/check-form.js"
    click BE6 "https://github.com/tc39/ecma262/blob/main/scripts/insert_snapshot_warning.js"
    click BE7 "https://github.com/tc39/ecma262/blob/main/scripts/publish-biblio.sh"
    click BE8 "https://github.com/tc39/ecma262/blob/main/scripts/publish-preview.js"
    click BE9 "https://github.com/tc39/ecma262/blob/main/scripts/snapshot_warning.css"
    click BE10 "https://github.com/tc39/ecma262/blob/main/scripts/snapshot_warning.html"
    click BE11 "https://github.com/tc39/ecma262/blob/main/scripts/spellcheck.mjs"
    click OUT "https://github.com/tc39/ecma262/tree/main/out/"
    click WF1 "https://github.com/tc39/ecma262/blob/main/.github/workflows/enforce-format.yml"
    click WF2 "https://github.com/tc39/ecma262/blob/main/.github/workflows/esmeta-typecheck.yml"
    click WF3 "https://github.com/tc39/ecma262/blob/main/.github/workflows/spellcheck.yml"
    click WF4 "https://github.com/tc39/ecma262/blob/main/.github/workflows/build.yml"
    click WF5 "https://github.com/tc39/ecma262/blob/main/.github/workflows/preview.yml"
    click WF6 "https://github.com/tc39/ecma262/blob/main/.github/workflows/preview-build.yml"
    click WF7 "https://github.com/tc39/ecma262/blob/main/.github/workflows/deploy.yml"
    click WF8 "https://github.com/tc39/ecma262/blob/main/.github/workflows/publish-biblio.yml"
    click WF9 "https://github.com/tc39/ecma262/blob/main/.github/workflows/ipr.yml"
    click WF10 "https://github.com/tc39/ecma262/blob/main/.github/workflows/require-allow-edits.yml"
```
