# electron/cation architecture

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

## Overview

##### Project Type and Purpose
- This is a Node.js/TypeScript GitHub App (bot) that listens to GitHub events (pull requests and issue comments) and enforces four PR‐governance rules:
- Semantic version labeling
- Minimum PR open time enforcement
- API review state management
- Deprecation‐review checklist enforcement
- It runs as a GitHub App (see app.json) and is tested with Vitest in the `spec/` folder.

##### High‐Level File Structure and Architectural Patterns
- `src/` – entry point (`index.ts`) plus four rule modules (`24-hour-rule.ts`, `add-triage-labels.ts`, `api-review-state.ts`, `deprecation-review-state.ts`, `enforce-semver-labels.ts`) and shared utility code (`utils/`, `constants.ts`, `enums.ts`).
- `spec/` – unit tests and fixtures for each rule module.
- `.github/workflows/` – CI pipelines for linting and testing.
- `app.json` – GitHub App manifest.
- No database: all state is managed via GitHub labels, checks, and comments.

##### Main Components and Their Interactions
a. GitHub (External Service)
- Generates webhook events: `pull_request.opened`, `pull_request.edited`, `pull_request_review`, `issue_comment`, etc.
- Provides REST/Checks API to read/write labels, comments, and check‐run statuses.
b. GitHub App Server (Node.js/TypeScript)
- index.ts initializes the Probot (or similar) framework and registers event handlers.
- Dispatcher module routes each incoming event to one or more rule‐enforcement modules.
c. Rule Modules (in `src/`)
- Semver enforcement (`enforce-semver-labels.ts`) – adds pending Check, ensures a semver label is present.
- PR open‐time (`24-hour-rule.ts`) – enforces minimum open time based on label.
- API review (`api-review-state.ts`) – adds and updates `api-review` labels/checks based on reviews or skip labels.
- Deprecation review (`deprecation-review-state.ts`) – posts a checklist comment, watches off‐checkboxes.
- Triage labels (`add-triage-labels.ts`) – initial “needs triage” labeling on new PRs.
d. Shared Utilities (`src/utils/`)
- GitHub API wrapper (`env-util.ts`, `label-utils.ts`, `log-util.ts`, `check-utils.ts`).
- Constants and enums define label names, time thresholds, check names.

##### Architectural Patterns and Principles
- Event‐Driven: each GitHub webhook triggers a cascade of handlers.
- Single‐Responsibility: one module per rule, orchestrated by a central dispatcher.
- Shared Utilities: avoid duplication of GitHub API calls, label/name constants.
- Stateless: no external DB—state lives in GitHub (labels, comments, checks).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Ingress"
        GitHub(("GitHub")):::external
        Receiver["Webhook Receiver / Probot\n(src/index.ts)"]:::app
        Dispatcher["Dispatcher\n(src/index.ts)"]:::app
    end

    subgraph "Business Logic"
        Semver["Semver Enforcement\n(src/enforce-semver-labels.ts)"]:::rule
        Rule24["24h PR Open-Time\n(src/24-hour-rule.ts)"]:::rule
        APIReview["API Review State\n(src/api-review-state.ts)"]:::rule
        DepRec["Deprecation Review\n(src/deprecation-review-state.ts)"]:::rule
        Triage["Triage Labels\n(src/add-triage-labels.ts)"]:::rule
    end

    subgraph "Utilities & Config"
        CheckUtils["Check Utils\n(src/utils/check-utils.ts)"]:::util
        EnvUtil["Env Util\n(src/utils/env-util.ts)"]:::util
        LabelUtils["Label Utils\n(src/utils/label-utils.ts)"]:::util
        LogUtil["Log Util\n(src/utils/log-util.ts)"]:::util
        Constants["Constants\n(src/constants.ts)"]:::util
        Enums["Enums\n(src/enums.ts)"]:::util
        Manifest["App Manifest\n(app.json)"]:::app
    end

    subgraph "External API"
        GitAPI(("GitHub REST & Checks API")):::external
    end

    subgraph "CI/CD"
        Lint["Lint Workflow\n(.github/workflows/lint.yml)"]:::ci
        TestWF["Test Workflow\n(.github/workflows/test.yml)"]:::ci
    end

    subgraph "Testing"
        Tests["Unit Tests\n(spec/*.spec.ts)"]:::test
        Fixtures["Fixtures\n(spec/fixtures/)"]:::test
    end

    GitHub -->|"webhook events\npull_request.opened, etc"| Receiver
    Receiver -->|"initialize & register handlers"| Dispatcher
    Dispatcher -->|"route events"| Semver
    Dispatcher --> Rule24
    Dispatcher --> APIReview
    Dispatcher --> DepRec
    Dispatcher --> Triage

    Semver -->|"uses utils"| CheckUtils
    Rule24 --> LabelUtils
    APIReview --> LabelUtils
    APIReview --> CheckUtils
    DepRec --> LabelUtils
    DepRec --> LogUtil
    Triage --> LabelUtils

    CheckUtils -->|"REST/Checks API calls"| GitAPI
    EnvUtil --> GitAPI
    LabelUtils --> GitAPI
    LogUtil --> GitAPI
    Constants --> Semver
    Enums --> Dispatcher

    Repo["Repository"]:::app
    Repo --> Lint
    Repo --> TestWF
    Lint -->|"runs on push/PR"| Repo
    TestWF --> Repo

    Tests --> Semver
    Tests --> Rule24
    Tests --> APIReview
    Tests --> DepRec
    Tests --> Triage
    Fixtures --> Tests

    classDef external fill:#D0E6F6,stroke:#000,stroke-width:1px
    classDef app fill:#E0E0E0,stroke:#000,stroke-width:1px
    classDef rule fill:#C6E2C6,stroke:#000,stroke-width:1px
    classDef util fill:#F9E79F,stroke:#000,stroke-width:1px
    classDef ci fill:#FAD7A0,stroke-dasharray:5 5
    classDef test fill:#E8DAEF,stroke:#000,stroke-width:1px

    click Receiver "https://github.com/electron/cation/blob/main/src/index.ts"
    click Dispatcher "https://github.com/electron/cation/blob/main/src/index.ts"
    click Semver "https://github.com/electron/cation/blob/main/src/enforce-semver-labels.ts"
    click Rule24 "https://github.com/electron/cation/blob/main/src/24-hour-rule.ts"
    click APIReview "https://github.com/electron/cation/blob/main/src/api-review-state.ts"
    click DepRec "https://github.com/electron/cation/blob/main/src/deprecation-review-state.ts"
    click Triage "https://github.com/electron/cation/blob/main/src/add-triage-labels.ts"
    click CheckUtils "https://github.com/electron/cation/blob/main/src/utils/check-utils.ts"
    click EnvUtil "https://github.com/electron/cation/blob/main/src/utils/env-util.ts"
    click LabelUtils "https://github.com/electron/cation/blob/main/src/utils/label-utils.ts"
    click LogUtil "https://github.com/electron/cation/blob/main/src/utils/log-util.ts"
    click Constants "https://github.com/electron/cation/blob/main/src/constants.ts"
    click Enums "https://github.com/electron/cation/blob/main/src/enums.ts"
    click Manifest "https://github.com/electron/cation/blob/main/app.json"
    click Lint "https://github.com/electron/cation/blob/main/.github/workflows/lint.yml"
    click TestWF "https://github.com/electron/cation/blob/main/.github/workflows/test.yml"
    click Tests "https://github.com/electron/cation/blob/main/spec/*.spec.ts"
    click Fixtures "https://github.com/electron/cation/tree/main/spec/fixtures/"
```
