# electron/rfcs architecture

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

- Interactive diagram: https://gitdiagram.com/electron/rfcs
- Repository: https://github.com/electron/rfcs

## Overview

##### Project type and purpose
- This is an **open-source process repository** (“electron/rfcs”) whose primary function is to collect, discuss, and version “Request for Comments” documents for the Electron project. It is not a runtime application but rather a **workflow/document-management tool** built on top of GitHub.

##### File structure
- Top-level files and folders:
- `.github/` – workflow definitions (`semantic.yml`) and CODEOWNERS (who must approve).
- `0000-template.md` – the base RFC template.
- `text/` – contains the actual RFC proposal Markdown files (0004-api-history-schema.md, etc.).
- `README.md` – describes the RFC process.
- `LICENSE.md` – license for the repository.
- The structure shows a **single-repo, GitHub-driven workflow** with:
- A template for new proposals
- A folder for active proposals (text/)
- CI checks via GitHub Actions for semantics, versioning, formatting, etc.

##### README for additional insights
- Defines the **stages of an RFC** (Proposed, Pending Comment, Active, Abandoned, Completed, Declined)
- Explains how to **fork, author, review, and merge** RFCs
- Describes human actors (contributors, API WG/maintainers) and automated checks

a. **Main components**
- **Community/Contributors**: fork & author RFCs
- **GitHub Platform**: hosting the repo, issues/PRs, Actions runner
- **RFC Repository**:
- `0000-template.md` (blueprint)
- `text/` folder (markdown RFCs)
- `images/` folder (assets)
- `.github/workflows/semantic.yml` (CI checks)
- `.github/CODEOWNERS` (review rules)
- **Maintainers / API Working Group**: review, label, merge, and manage status transitions
- **Electron/electron Repo**: target for implementation PRs once an RFC is Active
b. **Relationships & interactions**
1. Contributor forks repo → copies `0000-template.md` → creates `text/0000-*.md` → opens PR.
2. GitHub Actions (`semantic.yml`) runs semantic-versioning, formatting, or metadata checks.
3. CODEOWNERS file triggers automatic review requests to maintainers.
4. Maintainers review PR → change status label (Proposed → Pending Comment → Active, etc.) → merge or close.
5. Once “Active,” contributor or maintainer opens an implementation PR in `electron/electron`; upon merge, the RFC is marked “Completed.”
c. **Architectural patterns & design principles**
- **GitOps/CI-driven**: all process steps (lint, version check, labeling) automated through GitHub Actions.
- **Template-Based Extensibility**: new RFCs simply follow the filesystem convention in `text/`.
d. **Key technologies & frameworks**
- GitHub Actions (`.github/workflows/semantic.yml`)
- Markdown files in a conventional directory layout
- CODEOWNERS (GitHub feature) for mandatory reviewer assignment
- Standard Git/GitHub protocol (fork → PR → review → merge)

##### Elements
- **Clear labels** for each actor and component (e.g., “Contributor,” “GitHub Actions,” “Maintainers,” “RFC Repo”)

##### Detail is key
- Both **manual steps** (forking, review) and **automated steps** (CI checks)
- Don’t over-modularize: break the process into **every meaningful component** (template, CI, reviewers, repo, external implementation repo) to give maximum clarity
- Transitions—e.g., “2-week comment period” between Pending Comment → Active

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    subgraph "Actors"
        Contributor("Contributor"):::actor
        Maintainers("Maintainers / API WG"):::actor
    end

    %% External Repo
    ElectronRepo["Electron/electron Repo"]:::repo

    %% RFC Repository
    subgraph "RFC Repository"
        GitHubConfig[".github/"]:::service
        subgraph ".github"
            Workflow["semantic.yml"]:::service
            CodeOwners["CODEOWNERS"]:::service
        end
        Template["0000-template.md"]:::repo
        TextDir["text/"]:::repo
        Example0004["0004-api-history-schema.md"]:::repo
        Example0008["0008-preload-realm.md"]:::repo
        Example0012["0012-corner-smoothing.md"]:::repo
        Example0015["0015-hyphenation-data-api.md"]:::repo
        ImagesDir["images/"]:::repo
        README["README.md"]:::repo
        LICENSE["LICENSE.md"]:::repo
    end

    %% Lifecycle States
    subgraph "RFC Lifecycle States"
        Proposed["Proposed"]:::state
        Pending["Pending Comment"]:::state
        Active["Active"]:::state
        Completed["Completed"]:::state
        Declined["Declined"]:::state
        Abandoned["Abandoned"]:::state
    end

    %% Flow
    Contributor -->|"forks repo"| GitHubConfig
    Contributor -->|"copy template\ncreate RFC"| Template
    Template -->|creates| TextDir
    TextDir -->|add new RFC file| Example0004
    TextDir --> Example0008
    TextDir --> Example0012
    TextDir --> Example0015
    Example0004 -->|"open PR"| GitHubConfig
    GitHubConfig -->|triggers| Workflow
    GitHubConfig -->|triggers| CodeOwners
    Workflow -->|"CI status"| Maintainers
    CodeOwners -->|"request review"| Maintainers
    Maintainers -->|"review & label"| Proposed
    Proposed -->|"2-week comment period"| Pending
    Pending -->|"consensus"| Active
    Proposed -->|"no response"| Abandoned
    Proposed -->|"rejected"| Declined
    Pending -->|"rejected"| Declined
    Active -->|"implementation PR"| ElectronRepo
    ElectronRepo -->|"merge impl PR"| Completed
    Active -->|"rejected"| Declined

    %% Assets & Docs
    ImagesDir -->|assets| TextDir
    README -->|docs process| Proposed
    LICENSE -->|repo license| GitHubConfig

    %% Click Events
    click Workflow "https://github.com/electron/rfcs/blob/main/.github/workflows/semantic.yml"
    click CodeOwners "https://github.com/electron/rfcs/tree/main/.github/CODEOWNERS"
    click Template "https://github.com/electron/rfcs/blob/main/0000-template.md"
    click TextDir "https://github.com/electron/rfcs/tree/main/text/"
    click Example0004 "https://github.com/electron/rfcs/blob/main/text/0004-api-history-schema.md"
    click Example0008 "https://github.com/electron/rfcs/blob/main/text/0008-preload-realm.md"
    click Example0012 "https://github.com/electron/rfcs/blob/main/text/0012-corner-smoothing.md"
    click Example0015 "https://github.com/electron/rfcs/blob/main/text/0015-hyphenation-data-api.md"
    click ImagesDir "https://github.com/electron/rfcs/tree/main/images/"
    click README "https://github.com/electron/rfcs/blob/main/README.md"
    click LICENSE "https://github.com/electron/rfcs/blob/main/LICENSE.md"
    click GitHubConfig "https://github.com/electron/rfcs/tree/main/.github/"

    %% Styles
    classDef actor fill:#f9f,stroke:#333,stroke-width:1px
    classDef service fill:#cff,stroke:#333,stroke-width:1px
    classDef repo fill:#ccf,stroke:#333,stroke-width:1px
    classDef state fill:#fcf,stroke:#333,stroke-width:1px
```
