# bufbuild/protoc-gen-validate architecture

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

- Interactive diagram: https://gitdiagram.com/bufbuild/protoc-gen-validate
- Repository: https://github.com/bufbuild/protoc-gen-validate

## Overview

PGV is a protoc plugin that turns validation rules attached to protobuf fields into language-specific validators. The main workflow is proto constraints → plugin and rule checking → language templates → generated validation code. Java also provides a validator runtime and optional gRPC interceptors; Python instead generates and caches validation functions at runtime. The graph reflects documented capabilities, but several template and runtime implementations were not sampled, so their internal connections are limited to relationships shown in the README or source index.

Main entry points: [`templates/pkg.go`](https://github.com/bufbuild/protoc-gen-validate/blob/main/templates/pkg.go) (Template selection), [`java/pgv-java-stub/src/main/java/io/envoyproxy/pgv/ValidatorIndex.java`](https://github.com/bufbuild/protoc-gen-validate/blob/main/java/pgv-java-stub/src/main/java/io/envoyproxy/pgv/ValidatorIndex.java) (Validator index), [`module/validate.go`](https://github.com/bufbuild/protoc-gen-validate/blob/main/module/validate.go) (Validation module), [`java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidatingClientInterceptor.java`](https://github.com/bufbuild/protoc-gen-validate/blob/main/java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidatingClientInterceptor.java) (gRPC client interceptor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_schema["Rules and checking"]
  node_proto_rules["Validation schema<br/>[validate.proto]"]
  node_checker["Rule checker<br/>[checker.go]"]
end

subgraph group_generation["Code generation"]
  node_plugin["Plugin entry points<br/>[main.go]"]
  node_default_entry["Default entry point<br/>[main.go]"]
  node_module["Validation module<br/>[validate.go]"]
  node_shared_context["Rule context<br/>[context.go]"]
  node_template_router["Template selection<br/>[pkg.go]"]
  node_go_templates["Go templates<br/>[register.go]"]
  node_cpp_templates["C++ templates<br/>[register.go]"]
  node_java_templates["Java templates<br/>[register.go]"]
end

subgraph group_runtimes["Validation runtimes"]
  node_python_api["Python validation API<br/>[__init__.py]"]
  node_python_runtime["JIT validator<br/>[validator.py]"]
  node_java_index["Validator index"]
  node_java_reflection["Reflective index"]
  node_java_validation["Java rule helpers"]
  node_java_exception["Validation errors"]
end

subgraph group_integrations["Protocol integrations"]
  node_grpc_client["gRPC client interceptor"]
  node_grpc_server["gRPC server interceptor"]
  node_grpc_errors["gRPC error mapping"]
end

node_protoc(("protoc"))
node_generated["Generated validators"]
node_developer(("Proto developer"))
node_java_app(("Java gRPC app"))

node_developer -->|"annotates messages"| node_proto_rules
node_protoc -->|"invokes plugin"| node_plugin
node_plugin -->|"registers language module"| node_module
node_protoc -->|"invokes plugin"| node_default_entry
node_default_entry -->|"registers module"| node_module
node_module -->|"checks rules"| node_checker
node_checker -->|"reads constraints"| node_proto_rules
node_module -->|"selects templates"| node_template_router
node_template_router -->|"registers shared functions"| node_shared_context
node_shared_context -->|"resolves rule types"| node_proto_rules
node_template_router -->|"selects Go templates"| node_go_templates
node_template_router -->|"selects C++ templates"| node_cpp_templates
node_template_router -->|"selects Java templates"| node_java_templates
node_go_templates -->|"renders validators"| node_generated
node_cpp_templates -->|"renders validators"| node_generated
node_java_templates -->|"renders validators"| node_generated
node_developer -->|"calls validate"| node_python_api
node_python_api -->|"generates on demand"| node_python_runtime
node_java_reflection -->|"implements lookup"| node_java_index
node_java_app -->|"requests validator"| node_java_index
node_grpc_client -->|"looks up validator"| node_java_index
node_grpc_server -->|"looks up validator"| node_java_index
node_java_index -.->|"runs validation"| node_java_validation
node_java_validation -->|"reports failures"| node_java_exception
node_grpc_client -->|"maps failures"| node_grpc_errors
node_grpc_server -->|"maps failures"| node_grpc_errors
node_java_app -->|"installs interceptor"| node_grpc_client
node_java_app -->|"installs interceptor"| node_grpc_server

click node_proto_rules "https://github.com/bufbuild/protoc-gen-validate/blob/main/validate/validate.proto"
click node_plugin "https://github.com/bufbuild/protoc-gen-validate/blob/main/cmd/protoc-gen-validate-go/main.go"
click node_default_entry "https://github.com/bufbuild/protoc-gen-validate/blob/main/main.go"
click node_module "https://github.com/bufbuild/protoc-gen-validate/blob/main/module/validate.go"
click node_checker "https://github.com/bufbuild/protoc-gen-validate/blob/main/module/checker.go"
click node_shared_context "https://github.com/bufbuild/protoc-gen-validate/blob/main/templates/shared/context.go"
click node_template_router "https://github.com/bufbuild/protoc-gen-validate/blob/main/templates/pkg.go"
click node_go_templates "https://github.com/bufbuild/protoc-gen-validate/blob/main/templates/goshared/register.go"
click node_cpp_templates "https://github.com/bufbuild/protoc-gen-validate/blob/main/templates/cc/register.go"
click node_java_templates "https://github.com/bufbuild/protoc-gen-validate/blob/main/templates/java/register.go"
click node_python_api "https://github.com/bufbuild/protoc-gen-validate/blob/main/python/protoc_gen_validate/__init__.py"
click node_python_runtime "https://github.com/bufbuild/protoc-gen-validate/blob/main/python/protoc_gen_validate/validator.py"
click node_java_index "https://github.com/bufbuild/protoc-gen-validate/blob/main/java/pgv-java-stub/src/main/java/io/envoyproxy/pgv/ValidatorIndex.java"
click node_java_reflection "https://github.com/bufbuild/protoc-gen-validate/blob/main/java/pgv-java-stub/src/main/java/io/envoyproxy/pgv/ReflectiveValidatorIndex.java"
click node_java_validation "https://github.com/bufbuild/protoc-gen-validate/blob/main/java/pgv-java-stub/src/main/java/io/envoyproxy/pgv/StringValidation.java"
click node_java_exception "https://github.com/bufbuild/protoc-gen-validate/blob/main/java/pgv-java-stub/src/main/java/io/envoyproxy/pgv/ValidationException.java"
click node_grpc_client "https://github.com/bufbuild/protoc-gen-validate/blob/main/java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidatingClientInterceptor.java"
click node_grpc_server "https://github.com/bufbuild/protoc-gen-validate/blob/main/java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidatingServerInterceptor.java"
click node_grpc_errors "https://github.com/bufbuild/protoc-gen-validate/blob/main/java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidationExceptions.java"

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_proto_rules,node_checker toneBlue
class node_plugin,node_default_entry,node_module,node_shared_context,node_template_router,node_go_templates,node_cpp_templates,node_java_templates toneAmber
class node_python_api,node_python_runtime,node_java_index,node_java_reflection,node_java_validation,node_java_exception toneMint
class node_grpc_client,node_grpc_server,node_grpc_errors toneRose
class node_protoc,node_generated,node_developer,node_java_app toneIndigo
```

## Components

### Rules and checking

- [Validation schema](https://github.com/bufbuild/protoc-gen-validate/blob/main/validate/validate.proto): `validate/validate.proto`
- [Rule checker](https://github.com/bufbuild/protoc-gen-validate/blob/main/module/checker.go): `module/checker.go`

### Code generation

- [Plugin entry points](https://github.com/bufbuild/protoc-gen-validate/blob/main/cmd/protoc-gen-validate-go/main.go): `cmd/protoc-gen-validate-go/main.go`
- [Default entry point](https://github.com/bufbuild/protoc-gen-validate/blob/main/main.go): `main.go`
- [Validation module](https://github.com/bufbuild/protoc-gen-validate/blob/main/module/validate.go): `module/validate.go`
- [Rule context](https://github.com/bufbuild/protoc-gen-validate/blob/main/templates/shared/context.go): `templates/shared/context.go`
- [Template selection](https://github.com/bufbuild/protoc-gen-validate/blob/main/templates/pkg.go): `templates/pkg.go`
- [Go templates](https://github.com/bufbuild/protoc-gen-validate/blob/main/templates/goshared/register.go): `templates/goshared/register.go`
- [C++ templates](https://github.com/bufbuild/protoc-gen-validate/blob/main/templates/cc/register.go): `templates/cc/register.go`
- [Java templates](https://github.com/bufbuild/protoc-gen-validate/blob/main/templates/java/register.go): `templates/java/register.go`

### Validation runtimes

- [Python validation API](https://github.com/bufbuild/protoc-gen-validate/blob/main/python/protoc_gen_validate/__init__.py): `python/protoc_gen_validate/__init__.py`
- [JIT validator](https://github.com/bufbuild/protoc-gen-validate/blob/main/python/protoc_gen_validate/validator.py): `python/protoc_gen_validate/validator.py`
- [Validator index](https://github.com/bufbuild/protoc-gen-validate/blob/main/java/pgv-java-stub/src/main/java/io/envoyproxy/pgv/ValidatorIndex.java): `java/pgv-java-stub/src/main/java/io/envoyproxy/pgv/ValidatorIndex.java`
- [Reflective index](https://github.com/bufbuild/protoc-gen-validate/blob/main/java/pgv-java-stub/src/main/java/io/envoyproxy/pgv/ReflectiveValidatorIndex.java): `java/pgv-java-stub/src/main/java/io/envoyproxy/pgv/ReflectiveValidatorIndex.java`
- [Java rule helpers](https://github.com/bufbuild/protoc-gen-validate/blob/main/java/pgv-java-stub/src/main/java/io/envoyproxy/pgv/StringValidation.java): `java/pgv-java-stub/src/main/java/io/envoyproxy/pgv/StringValidation.java`
- [Validation errors](https://github.com/bufbuild/protoc-gen-validate/blob/main/java/pgv-java-stub/src/main/java/io/envoyproxy/pgv/ValidationException.java): `java/pgv-java-stub/src/main/java/io/envoyproxy/pgv/ValidationException.java`

### Protocol integrations

- [gRPC client interceptor](https://github.com/bufbuild/protoc-gen-validate/blob/main/java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidatingClientInterceptor.java): `java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidatingClientInterceptor.java`
- [gRPC server interceptor](https://github.com/bufbuild/protoc-gen-validate/blob/main/java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidatingServerInterceptor.java): `java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidatingServerInterceptor.java`
- [gRPC error mapping](https://github.com/bufbuild/protoc-gen-validate/blob/main/java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidationExceptions.java): `java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidationExceptions.java`

### Other components

- **protoc**
- **Generated validators**
- **Proto developer**
- **Java gRPC app**

## Connections

- Proto developer → Validation schema: annotates messages
- protoc → Plugin entry points: invokes plugin
- Plugin entry points → Validation module: registers language module (evidence: `cmd/protoc-gen-validate-go/main.go`)
- protoc → Default entry point: invokes plugin
- Default entry point → Validation module: registers module (evidence: `main.go`)
- Validation module → Rule checker: checks rules (evidence: `module/checker.go`)
- Rule checker → Validation schema: reads constraints (evidence: `module/checker.go`)
- Validation module → Template selection: selects templates (evidence: `module/validate.go`)
- Template selection → Rule context: registers shared functions (evidence: `templates/pkg.go`)
- Rule context → Validation schema: resolves rule types (evidence: `templates/shared/context.go`)
- Template selection → Go templates: selects Go templates (evidence: `templates/pkg.go`)
- Template selection → C++ templates: selects C++ templates (evidence: `templates/pkg.go`)
- Template selection → Java templates: selects Java templates (evidence: `templates/pkg.go`)
- Go templates → Generated validators: renders validators
- C++ templates → Generated validators: renders validators
- Java templates → Generated validators: renders validators
- Proto developer → Python validation API: calls validate
- Python validation API → JIT validator: generates on demand
- Reflective index → Validator index: implements lookup (evidence: `java/pgv-java-validation/src/main/java/io/envoyproxy/pgv/validation/JavaHarness.java`)
- Java gRPC app → Validator index: requests validator
- gRPC client interceptor → Validator index: looks up validator (evidence: `java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidatingClientInterceptor.java`)
- gRPC server interceptor → Validator index: looks up validator (evidence: `java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidatingServerInterceptor.java`)
- Validator index → Java rule helpers: runs validation
- Java rule helpers → Validation errors: reports failures (evidence: `java/pgv-java-stub/src/main/java/io/envoyproxy/pgv/StringValidation.java`)
- gRPC client interceptor → gRPC error mapping: maps failures (evidence: `java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidatingClientInterceptor.java`)
- gRPC server interceptor → gRPC error mapping: maps failures (evidence: `java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidatingServerInterceptor.java`)
- Java gRPC app → gRPC client interceptor: installs interceptor
- Java gRPC app → gRPC server interceptor: installs interceptor
