# certbot/certbot architecture

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

- Interactive diagram: https://gitdiagram.com/certbot/certbot
- Repository: https://github.com/certbot/certbot

## Overview

Certbot is a command-line client that obtains and maintains HTTPS certificates through ACME. The main workflow configures a request, creates or reuses an account, proves domain control through an authenticator, obtains a certificate, stores its renewable lineage, and optionally configures the web server. Renewal and certificate-management commands reuse stored lineages; Apache, nginx, webroot, standalone, and DNS plugins provide distinct deployment or validation options. The graph follows README capabilities and indexed references; some plugin and renewal implementation details were not sampled, so uncertain connections are omitted or dashed.

Main entry points: [`certbot/src/certbot/_internal/main.py`](https://github.com/certbot/certbot/blob/main/certbot/src/certbot/_internal/main.py) (CLI commands), [`acme/src/acme/client.py`](https://github.com/certbot/certbot/blob/main/acme/src/acme/client.py) (ACME client), [`certbot/src/certbot/_internal/client.py`](https://github.com/certbot/certbot/blob/main/certbot/src/certbot/_internal/client.py) (Certificate client), [`certbot/src/certbot/_internal/plugins`](https://github.com/certbot/certbot/tree/main/certbot/src/certbot/_internal/plugins) (Authenticators)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command workflow"]
  node_main["CLI commands<br/>[main.py]"]
  node_config["Configuration<br/>[configuration.py]"]
end

subgraph group_acme["ACME protocol"]
  node_account["ACME account<br/>[account.py]"]
  node_acme_client["ACME client<br/>[client.py]"]
  node_acme_messages["Protocol messages<br/>[messages.py]"]
  node_challenges["Challenge types<br/>[challenges.py]"]
  node_auth_handler["Authorization handler<br/>[auth_handler.py]"]
end

subgraph group_plugins["Authenticators and installers"]
  node_auth_plugins["Authenticators"]
  node_apache["Apache plugin<br/>[configurator.py]"]
  node_nginx["nginx plugin<br/>[configurator.py]"]
  node_dns_plugins["DNS plugins<br/>[dns_cloudflare.py]"]
  node_installer["Web server installers"]
end

subgraph group_certs["Certificate lifecycle"]
  node_certificate_client["Certificate client<br/>[client.py]"]
  node_renewal["Renewal<br/>[renewal.py]"]
  node_cert_manager["Certificate management<br/>[cert_manager.py]"]
  node_storage[("Lineage storage<br/>[storage.py]")]
  node_crypto["Certificate crypto<br/>[crypto_util.py]"]
  node_reverter["Config rollback<br/>[reverter.py]"]
end

subgraph group_support["Shared runtime"]
  node_filesystem["Secure filesystem<br/>[filesystem.py]"]
end

node_user(("Operator"))
node_ca(("ACME certificate authority"))
node_webserver(("Web server"))

node_user -->|"runs commands"| node_main
node_main -->|"loads settings"| node_config
node_main -->|"uses account"| node_account
node_main -->|"initializes client"| node_certificate_client
node_main -->|"manages certificates"| node_cert_manager
node_main -.->|"runs renewal"| node_renewal
node_account -->|"uses protocol"| node_acme_client
node_account -->|"uses messages"| node_acme_messages
node_acme_client -->|"encodes messages"| node_acme_messages
node_acme_client -->|"uses challenges"| node_challenges
node_acme_client -->|"sends ACME requests"| node_ca
node_auth_handler -->|"polls authorizations"| node_acme_client
node_auth_handler -->|"dispatches challenges"| node_auth_plugins
node_auth_handler -->|"selects challenge types"| node_challenges
node_auth_plugins -.->|"includes"| node_apache
node_auth_plugins -.->|"includes"| node_nginx
node_auth_plugins -.->|"includes"| node_dns_plugins
node_certificate_client -.->|"handles authorization"| node_auth_handler
node_certificate_client -.->|"requests certificates"| node_acme_client
node_certificate_client -.->|"creates key material"| node_crypto
node_certificate_client -.->|"stores lineage"| node_storage
node_renewal -->|"reads lineage"| node_storage
node_cert_manager -->|"deletes lineage"| node_storage
node_main -.->|"selects configurator"| node_installer
node_installer -->|"configures server"| node_webserver
node_installer -.->|"records changes"| node_reverter
node_storage -->|"uses safe file operations"| node_filesystem
node_crypto -->|"uses safe file operations"| node_filesystem

click node_main "https://github.com/certbot/certbot/blob/main/certbot/src/certbot/_internal/main.py"
click node_config "https://github.com/certbot/certbot/blob/main/certbot/src/certbot/configuration.py"
click node_account "https://github.com/certbot/certbot/blob/main/certbot/src/certbot/_internal/account.py"
click node_acme_client "https://github.com/certbot/certbot/blob/main/acme/src/acme/client.py"
click node_acme_messages "https://github.com/certbot/certbot/blob/main/acme/src/acme/messages.py"
click node_challenges "https://github.com/certbot/certbot/blob/main/acme/src/acme/challenges.py"
click node_auth_handler "https://github.com/certbot/certbot/blob/main/certbot/src/certbot/_internal/auth_handler.py"
click node_auth_plugins "https://github.com/certbot/certbot/tree/main/certbot/src/certbot/_internal/plugins"
click node_apache "https://github.com/certbot/certbot/blob/main/certbot/src/certbot/_internal/plugins/apache/configurator.py"
click node_nginx "https://github.com/certbot/certbot/blob/main/certbot/src/certbot/_internal/plugins/nginx/configurator.py"
click node_dns_plugins "https://github.com/certbot/certbot/blob/main/certbot-dns-cloudflare/src/certbot_dns_cloudflare/_internal/dns_cloudflare.py"
click node_installer "https://github.com/certbot/certbot/tree/main/certbot/src/certbot/_internal/plugins"
click node_certificate_client "https://github.com/certbot/certbot/blob/main/certbot/src/certbot/_internal/client.py"
click node_renewal "https://github.com/certbot/certbot/blob/main/certbot/src/certbot/_internal/renewal.py"
click node_cert_manager "https://github.com/certbot/certbot/blob/main/certbot/src/certbot/_internal/cert_manager.py"
click node_storage "https://github.com/certbot/certbot/blob/main/certbot/src/certbot/_internal/storage.py"
click node_crypto "https://github.com/certbot/certbot/blob/main/certbot/src/certbot/crypto_util.py"
click node_reverter "https://github.com/certbot/certbot/blob/main/certbot/src/certbot/reverter.py"
click node_filesystem "https://github.com/certbot/certbot/blob/main/certbot/src/certbot/compat/filesystem.py"

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_main,node_config toneBlue
class node_account,node_acme_client,node_acme_messages,node_challenges,node_auth_handler toneAmber
class node_auth_plugins,node_apache,node_nginx,node_dns_plugins,node_installer,node_webserver toneMint
class node_certificate_client,node_renewal,node_cert_manager,node_storage,node_crypto,node_reverter toneRose
class node_filesystem,node_user,node_ca toneIndigo
```

## Components

### Command workflow

- [CLI commands](https://github.com/certbot/certbot/blob/main/certbot/src/certbot/_internal/main.py): `certbot/src/certbot/_internal/main.py`
- [Configuration](https://github.com/certbot/certbot/blob/main/certbot/src/certbot/configuration.py): `certbot/src/certbot/configuration.py`

### ACME protocol

- [ACME account](https://github.com/certbot/certbot/blob/main/certbot/src/certbot/_internal/account.py): `certbot/src/certbot/_internal/account.py`
- [ACME client](https://github.com/certbot/certbot/blob/main/acme/src/acme/client.py): `acme/src/acme/client.py`
- [Protocol messages](https://github.com/certbot/certbot/blob/main/acme/src/acme/messages.py): `acme/src/acme/messages.py`
- [Challenge types](https://github.com/certbot/certbot/blob/main/acme/src/acme/challenges.py): `acme/src/acme/challenges.py`
- [Authorization handler](https://github.com/certbot/certbot/blob/main/certbot/src/certbot/_internal/auth_handler.py): `certbot/src/certbot/_internal/auth_handler.py`

### Authenticators and installers

- [Authenticators](https://github.com/certbot/certbot/tree/main/certbot/src/certbot/_internal/plugins): `certbot/src/certbot/_internal/plugins`
- [Apache plugin](https://github.com/certbot/certbot/blob/main/certbot/src/certbot/_internal/plugins/apache/configurator.py): `certbot/src/certbot/_internal/plugins/apache/configurator.py`
- [nginx plugin](https://github.com/certbot/certbot/blob/main/certbot/src/certbot/_internal/plugins/nginx/configurator.py): `certbot/src/certbot/_internal/plugins/nginx/configurator.py`
- [DNS plugins](https://github.com/certbot/certbot/blob/main/certbot-dns-cloudflare/src/certbot_dns_cloudflare/_internal/dns_cloudflare.py): `certbot-dns-cloudflare/src/certbot_dns_cloudflare/_internal/dns_cloudflare.py`
- [Web server installers](https://github.com/certbot/certbot/tree/main/certbot/src/certbot/_internal/plugins): `certbot/src/certbot/_internal/plugins`

### Certificate lifecycle

- [Certificate client](https://github.com/certbot/certbot/blob/main/certbot/src/certbot/_internal/client.py): `certbot/src/certbot/_internal/client.py`
- [Renewal](https://github.com/certbot/certbot/blob/main/certbot/src/certbot/_internal/renewal.py): `certbot/src/certbot/_internal/renewal.py`
- [Certificate management](https://github.com/certbot/certbot/blob/main/certbot/src/certbot/_internal/cert_manager.py): `certbot/src/certbot/_internal/cert_manager.py`
- [Lineage storage](https://github.com/certbot/certbot/blob/main/certbot/src/certbot/_internal/storage.py): `certbot/src/certbot/_internal/storage.py`
- [Certificate crypto](https://github.com/certbot/certbot/blob/main/certbot/src/certbot/crypto_util.py): `certbot/src/certbot/crypto_util.py`
- [Config rollback](https://github.com/certbot/certbot/blob/main/certbot/src/certbot/reverter.py): `certbot/src/certbot/reverter.py`

### Shared runtime

- [Secure filesystem](https://github.com/certbot/certbot/blob/main/certbot/src/certbot/compat/filesystem.py): `certbot/src/certbot/compat/filesystem.py`

### Other components

- **Operator**
- **ACME certificate authority**
- **Web server**

## Connections

- Operator → CLI commands: runs commands (evidence: `README.rst`)
- CLI commands → Configuration: loads settings (evidence: `certbot/src/certbot/_internal/main.py`)
- CLI commands → ACME account: uses account (evidence: `certbot/src/certbot/_internal/main.py`)
- CLI commands → Certificate client: initializes client (evidence: `certbot/src/certbot/_internal/main.py`)
- CLI commands → Certificate management: manages certificates (evidence: `certbot/src/certbot/_internal/main.py`)
- CLI commands → Renewal: runs renewal (evidence: `certbot/src/certbot/_internal/main.py`)
- ACME account → ACME client: uses protocol (evidence: `certbot/src/certbot/_internal/account.py`)
- ACME account → Protocol messages: uses messages (evidence: `certbot/src/certbot/_internal/account.py`)
- ACME client → Protocol messages: encodes messages (evidence: `acme/src/acme/client.py`)
- ACME client → Challenge types: uses challenges (evidence: `acme/src/acme/client.py`)
- ACME client → ACME certificate authority: sends ACME requests (evidence: `README.rst`)
- Authorization handler → ACME client: polls authorizations (evidence: `certbot/src/certbot/_internal/auth_handler.py`)
- Authorization handler → Authenticators: dispatches challenges (evidence: `certbot/src/certbot/_internal/auth_handler.py`)
- Authorization handler → Challenge types: selects challenge types (evidence: `certbot/src/certbot/_internal/auth_handler.py`)
- Authenticators → Apache plugin: includes
- Authenticators → nginx plugin: includes
- Authenticators → DNS plugins: includes
- Certificate client → Authorization handler: handles authorization
- Certificate client → ACME client: requests certificates
- Certificate client → Certificate crypto: creates key material
- Certificate client → Lineage storage: stores lineage
- Renewal → Lineage storage: reads lineage (evidence: `certbot/src/certbot/_internal/storage.py`)
- Certificate management → Lineage storage: deletes lineage (evidence: `certbot/src/certbot/_internal/cert_manager.py`)
- CLI commands → Web server installers: selects configurator (evidence: `certbot/src/certbot/_internal/main.py`)
- Web server installers → Web server: configures server (evidence: `README.rst`)
- Web server installers → Config rollback: records changes
- Lineage storage → Secure filesystem: uses safe file operations (evidence: `certbot/src/certbot/_internal/storage.py`)
- Certificate crypto → Secure filesystem: uses safe file operations (evidence: `certbot/src/certbot/crypto_util.py`)
