# publicsuffix/list architecture

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

- Interactive diagram: https://gitdiagram.com/publicsuffix/list
- Repository: https://github.com/publicsuffix/list

## Overview

The Public Suffix List is both a maintained domain-rule dataset and tooling for editing, validating, and using it. A contributor’s workflow runs through the psltool command interface, which parses and validates list data; the parser relies on domain-name handling, while online checks can consult GitHub and local history. The repository also provides suffix lookup, a standalone syntax linter, gTLD-list generation, and a private-domain review utility. Edges reflect excerpts, the source index, or README; unsampled internals are not inferred.

Main entry points: [`tools/psltool/psltool.go`](https://github.com/publicsuffix/list/blob/main/tools/psltool/psltool.go) (psltool CLI), [`tools/internal/parser/validate.go`](https://github.com/publicsuffix/list/blob/main/tools/internal/parser/validate.go) (List validation), [`tools/newgtlds.go`](https://github.com/publicsuffix/list/blob/main/tools/newgtlds.go) (gTLD updater), [`tools/private_domains_checker/PSLPrivateDomainsProcessor.py`](https://github.com/publicsuffix/list/blob/main/tools/private_domains_checker/PSLPrivateDomainsProcessor.py) (Private-domain checker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["List and lookup"]
  node_psl_data[("Suffix list")]
  node_lookup["Suffix lookup<br/>[file.go]"]
end

subgraph group_tooling["Editing and validation"]
  node_cli["psltool CLI<br/>[psltool.go]"]
  node_parser["PSL parser<br/>[parser.go]"]
  node_list_model["Parsed list model<br/>[file.go]"]
  node_domain["Domain handling<br/>[domain.go]"]
  node_cleaner["List formatting<br/>[clean.go]"]
  node_exceptions["Validation exceptions<br/>[exceptions.go]"]
  node_validation["List validation<br/>[validate.go]"]
  node_history["PR history<br/>[history.go]"]
  node_github["GitHub PR access<br/>[pr.go]"]
  node_linter["Syntax linter<br/>[pslint.py]"]
end

subgraph group_generation["List maintenance"]
  node_gtld["gTLD updater<br/>[newgtlds.go]"]
  node_icann["ICANN data"]
  node_iana["IANA data"]
end

subgraph group_review["Domain review"]
  node_private_checker["Private-domain checker"]
  node_dns["DNS services"]
  node_whois["WHOIS service"]
end

node_contributors(("Contributors"))

node_contributors -->|"run commands"| node_cli
node_cli -->|"parses list"| node_parser
node_parser -->|"parses names"| node_domain
node_cli -->|"validates list"| node_validation
node_validation -->|"checks names"| node_domain
node_validation -->|"checks PR history"| node_history
node_validation -->|"checks PR data"| node_github
node_cli -->|"loads PR history"| node_history
node_cli -->|"fetches PR list"| node_github
node_lookup -->|"uses domain names"| node_domain
node_cli -->|"formats list"| node_cleaner
node_linter -.->|"checks syntax"| node_psl_data
node_gtld -->|"fetches gTLD data"| node_icann
node_gtld -->|"fetches TLD data"| node_iana
node_gtld -.->|"updates entries"| node_psl_data
node_private_checker -->|"checks DNS"| node_dns
node_private_checker -.->|"queries WHOIS"| node_whois
node_private_checker -->|"fetches list"| node_psl_data

click node_psl_data "https://github.com/publicsuffix/list/blob/main/public_suffix_list.dat"
click node_lookup "https://github.com/publicsuffix/list/blob/main/tools/internal/parser/file.go"
click node_cli "https://github.com/publicsuffix/list/blob/main/tools/psltool/psltool.go"
click node_parser "https://github.com/publicsuffix/list/blob/main/tools/internal/parser/parser.go"
click node_list_model "https://github.com/publicsuffix/list/blob/main/tools/internal/parser/file.go"
click node_domain "https://github.com/publicsuffix/list/blob/main/tools/internal/domain/domain.go"
click node_cleaner "https://github.com/publicsuffix/list/blob/main/tools/internal/parser/clean.go"
click node_exceptions "https://github.com/publicsuffix/list/blob/main/tools/internal/parser/exceptions.go"
click node_validation "https://github.com/publicsuffix/list/blob/main/tools/internal/parser/validate.go"
click node_history "https://github.com/publicsuffix/list/blob/main/tools/internal/githistory/history.go"
click node_github "https://github.com/publicsuffix/list/blob/main/tools/internal/github/pr.go"
click node_linter "https://github.com/publicsuffix/list/blob/main/linter/pslint.py"
click node_gtld "https://github.com/publicsuffix/list/blob/main/tools/newgtlds.go"
click node_private_checker "https://github.com/publicsuffix/list/blob/main/tools/private_domains_checker/PSLPrivateDomainsProcessor.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_psl_data,node_lookup toneBlue
class node_cli,node_parser,node_list_model,node_domain,node_cleaner,node_exceptions,node_validation,node_history,node_github,node_linter toneAmber
class node_gtld,node_icann,node_iana toneMint
class node_private_checker,node_dns,node_whois toneRose
class node_contributors toneIndigo
```

## Components

### List and lookup

- [Suffix list](https://github.com/publicsuffix/list/blob/main/public_suffix_list.dat): `public_suffix_list.dat`
- [Suffix lookup](https://github.com/publicsuffix/list/blob/main/tools/internal/parser/file.go): `tools/internal/parser/file.go`

### Editing and validation

- [psltool CLI](https://github.com/publicsuffix/list/blob/main/tools/psltool/psltool.go): `tools/psltool/psltool.go`
- [PSL parser](https://github.com/publicsuffix/list/blob/main/tools/internal/parser/parser.go): `tools/internal/parser/parser.go`
- [Parsed list model](https://github.com/publicsuffix/list/blob/main/tools/internal/parser/file.go): `tools/internal/parser/file.go`
- [Domain handling](https://github.com/publicsuffix/list/blob/main/tools/internal/domain/domain.go): `tools/internal/domain/domain.go`
- [List formatting](https://github.com/publicsuffix/list/blob/main/tools/internal/parser/clean.go): `tools/internal/parser/clean.go`
- [Validation exceptions](https://github.com/publicsuffix/list/blob/main/tools/internal/parser/exceptions.go): `tools/internal/parser/exceptions.go`
- [List validation](https://github.com/publicsuffix/list/blob/main/tools/internal/parser/validate.go): `tools/internal/parser/validate.go`
- [PR history](https://github.com/publicsuffix/list/blob/main/tools/internal/githistory/history.go): `tools/internal/githistory/history.go`
- [GitHub PR access](https://github.com/publicsuffix/list/blob/main/tools/internal/github/pr.go): `tools/internal/github/pr.go`
- [Syntax linter](https://github.com/publicsuffix/list/blob/main/linter/pslint.py): `linter/pslint.py`

### List maintenance

- [gTLD updater](https://github.com/publicsuffix/list/blob/main/tools/newgtlds.go): `tools/newgtlds.go`
- **ICANN data**
- **IANA data**

### Domain review

- [Private-domain checker](https://github.com/publicsuffix/list/blob/main/tools/private_domains_checker/PSLPrivateDomainsProcessor.py): `tools/private_domains_checker/PSLPrivateDomainsProcessor.py`
- **DNS services**
- **WHOIS service**

### Other components

- **Contributors**

## Connections

- Contributors → psltool CLI: run commands (evidence: `tools/psltool/psltool.go`)
- psltool CLI → PSL parser: parses list (evidence: `tools/psltool/psltool.go`)
- PSL parser → Domain handling: parses names (evidence: `tools/internal/parser/parser.go`)
- psltool CLI → List validation: validates list (evidence: `tools/psltool/psltool.go`)
- List validation → Domain handling: checks names (evidence: `tools/internal/parser/validate.go`)
- List validation → PR history: checks PR history (evidence: `tools/internal/parser/validate.go`)
- List validation → GitHub PR access: checks PR data (evidence: `tools/internal/parser/validate.go`)
- psltool CLI → PR history: loads PR history (evidence: `tools/psltool/psltool.go`)
- psltool CLI → GitHub PR access: fetches PR list (evidence: `tools/psltool/psltool.go`)
- Suffix lookup → Domain handling: uses domain names (evidence: `tools/internal/parser/file.go`)
- psltool CLI → List formatting: formats list (evidence: `tools/psltool/psltool.go`)
- Syntax linter → Suffix list: checks syntax
- gTLD updater → ICANN data: fetches gTLD data (evidence: `tools/newgtlds.go`)
- gTLD updater → IANA data: fetches TLD data (evidence: `tools/newgtlds.go`)
- gTLD updater → Suffix list: updates entries
- Private-domain checker → DNS services: checks DNS (evidence: `tools/private_domains_checker/PSLPrivateDomainsProcessor.py`)
- Private-domain checker → WHOIS service: queries WHOIS
- Private-domain checker → Suffix list: fetches list (evidence: `tools/private_domains_checker/PSLPrivateDomainsProcessor.py`)
