# caddyserver/caddy architecture

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

- Interactive diagram: https://gitdiagram.com/caddyserver/caddy
- Repository: https://github.com/caddyserver/caddy

## Overview

Caddy is an extensible server platform whose principal workflow is to load JSON or adapt Caddyfile configuration, start configured apps, and serve HTTP(S) requests. Its major runtime capabilities include automatic certificate management, a modular HTTP handler stack, reverse proxying, static files, and an administrative API. The graph combines README-documented product behavior with relationships visible in sampled source; several runtime links are dashed where their implementation was not sampled.

Main entry points: [`modules/caddyhttp/routes.go`](https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/routes.go) (Routes and handlers), [`modules/caddyhttp/server.go`](https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/server.go) (HTTP server), [`modules/caddytls/automation.go`](https://github.com/caddyserver/caddy/blob/master/modules/caddytls/automation.go) (TLS automation), [`caddyconfig/load.go`](https://github.com/caddyserver/caddy/blob/master/caddyconfig/load.go) (Config loading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Configuration"]
  node_caddyfile["Caddyfile parser<br/>[parse.go]"]
  node_httpadapter["HTTP adapter<br/>[httptype.go]"]
  node_configloader["Config loading<br/>[load.go]"]
end

subgraph group_runtime["Server runtime"]
end

subgraph group_http["HTTP services"]
  node_http_app["HTTP app<br/>[app.go]"]
  node_http_server["HTTP server<br/>[server.go]"]
  node_routes["Routes and handlers<br/>[routes.go]"]
  node_reverse_proxy["Reverse proxy<br/>[reverseproxy.go]"]
  node_fastcgi["FastCGI client<br/>[client.go]"]
  node_file_server["Static files<br/>[staticfiles.go]"]
  node_templates["HTTP templates<br/>[tplcontext.go]"]
  node_http_push["HTTP/2 push<br/>[handler.go]"]
end

subgraph group_security["TLS and PKI"]
  node_tls["TLS automation<br/>[automation.go]"]
  node_pki["Local PKI<br/>[ca.go]"]
  node_acme["ACME server<br/>[acmeserver.go]"]
end

subgraph group_platform["Platform services"]
  node_cli["Caddy CLI<br/>[main.go]"]
  node_admin["Admin API<br/>[admin.go]"]
  node_module_registry["Module registry<br/>[modules.go]"]
  node_standard_modules["Standard modules<br/>[imports.go]"]
  node_storage[("Certificate storage<br/>[filestorage.go]")]
  node_logging["Logging<br/>[filewriter.go]"]
  node_metrics["Metrics<br/>[metrics.go]"]
end

node_operator(("Operator"))
node_config_json["Native JSON config"]
node_http_client(("HTTP clients"))
node_upstreams["Upstream services"]
node_certificate_issuers["Certificate issuers"]

node_operator -->|"runs"| node_cli
node_cli -->|"loads config"| node_configloader
node_cli -.->|"adapts config"| node_httpadapter
node_caddyfile -->|"parses directives"| node_httpadapter
node_httpadapter -->|"builds app config"| node_http_app
node_configloader -.->|"loads JSON"| node_config_json
node_configloader -.->|"configures runtime"| node_admin
node_standard_modules -->|"registers modules"| node_module_registry
node_http_app -.->|"starts servers"| node_http_server
node_http_server -.->|"dispatches requests"| node_routes
node_routes -.->|"routes to"| node_reverse_proxy
node_reverse_proxy -.->|"uses FastCGI"| node_fastcgi
node_reverse_proxy -.->|"forwards requests"| node_upstreams
node_routes -.->|"routes to"| node_file_server
node_routes -.->|"renders templates"| node_templates
node_routes -.->|"may push resources"| node_http_push
node_http_app -.->|"uses TLS"| node_tls
node_tls -.->|"obtains certificates"| node_certificate_issuers
node_tls -.->|"supports local CA"| node_pki
node_pki -.->|"serves ACME"| node_acme
node_tls -.->|"stores certificates"| node_storage
node_http_server -.->|"logs requests"| node_logging
node_http_server -.->|"exports metrics"| node_metrics

click node_cli "https://github.com/caddyserver/caddy/blob/master/cmd/main.go"
click node_caddyfile "https://github.com/caddyserver/caddy/blob/master/caddyconfig/caddyfile/parse.go"
click node_httpadapter "https://github.com/caddyserver/caddy/blob/master/caddyconfig/httpcaddyfile/httptype.go"
click node_configloader "https://github.com/caddyserver/caddy/blob/master/caddyconfig/load.go"
click node_admin "https://github.com/caddyserver/caddy/blob/master/admin.go"
click node_module_registry "https://github.com/caddyserver/caddy/blob/master/modules.go"
click node_standard_modules "https://github.com/caddyserver/caddy/blob/master/modules/standard/imports.go"
click node_http_app "https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/app.go"
click node_http_server "https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/server.go"
click node_routes "https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/routes.go"
click node_reverse_proxy "https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/reverseproxy/reverseproxy.go"
click node_fastcgi "https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/reverseproxy/fastcgi/client.go"
click node_file_server "https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/fileserver/staticfiles.go"
click node_templates "https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/templates/tplcontext.go"
click node_http_push "https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/push/handler.go"
click node_tls "https://github.com/caddyserver/caddy/blob/master/modules/caddytls/automation.go"
click node_pki "https://github.com/caddyserver/caddy/blob/master/modules/caddypki/ca.go"
click node_acme "https://github.com/caddyserver/caddy/blob/master/modules/caddypki/acmeserver/acmeserver.go"
click node_storage "https://github.com/caddyserver/caddy/blob/master/modules/filestorage/filestorage.go"
click node_logging "https://github.com/caddyserver/caddy/blob/master/modules/logging/filewriter.go"
click node_metrics "https://github.com/caddyserver/caddy/blob/master/modules/metrics/metrics.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_caddyfile,node_httpadapter,node_configloader,node_http_client toneBlue
class node_http_app,node_http_server,node_routes,node_reverse_proxy,node_fastcgi,node_file_server,node_templates,node_http_push toneMint
class node_tls,node_pki,node_acme toneRose
class node_cli,node_admin,node_module_registry,node_standard_modules,node_storage,node_logging,node_metrics,node_operator,node_config_json,node_upstreams,node_certificate_issuers toneIndigo
```

## Components

### Configuration

- [Caddyfile parser](https://github.com/caddyserver/caddy/blob/master/caddyconfig/caddyfile/parse.go): `caddyconfig/caddyfile/parse.go`
- [HTTP adapter](https://github.com/caddyserver/caddy/blob/master/caddyconfig/httpcaddyfile/httptype.go): `caddyconfig/httpcaddyfile/httptype.go`
- [Config loading](https://github.com/caddyserver/caddy/blob/master/caddyconfig/load.go): `caddyconfig/load.go`

### HTTP services

- [HTTP app](https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/app.go): `modules/caddyhttp/app.go`
- [HTTP server](https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/server.go): `modules/caddyhttp/server.go`
- [Routes and handlers](https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/routes.go): `modules/caddyhttp/routes.go`
- [Reverse proxy](https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/reverseproxy/reverseproxy.go): `modules/caddyhttp/reverseproxy/reverseproxy.go`
- [FastCGI client](https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/reverseproxy/fastcgi/client.go): `modules/caddyhttp/reverseproxy/fastcgi/client.go`
- [Static files](https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/fileserver/staticfiles.go): `modules/caddyhttp/fileserver/staticfiles.go`
- [HTTP templates](https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/templates/tplcontext.go): `modules/caddyhttp/templates/tplcontext.go`
- [HTTP/2 push](https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/push/handler.go): `modules/caddyhttp/push/handler.go`

### TLS and PKI

- [TLS automation](https://github.com/caddyserver/caddy/blob/master/modules/caddytls/automation.go): `modules/caddytls/automation.go`
- [Local PKI](https://github.com/caddyserver/caddy/blob/master/modules/caddypki/ca.go): `modules/caddypki/ca.go`
- [ACME server](https://github.com/caddyserver/caddy/blob/master/modules/caddypki/acmeserver/acmeserver.go): `modules/caddypki/acmeserver/acmeserver.go`

### Platform services

- [Caddy CLI](https://github.com/caddyserver/caddy/blob/master/cmd/main.go): `cmd/main.go`
- [Admin API](https://github.com/caddyserver/caddy/blob/master/admin.go): `admin.go`
- [Module registry](https://github.com/caddyserver/caddy/blob/master/modules.go): `modules.go`
- [Standard modules](https://github.com/caddyserver/caddy/blob/master/modules/standard/imports.go): `modules/standard/imports.go`
- [Certificate storage](https://github.com/caddyserver/caddy/blob/master/modules/filestorage/filestorage.go): `modules/filestorage/filestorage.go`
- [Logging](https://github.com/caddyserver/caddy/blob/master/modules/logging/filewriter.go): `modules/logging/filewriter.go`
- [Metrics](https://github.com/caddyserver/caddy/blob/master/modules/metrics/metrics.go): `modules/metrics/metrics.go`

### Other components

- **Operator**
- **Native JSON config**
- **HTTP clients**
- **Upstream services**
- **Certificate issuers**

## Connections

- Operator → Caddy CLI: runs
- Caddy CLI → Config loading: loads config (evidence: `cmd/main.go`)
- Caddy CLI → HTTP adapter: adapts config
- Caddyfile parser → HTTP adapter: parses directives (evidence: `caddyconfig/httpcaddyfile/httptype.go`)
- HTTP adapter → HTTP app: builds app config (evidence: `caddyconfig/httpcaddyfile/httptype.go`)
- Config loading → Native JSON config: loads JSON
- Config loading → Admin API: configures runtime
- Standard modules → Module registry: registers modules (evidence: `modules/standard/imports.go`)
- HTTP app → HTTP server: starts servers
- HTTP server → Routes and handlers: dispatches requests
- Routes and handlers → Reverse proxy: routes to
- Reverse proxy → FastCGI client: uses FastCGI
- Reverse proxy → Upstream services: forwards requests
- Routes and handlers → Static files: routes to
- Routes and handlers → HTTP templates: renders templates
- Routes and handlers → HTTP/2 push: may push resources
- HTTP app → TLS automation: uses TLS
- TLS automation → Certificate issuers: obtains certificates
- TLS automation → Local PKI: supports local CA
- Local PKI → ACME server: serves ACME
- TLS automation → Certificate storage: stores certificates
- HTTP server → Logging: logs requests
- HTTP server → Metrics: exports metrics
