# kubernetes-sigs/prow architecture

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

- Interactive diagram: https://gitdiagram.com/kubernetes-sigs/prow
- Repository: https://github.com/kubernetes-sigs/prow

## Overview

##### Key Components
- Prow Components (Executables): There are many binaries such as admission, branchprotector, checkconfig, clonerefs, config-bootstrapper, crier, deck, hook, tide, and many others. Each of these plays a specific role:
- “deck” is the web UI.
- “crier” manages reporting and logging.
- “hook” handles GitHub (or code host) webhooks.
- “tide” manages merge and PR statuses.
- Other executables (e.g., branchprotector, external-plugins, sidecar) provide specialized functionality.
- Shared Libraries and APIs: The pkg directory is rich with shared code (APIs, client libraries, informers, plugins, and integration logic) used across these components.
- Configuration and Custom Resources: Notice the config/prow directories and CRDs (e.g., prowjob-crd) which indicate integrations with Kubernetes’ custom resources.
- External Integrations: The system interfaces with GitHub, Gerrit, Google Cloud Build, PubSub, and likely other external services for triggering jobs or reporting statuses.

##### Relationships and Interactions
- Kubernetes Cluster: Show a central Kubernetes cluster that orchestrates these components; many components use Kubernetes informers and CRDs, implying bidirectional interaction with the k8s API server.
- External APIs/Hooks: Represent external services (GitHub, Gerrit, Slack, PubSub) that communicate with “hook”, “crier”, “branchprotector”, and “plugins”. These integrations are critical to the overall automation processes.

##### Architectural Patterns & Design Principles
- Distributed, Microservice-like Design: The distinct binaries allow for independent scaling, deployment, and maintenance.
- Separation of Concerns: Each component has a dedicated responsibility. For example, the “deck” component handles the UI while “hook” deals with event processing.
- Shared Libraries for Consistency: The use of the extensive pkg folder ensures that low-level operations (like git commands, logging, configuration parsing, and API clients) remain standardized across services.
- Kubernetes Integration: The strong reliance on Kubernetes for deployment, monitoring, and resource configuration highlights the design’s cloud-native nature.

## Diagram (Mermaid)

```mermaid
graph TD 
    %% External Integrations
    subgraph "External Integrations"
        extG["GitHub"]:::external
        extGr["Gerrit"]:::external
    end

    %% Prow Components (Executables)
    subgraph "Prow Components (Executables)"
        deck["Deck (Web UI)"]:::executables
        crier["Crier (Reporter)"]:::executables
        hook["Hook (Event Handler)"]:::executables
        tide["Tide (Merge Manager)"]:::executables
        branchProtector["BranchProtector"]:::executables
        extPlugins["External Plugins"]:::executables
        sidecar["Sidecar"]:::executables
    end

    %% Shared Libraries and Configuration
    subgraph "Shared and Configuration"
        shared["Shared Libraries & APIs"]:::shared
        githubInt["GitHub Integration"]:::shared
        gerritInt["Gerrit Integration"]:::shared
        k8sClient["Kubernetes Client & Informers"]:::shared
        cicd["CI/CD Orchestration"]:::shared
        plugins["Plugin Framework"]:::shared
        configCRD["Configuration Files"]:::shared
        clusterCRD["CRDs (prowjob-crd)"]:::shared
    end

    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        k8s["Kubernetes API Server"]:::kubernetes
    end

    %% External Integrations to Prow Components
    extG -->|"webhook"| hook
    extGr -->|"webhook"| hook

    %% Internal Prow interactions
    hook -->|"triggers"| crier
    hook -->|"triggers"| tide
    branchProtector -->|"evaluates"| githubInt
    extPlugins -->|"uses"| plugins
    hook -->|"uses"| plugins

    %% Executables using Shared Libraries
    deck -->|"uses"| shared
    crier -->|"uses"| shared
    hook -->|"uses"| shared
    tide -->|"uses"| shared
    branchProtector -->|"uses"| shared
    extPlugins -->|"uses"| shared
    sidecar -->|"uses"| shared

    %% Executables reading Configuration
    deck -->|"reads"| configCRD
    crier -->|"reads"| configCRD
    hook -->|"reads"| configCRD
    tide -->|"reads"| configCRD
    branchProtector -->|"reads"| configCRD
    extPlugins -->|"reads"| configCRD
    sidecar -->|"reads"| configCRD

    %% Configuration and CRD Flow
    configCRD -->|"defines"| clusterCRD
    clusterCRD -->|"managed_by"| k8sClient

    %% Shared Libraries flow towards Kubernetes Client & Informers
    shared --> k8sClient
    githubInt --> k8sClient
    gerritInt --> k8sClient
    cicd --> k8sClient
    plugins --> k8sClient

    %% Kubernetes Client connects to Kubernetes API Server
    k8sClient --> k8s

    %% Additional integration flow from Tide to GitHub Integration
    tide -->|"updates_status"| githubInt

    %% Click Events
    click deck "https://github.com/kubernetes-sigs/prow/tree/main/cmd/deck"
    click crier "https://github.com/kubernetes-sigs/prow/tree/main/cmd/crier"
    click hook "https://github.com/kubernetes-sigs/prow/tree/main/cmd/hook"
    click tide "https://github.com/kubernetes-sigs/prow/tree/main/cmd/tide"
    click branchProtector "https://github.com/kubernetes-sigs/prow/tree/main/cmd/branchprotector"
    click extPlugins "https://github.com/kubernetes-sigs/prow/tree/main/cmd/external-plugins"
    click sidecar "https://github.com/kubernetes-sigs/prow/tree/main/cmd/sidecar"
    click shared "https://github.com/kubernetes-sigs/prow/tree/main/pkg"
    click githubInt "https://github.com/kubernetes-sigs/prow/tree/main/pkg/github"
    click gerritInt "https://github.com/kubernetes-sigs/prow/tree/main/pkg/gerrit"
    click k8sClient "https://github.com/kubernetes-sigs/prow/tree/main/pkg/client/informers"
    click cicd "https://github.com/kubernetes-sigs/prow/tree/main/pkg/cron"
    click plugins "https://github.com/kubernetes-sigs/prow/tree/main/pkg/plugins"
    click configCRD "https://github.com/kubernetes-sigs/prow/tree/main/config/prow"
    click clusterCRD "https://github.com/kubernetes-sigs/prow/tree/main/config/prow/cluster"
    click k8s "https://github.com/kubernetes-sigs/prow/tree/main/config/prow/cluster"

    %% Styles
    classDef executables fill:#cfe2f3,stroke:#2e6da4,stroke-width:2px;
    classDef shared fill:#dff0d8,stroke:#3c763d,stroke-width:2px;
    classDef external fill:#f2dede,stroke:#a94442,stroke-width:2px;
    classDef kubernetes fill:#fcf8e3,stroke:#8a6d3b,stroke-width:2px;
```
