# google/certificate-transparency-go architecture

> Architecture diagram of the GitHub repository google/certificate-transparency-go, 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/google/certificate-transparency-go
- Repository: https://github.com/google/certificate-transparency-go

## Overview

This repository is a Certificate Transparency toolkit and service implementation. Its main user workflows are querying and scanning CT logs, validating certificate/log data, submitting certificate chains to policy-selected logs, and operating a Trillian-backed CT log. The graph includes documented capabilities whose source was not sampled; their internal wiring is omitted where the excerpts do not establish it.

Main entry points: [`client`](https://github.com/google/certificate-transparency-go/tree/master/client) (Log client library), [`submission/distributor.go`](https://github.com/google/certificate-transparency-go/blob/master/submission/distributor.go) (Log distributor), [`trillian/migrillian/core/controller.go`](https://github.com/google/certificate-transparency-go/blob/master/trillian/migrillian/core/controller.go) (Migration controller), [`trillian/ctfe`](https://github.com/google/certificate-transparency-go/tree/master/trillian/ctfe) (CTFE personality)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_formats["CT formats and validation"]
  node_ctdata["CT data types<br/>[types.go]"]
  node_asn1["ASN.1 encoding"]
  node_x509["Certificate parsing"]
  node_tls["TLS encoding"]
  node_x509util["Certificate utilities"]
end

subgraph group_clients["Log clients and monitoring"]
  node_ctclient["CT command client"]
  node_clientlib["Log client library"]
  node_jsonclient["JSON HTTP client"]
  node_scanner["Log scanner"]
end

subgraph group_submission["Multi-log submission"]
  node_submissionserver["Submission server"]
  node_proxy["Submission proxy<br/>[proxy.go]"]
  node_distributor["Log distributor<br/>[distributor.go]"]
end

subgraph group_trillian["Trillian services"]
  node_ctfe["CTFE personality"]
  node_ctfehandlers["CTFE request handlers<br/>[handlers.go]"]
  node_issuancestorage["Issuance-chain storage<br/>[storage.go]"]
  node_sqldb[("SQL storage backends")]
  node_migrillian["Log migration runner<br/>[main.go]"]
  node_controller["Migration controller<br/>[controller.go]"]
end

subgraph group_operations["Utilities and policy"]
  node_ctutil["CT verification tools"]
  node_loglist["Log list reader"]
  node_policy["CT policy rules"]
end

node_user(("Engineer or service"))
node_logservice{{"CT log endpoint"}}
node_trillianbackend{{"Trillian log backend"}}

node_user -->|"runs commands"| node_ctclient
node_ctclient -->|"dispatches requests"| node_clientlib
node_clientlib -->|"queries log"| node_logservice
node_scanner -->|"fetches entries"| node_clientlib
node_user -->|"starts scan"| node_scanner
node_user -->|"submits chains"| node_submissionserver
node_submissionserver -->|"serves requests"| node_proxy
node_proxy -->|"dispatches submissions"| node_distributor
node_distributor -->|"selects logs by"| node_policy
node_distributor -->|"submits chains"| node_logservice
node_ctfe -->|"serves requests"| node_ctfehandlers
node_ctfehandlers -->|"reads and writes"| node_trillianbackend
node_ctfe -->|"selects storage"| node_issuancestorage
node_issuancestorage -->|"uses SQL backend"| node_sqldb
node_migrillian -->|"runs migrations"| node_controller
node_controller -->|"fetches source entries"| node_clientlib
node_controller -->|"writes leaves"| node_trillianbackend
node_ctutil -->|"validates structures"| node_ctdata
node_x509util -->|"uses certificates"| node_x509
node_jsonclient -->|"sends HTTP requests"| node_logservice

click node_ctdata "https://github.com/google/certificate-transparency-go/blob/master/types.go"
click node_asn1 "https://github.com/google/certificate-transparency-go/tree/master/asn1"
click node_x509 "https://github.com/google/certificate-transparency-go/tree/master/x509"
click node_tls "https://github.com/google/certificate-transparency-go/tree/master/tls"
click node_x509util "https://github.com/google/certificate-transparency-go/tree/master/x509util"
click node_ctclient "https://github.com/google/certificate-transparency-go/tree/master/client/ctclient"
click node_clientlib "https://github.com/google/certificate-transparency-go/tree/master/client"
click node_jsonclient "https://github.com/google/certificate-transparency-go/tree/master/jsonclient"
click node_scanner "https://github.com/google/certificate-transparency-go/tree/master/scanner"
click node_ctutil "https://github.com/google/certificate-transparency-go/tree/master/ctutil"
click node_loglist "https://github.com/google/certificate-transparency-go/tree/master/loglist3"
click node_policy "https://github.com/google/certificate-transparency-go/tree/master/ctpolicy"
click node_submissionserver "https://github.com/google/certificate-transparency-go/tree/master/submission/server"
click node_proxy "https://github.com/google/certificate-transparency-go/blob/master/submission/proxy.go"
click node_distributor "https://github.com/google/certificate-transparency-go/blob/master/submission/distributor.go"
click node_ctfe "https://github.com/google/certificate-transparency-go/tree/master/trillian/ctfe"
click node_ctfehandlers "https://github.com/google/certificate-transparency-go/blob/master/trillian/ctfe/handlers.go"
click node_issuancestorage "https://github.com/google/certificate-transparency-go/blob/master/trillian/ctfe/storage/storage.go"
click node_sqldb "https://github.com/google/certificate-transparency-go/tree/master/trillian/ctfe/storage"
click node_migrillian "https://github.com/google/certificate-transparency-go/blob/master/trillian/migrillian/main.go"
click node_controller "https://github.com/google/certificate-transparency-go/blob/master/trillian/migrillian/core/controller.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_ctdata,node_asn1,node_x509,node_tls,node_x509util toneBlue
class node_ctclient,node_clientlib,node_jsonclient,node_scanner toneAmber
class node_submissionserver,node_proxy,node_distributor toneMint
class node_ctfe,node_ctfehandlers,node_issuancestorage,node_sqldb,node_migrillian,node_controller toneRose
class node_ctutil,node_loglist,node_policy,node_user,node_logservice,node_trillianbackend toneIndigo
```

## Components

### CT formats and validation

- [CT data types](https://github.com/google/certificate-transparency-go/blob/master/types.go): `types.go`
- [ASN.1 encoding](https://github.com/google/certificate-transparency-go/tree/master/asn1): `asn1`
- [Certificate parsing](https://github.com/google/certificate-transparency-go/tree/master/x509): `x509`
- [TLS encoding](https://github.com/google/certificate-transparency-go/tree/master/tls): `tls`
- [Certificate utilities](https://github.com/google/certificate-transparency-go/tree/master/x509util): `x509util`

### Log clients and monitoring

- [CT command client](https://github.com/google/certificate-transparency-go/tree/master/client/ctclient): `client/ctclient`
- [Log client library](https://github.com/google/certificate-transparency-go/tree/master/client): `client`
- [JSON HTTP client](https://github.com/google/certificate-transparency-go/tree/master/jsonclient): `jsonclient`
- [Log scanner](https://github.com/google/certificate-transparency-go/tree/master/scanner): `scanner`

### Multi-log submission

- [Submission server](https://github.com/google/certificate-transparency-go/tree/master/submission/server): `submission/server`
- [Submission proxy](https://github.com/google/certificate-transparency-go/blob/master/submission/proxy.go): `submission/proxy.go`
- [Log distributor](https://github.com/google/certificate-transparency-go/blob/master/submission/distributor.go): `submission/distributor.go`

### Trillian services

- [CTFE personality](https://github.com/google/certificate-transparency-go/tree/master/trillian/ctfe): `trillian/ctfe`
- [CTFE request handlers](https://github.com/google/certificate-transparency-go/blob/master/trillian/ctfe/handlers.go): `trillian/ctfe/handlers.go`
- [Issuance-chain storage](https://github.com/google/certificate-transparency-go/blob/master/trillian/ctfe/storage/storage.go): `trillian/ctfe/storage/storage.go`
- [SQL storage backends](https://github.com/google/certificate-transparency-go/tree/master/trillian/ctfe/storage): `trillian/ctfe/storage`
- [Log migration runner](https://github.com/google/certificate-transparency-go/blob/master/trillian/migrillian/main.go): `trillian/migrillian/main.go`
- [Migration controller](https://github.com/google/certificate-transparency-go/blob/master/trillian/migrillian/core/controller.go): `trillian/migrillian/core/controller.go`

### Utilities and policy

- [CT verification tools](https://github.com/google/certificate-transparency-go/tree/master/ctutil): `ctutil`
- [Log list reader](https://github.com/google/certificate-transparency-go/tree/master/loglist3): `loglist3`
- [CT policy rules](https://github.com/google/certificate-transparency-go/tree/master/ctpolicy): `ctpolicy`

### Other components

- **Engineer or service**
- **CT log endpoint**
- **Trillian log backend**

## Connections

- Engineer or service → CT command client: runs commands
- CT command client → Log client library: dispatches requests
- Log client library → CT log endpoint: queries log
- Log scanner → Log client library: fetches entries
- Engineer or service → Log scanner: starts scan
- Engineer or service → Submission server: submits chains
- Submission server → Submission proxy: serves requests
- Submission proxy → Log distributor: dispatches submissions
- Log distributor → CT policy rules: selects logs by
- Log distributor → CT log endpoint: submits chains
- CTFE personality → CTFE request handlers: serves requests
- CTFE request handlers → Trillian log backend: reads and writes
- CTFE personality → Issuance-chain storage: selects storage
- Issuance-chain storage → SQL storage backends: uses SQL backend
- Log migration runner → Migration controller: runs migrations
- Migration controller → Log client library: fetches source entries
- Migration controller → Trillian log backend: writes leaves
- CT verification tools → CT data types: validates structures
- Certificate utilities → Certificate parsing: uses certificates
- JSON HTTP client → CT log endpoint: sends HTTP requests