# alexellis/derek architecture

> Architecture diagram of the GitHub repository alexellis/derek, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alexellis/derek
- Repository: https://github.com/alexellis/derek

## Overview

Derek is a webhook-driven GitHub App that automates repository governance and delegates issue/PR actions. GitHub sends events to the runtime entry point, which parses and routes them, verifies customer/configuration eligibility where applicable, then invokes feature handlers that update GitHub. The graph preserves the documented DCO, PR-governance, issue-template, comment-command, Hacktoberfest, and release-note capabilities. Source excerpts were partial, so some capability wiring and internal calls are not shown beyond what the README or sampled code supports.

Main entry points: [`main.go`](https://github.com/alexellis/derek/blob/master/main.go) (Webhook entry and router), [`handler/permissions_handler.go`](https://github.com/alexellis/derek/blob/master/handler/permissions_handler.go) (Repository configuration), [`handler/pullrequest_handler.go`](https://github.com/alexellis/derek/blob/master/handler/pullrequest_handler.go) (PR and DCO checks), [`handler/hacktoberfest_handler.go`](https://github.com/alexellis/derek/blob/master/handler/hacktoberfest_handler.go) (Hacktoberfest checks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Webhook runtime"]
  node_runtime["Webhook entry and router<br/>[main.go]"]
  node_app_config["App configuration<br/>[config.go]"]
  node_event_types["Webhook data types<br/>[types.go]"]
end

subgraph group_access["Access and configuration"]
  node_customer_check["Customer validation<br/>[customers.go]"]
  node_repo_config["Repository configuration"]
  node_config_merge["Configuration merge<br/>[merge.go]"]
  node_installation_auth["Installation tokens<br/>[jwt_auth.go]"]
  node_client_factory["GitHub client<br/>[client_factory.go]"]
end

subgraph group_governance["Repository governance"]
  node_pr_governance["PR and DCO checks"]
  node_spam_checks["Hacktoberfest checks"]
  node_issue_templates["Issue template checks"]
end

subgraph group_commands["Delegated commands"]
  node_comment_commands["Comment command handler<br/>[comment_handler.go]"]
end

subgraph group_release["Release notes"]
  node_release_notes["Release changelog<br/>[release_handler.go]"]
end

node_github_actor(("GitHub activity"))
node_github_api(("GitHub API"))
node_remote_config(("GitHub-hosted config"))
node_customer_registry(("Customer registry"))

node_github_actor -->|"sends webhook"| node_runtime
node_runtime -->|"loads settings"| node_app_config
node_runtime -->|"parses payload"| node_event_types
node_runtime -->|"checks customer"| node_customer_check
node_customer_check -->|"reads registry"| node_customer_registry
node_runtime -->|"loads repo settings"| node_repo_config
node_repo_config -->|"fetches config"| node_remote_config
node_repo_config -->|"merges settings"| node_config_merge
node_repo_config -->|"downloads private config"| node_github_api
node_runtime -->|"dispatches PR"| node_pr_governance
node_runtime -->|"dispatches spam check"| node_spam_checks
node_runtime -->|"dispatches issue check"| node_issue_templates
node_runtime -->|"dispatches comment"| node_comment_commands
node_runtime -->|"dispatches release"| node_release_notes
node_pr_governance -->|"gets token"| node_installation_auth
node_spam_checks -->|"gets token"| node_installation_auth
node_comment_commands -->|"gets token"| node_installation_auth
node_installation_auth -->|"requests token"| node_github_api
node_pr_governance -->|"creates client"| node_client_factory
node_spam_checks -->|"creates client"| node_client_factory
node_comment_commands -->|"creates client"| node_client_factory
node_issue_templates -->|"labels and comments"| node_github_api
node_pr_governance -->|"checks and updates PR"| node_github_api
node_spam_checks -->|"checks and updates PR"| node_github_api
node_comment_commands -->|"applies commands"| node_github_api
node_release_notes -->|"reads and updates release"| node_github_api
node_release_notes -->|"creates client"| node_client_factory

click node_runtime "https://github.com/alexellis/derek/blob/master/main.go"
click node_app_config "https://github.com/alexellis/derek/blob/master/config/config.go"
click node_event_types "https://github.com/alexellis/derek/blob/master/types/types.go"
click node_customer_check "https://github.com/alexellis/derek/blob/master/auth/customers.go"
click node_repo_config "https://github.com/alexellis/derek/blob/master/handler/permissions_handler.go"
click node_config_merge "https://github.com/alexellis/derek/blob/master/types/merge.go"
click node_installation_auth "https://github.com/alexellis/derek/blob/master/auth/jwt_auth.go"
click node_client_factory "https://github.com/alexellis/derek/blob/master/factory/client_factory.go"
click node_pr_governance "https://github.com/alexellis/derek/blob/master/handler/pullrequest_handler.go"
click node_spam_checks "https://github.com/alexellis/derek/blob/master/handler/hacktoberfest_handler.go"
click node_issue_templates "https://github.com/alexellis/derek/blob/master/handler/template_handler.go"
click node_comment_commands "https://github.com/alexellis/derek/blob/master/handler/comment_handler.go"
click node_release_notes "https://github.com/alexellis/derek/blob/master/handler/release_handler.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runtime,node_app_config,node_event_types toneBlue
class node_customer_check,node_repo_config,node_config_merge,node_installation_auth,node_client_factory toneAmber
class node_pr_governance,node_spam_checks,node_issue_templates,node_github_api toneMint
class node_comment_commands toneRose
class node_release_notes,node_github_actor,node_remote_config,node_customer_registry toneIndigo
```

## Components

### Webhook runtime

- [Webhook entry and router](https://github.com/alexellis/derek/blob/master/main.go): `main.go`
- [App configuration](https://github.com/alexellis/derek/blob/master/config/config.go): `config/config.go`
- [Webhook data types](https://github.com/alexellis/derek/blob/master/types/types.go): `types/types.go`

### Access and configuration

- [Customer validation](https://github.com/alexellis/derek/blob/master/auth/customers.go): `auth/customers.go`
- [Repository configuration](https://github.com/alexellis/derek/blob/master/handler/permissions_handler.go): `handler/permissions_handler.go`
- [Configuration merge](https://github.com/alexellis/derek/blob/master/types/merge.go): `types/merge.go`
- [Installation tokens](https://github.com/alexellis/derek/blob/master/auth/jwt_auth.go): `auth/jwt_auth.go`
- [GitHub client](https://github.com/alexellis/derek/blob/master/factory/client_factory.go): `factory/client_factory.go`

### Repository governance

- [PR and DCO checks](https://github.com/alexellis/derek/blob/master/handler/pullrequest_handler.go): `handler/pullrequest_handler.go`
- [Hacktoberfest checks](https://github.com/alexellis/derek/blob/master/handler/hacktoberfest_handler.go): `handler/hacktoberfest_handler.go`
- [Issue template checks](https://github.com/alexellis/derek/blob/master/handler/template_handler.go): `handler/template_handler.go`

### Delegated commands

- [Comment command handler](https://github.com/alexellis/derek/blob/master/handler/comment_handler.go): `handler/comment_handler.go`

### Release notes

- [Release changelog](https://github.com/alexellis/derek/blob/master/handler/release_handler.go): `handler/release_handler.go`

### Other components

- **GitHub activity**
- **GitHub API**
- **GitHub-hosted config**
- **Customer registry**

## Connections

- GitHub activity → Webhook entry and router: sends webhook
- Webhook entry and router → App configuration: loads settings
- Webhook entry and router → Webhook data types: parses payload
- Webhook entry and router → Customer validation: checks customer
- Customer validation → Customer registry: reads registry
- Webhook entry and router → Repository configuration: loads repo settings
- Repository configuration → GitHub-hosted config: fetches config
- Repository configuration → Configuration merge: merges settings
- Repository configuration → GitHub API: downloads private config
- Webhook entry and router → PR and DCO checks: dispatches PR
- Webhook entry and router → Hacktoberfest checks: dispatches spam check
- Webhook entry and router → Issue template checks: dispatches issue check
- Webhook entry and router → Comment command handler: dispatches comment
- Webhook entry and router → Release changelog: dispatches release
- PR and DCO checks → Installation tokens: gets token
- Hacktoberfest checks → Installation tokens: gets token
- Comment command handler → Installation tokens: gets token
- Installation tokens → GitHub API: requests token
- PR and DCO checks → GitHub client: creates client
- Hacktoberfest checks → GitHub client: creates client
- Comment command handler → GitHub client: creates client
- Issue template checks → GitHub API: labels and comments
- PR and DCO checks → GitHub API: checks and updates PR
- Hacktoberfest checks → GitHub API: checks and updates PR
- Comment command handler → GitHub API: applies commands
- Release changelog → GitHub API: reads and updates release
- Release changelog → GitHub client: creates client