# opentofu/registry architecture

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

- Interactive diagram: https://gitdiagram.com/opentofu/registry
- Repository: https://github.com/opentofu/registry

## Overview

OpenTofu Registry is a metadata-backed registry for providers and modules. Its main workflow is to discover repository releases, maintain and validate registry metadata, generate v1 API response files, and serve those files to registry clients. Separate commands support adding entries, updating versions and backfilling history, and checking provider signing keys. The README also describes GitHub issue-form submissions, which are a human intake process rather than an in-repository runtime path. The graph focuses on documented capabilities and evidenced command wiring; source excerpts are partial, so uncertain internal links are omitted.

Main entry points: [`src/cmd/bump-versions/main.go`](https://github.com/opentofu/registry/blob/main/src/cmd/bump-versions/main.go) (Bump versions), [`src/internal/provider/list.go`](https://github.com/opentofu/registry/blob/main/src/internal/provider/list.go) (Provider discovery), [`src/internal/github/client.go`](https://github.com/opentofu/registry/blob/main/src/internal/github/client.go) (GitHub client), [`src/cmd/verify-gpg-key/main.go`](https://github.com/opentofu/registry/blob/main/src/cmd/verify-gpg-key/main.go) (Key verification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Catalog management"]
  node_addmodule["Add module<br/>[main.go]"]
  node_addprovider["Add provider<br/>[main.go]"]
  node_bump["Bump versions<br/>[main.go]"]
  node_modules["Module metadata<br/>[module.go]"]
  node_modulelist["Module discovery<br/>[list.go]"]
  node_providers["Provider metadata<br/>[provider.go]"]
  node_providerlist["Provider discovery<br/>[list.go]"]
  node_backfill["Version backfill<br/>[backfill.go]"]
end

subgraph group_github["GitHub integration"]
  node_ghclient["GitHub client<br/>[client.go]"]
  node_ghassets["Release assets<br/>[assets.go]"]
end

subgraph group_trust["Validation and signing"]
  node_gpgcheck["Key verification<br/>[main.go]"]
  node_gpgkeys["Signing keys<br/>[keycollection.go]"]
  node_validate["Metadata validation<br/>[main.go]"]
end

subgraph group_api["API publication"]
  node_generate["Generate API<br/>[main.go]"]
  node_v1modules["Module API output<br/>[modules.go]"]
  node_v1providers["Provider API output<br/>[providers.go]"]
  node_generated["Generated responses"]
  node_server["HTTPS file server<br/>[main.go]"]
end

node_submitter(("Registry submitter"))
node_clients(("Registry clients"))
node_gpgstore["GPG key files"]

node_submitter -.->|"submits module"| node_addmodule
node_submitter -.->|"submits provider"| node_addprovider
node_addmodule -->|"lists entries"| node_modulelist
node_addmodule -->|"writes metadata"| node_modules
node_addprovider -->|"lists entries"| node_providerlist
node_addprovider -->|"writes metadata"| node_providers
node_bump -->|"lists modules"| node_modulelist
node_bump -->|"lists providers"| node_providerlist
node_bump -->|"updates metadata"| node_modules
node_bump -->|"updates metadata"| node_providers
node_bump -->|"backfills versions"| node_backfill
node_modulelist -->|"queries repositories"| node_ghclient
node_providerlist -->|"queries repositories"| node_ghclient
node_backfill -->|"fetches history"| node_ghclient
node_ghclient -->|"downloads assets"| node_ghassets
node_validate -->|"validates module data"| node_modules
node_validate -->|"validates provider data"| node_providers
node_gpgcheck -->|"finds providers"| node_providerlist
node_gpgcheck -->|"uses key checks"| node_gpgkeys
node_gpgcheck -->|"checks membership"| node_ghclient
node_gpgcheck -->|"downloads signatures"| node_ghassets
node_gpgkeys -->|"reads keys"| node_gpgstore
node_generate -->|"lists modules"| node_modulelist
node_generate -->|"lists providers"| node_providerlist
node_generate -->|"generates module API"| node_v1modules
node_generate -->|"generates provider API"| node_v1providers
node_v1modules -->|"reads metadata"| node_modules
node_v1modules -->|"writes responses"| node_generated
node_v1providers -->|"reads metadata"| node_providers
node_v1providers -->|"loads signing keys"| node_gpgkeys
node_v1providers -->|"writes responses"| node_generated
node_server -->|"serves files"| node_generated
node_clients -->|"requests API"| node_server

click node_addmodule "https://github.com/opentofu/registry/blob/main/src/cmd/add-module/main.go"
click node_addprovider "https://github.com/opentofu/registry/blob/main/src/cmd/add-provider/main.go"
click node_bump "https://github.com/opentofu/registry/blob/main/src/cmd/bump-versions/main.go"
click node_modules "https://github.com/opentofu/registry/blob/main/src/internal/module/module.go"
click node_modulelist "https://github.com/opentofu/registry/blob/main/src/internal/module/list.go"
click node_providers "https://github.com/opentofu/registry/blob/main/src/internal/provider/provider.go"
click node_providerlist "https://github.com/opentofu/registry/blob/main/src/internal/provider/list.go"
click node_backfill "https://github.com/opentofu/registry/blob/main/src/internal/provider/backfill.go"
click node_ghclient "https://github.com/opentofu/registry/blob/main/src/internal/github/client.go"
click node_ghassets "https://github.com/opentofu/registry/blob/main/src/internal/github/assets.go"
click node_gpgcheck "https://github.com/opentofu/registry/blob/main/src/cmd/verify-gpg-key/main.go"
click node_gpgkeys "https://github.com/opentofu/registry/blob/main/src/internal/gpg/keycollection.go"
click node_validate "https://github.com/opentofu/registry/blob/main/src/cmd/validate/main.go"
click node_generate "https://github.com/opentofu/registry/blob/main/src/cmd/generate-v1/main.go"
click node_v1modules "https://github.com/opentofu/registry/blob/main/src/internal/v1api/modules.go"
click node_v1providers "https://github.com/opentofu/registry/blob/main/src/internal/v1api/providers.go"
click node_server "https://github.com/opentofu/registry/blob/main/src/cmd/run-server/main.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_addmodule,node_addprovider,node_bump,node_modules,node_modulelist,node_providers,node_providerlist,node_backfill,node_clients toneBlue
class node_ghclient,node_ghassets toneAmber
class node_gpgcheck,node_gpgkeys,node_validate toneMint
class node_generate,node_v1modules,node_v1providers,node_generated,node_server toneRose
class node_submitter,node_gpgstore toneIndigo
```

## Components

### Catalog management

- [Add module](https://github.com/opentofu/registry/blob/main/src/cmd/add-module/main.go): `src/cmd/add-module/main.go`
- [Add provider](https://github.com/opentofu/registry/blob/main/src/cmd/add-provider/main.go): `src/cmd/add-provider/main.go`
- [Bump versions](https://github.com/opentofu/registry/blob/main/src/cmd/bump-versions/main.go): `src/cmd/bump-versions/main.go`
- [Module metadata](https://github.com/opentofu/registry/blob/main/src/internal/module/module.go): `src/internal/module/module.go`
- [Module discovery](https://github.com/opentofu/registry/blob/main/src/internal/module/list.go): `src/internal/module/list.go`
- [Provider metadata](https://github.com/opentofu/registry/blob/main/src/internal/provider/provider.go): `src/internal/provider/provider.go`
- [Provider discovery](https://github.com/opentofu/registry/blob/main/src/internal/provider/list.go): `src/internal/provider/list.go`
- [Version backfill](https://github.com/opentofu/registry/blob/main/src/internal/provider/backfill.go): `src/internal/provider/backfill.go`

### GitHub integration

- [GitHub client](https://github.com/opentofu/registry/blob/main/src/internal/github/client.go): `src/internal/github/client.go`
- [Release assets](https://github.com/opentofu/registry/blob/main/src/internal/github/assets.go): `src/internal/github/assets.go`

### Validation and signing

- [Key verification](https://github.com/opentofu/registry/blob/main/src/cmd/verify-gpg-key/main.go): `src/cmd/verify-gpg-key/main.go`
- [Signing keys](https://github.com/opentofu/registry/blob/main/src/internal/gpg/keycollection.go): `src/internal/gpg/keycollection.go`
- [Metadata validation](https://github.com/opentofu/registry/blob/main/src/cmd/validate/main.go): `src/cmd/validate/main.go`

### API publication

- [Generate API](https://github.com/opentofu/registry/blob/main/src/cmd/generate-v1/main.go): `src/cmd/generate-v1/main.go`
- [Module API output](https://github.com/opentofu/registry/blob/main/src/internal/v1api/modules.go): `src/internal/v1api/modules.go`
- [Provider API output](https://github.com/opentofu/registry/blob/main/src/internal/v1api/providers.go): `src/internal/v1api/providers.go`
- **Generated responses**
- [HTTPS file server](https://github.com/opentofu/registry/blob/main/src/cmd/run-server/main.go): `src/cmd/run-server/main.go`

### Other components

- **Registry submitter**
- **Registry clients**
- **GPG key files**

## Connections

- Registry submitter → Add module: submits module
- Registry submitter → Add provider: submits provider
- Add module → Module discovery: lists entries
- Add module → Module metadata: writes metadata
- Add provider → Provider discovery: lists entries
- Add provider → Provider metadata: writes metadata
- Bump versions → Module discovery: lists modules
- Bump versions → Provider discovery: lists providers
- Bump versions → Module metadata: updates metadata
- Bump versions → Provider metadata: updates metadata
- Bump versions → Version backfill: backfills versions
- Module discovery → GitHub client: queries repositories
- Provider discovery → GitHub client: queries repositories
- Version backfill → GitHub client: fetches history
- GitHub client → Release assets: downloads assets
- Metadata validation → Module metadata: validates module data
- Metadata validation → Provider metadata: validates provider data
- Key verification → Provider discovery: finds providers
- Key verification → Signing keys: uses key checks
- Key verification → GitHub client: checks membership
- Key verification → Release assets: downloads signatures
- Signing keys → GPG key files: reads keys
- Generate API → Module discovery: lists modules
- Generate API → Provider discovery: lists providers
- Generate API → Module API output: generates module API
- Generate API → Provider API output: generates provider API
- Module API output → Module metadata: reads metadata
- Module API output → Generated responses: writes responses
- Provider API output → Provider metadata: reads metadata
- Provider API output → Signing keys: loads signing keys
- Provider API output → Generated responses: writes responses
- HTTPS file server → Generated responses: serves files
- Registry clients → HTTPS file server: requests API