# go-kratos/kratos architecture

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

- Interactive diagram: https://gitdiagram.com/go-kratos/kratos
- Repository: https://github.com/go-kratos/kratos

## Overview

Kratos is a Go framework for building cloud-native microservices. Its primary workflow is API-first service development: developers use the CLI and Protobuf generators to scaffold a service, then run it through the application lifecycle with HTTP and/or gRPC transports. Clients can discover and select service instances; middleware, configuration, encoding, logging, and registry implementations provide supporting capabilities. Source excerpts establish several runtime calls, while README statements support the documented code-generation workflow and broad feature branches; unsampled subsystem links are omitted or marked unverified.

Main entry points: [`app.go`](https://github.com/go-kratos/kratos/blob/main/app.go) (App lifecycle), [`cmd/kratos`](https://github.com/go-kratos/kratos/tree/main/cmd/kratos) (Kratos CLI), [`middleware`](https://github.com/go-kratos/kratos/tree/main/middleware) (Middleware), [`registry/registry.go`](https://github.com/go-kratos/kratos/blob/main/registry/registry.go) (Registry API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dev["Service development"]
  node_cli["Kratos CLI"]
  node_proto_api["Protobuf API"]
  node_http_codegen["HTTP generator<br/>[main.go]"]
  node_errors_codegen["Errors generator<br/>[main.go]"]
end

subgraph group_runtime["Application runtime"]
  node_app["App lifecycle<br/>[app.go]"]
  node_middleware["Middleware"]
  node_config["Configuration"]
  node_logging["Logging"]
end

subgraph group_transport["Transport and clients"]
  node_http_server["HTTP server<br/>[server.go]"]
  node_grpc_server["gRPC server<br/>[server.go]"]
  node_http_client["HTTP client<br/>[client.go]"]
  node_grpc_client["gRPC client<br/>[client.go]"]
  node_encoding["Encoding codecs"]
end

subgraph group_platform["Service platform"]
  node_registry_api["Registry API<br/>[registry.go]"]
  node_selector["Node selection"]
  node_consul[("Consul registry<br/>[client.go]")]
  node_polaris["Polaris routing<br/>[router.go]"]
  node_form_proto["Protobuf form decoding<br/>[proto_decode.go]"]
end

subgraph group_ecosystem["Extensions"]
  node_contrib["Contrib integrations"]
  node_mcp["MCP transport<br/>[server.go]"]
  node_oauth["OAuth2 middleware<br/>[server.go]"]
end

node_developer(("Service developer"))

node_developer -->|"scaffolds service"| node_cli
node_developer -->|"defines API"| node_proto_api
node_proto_api -->|"adds API"| node_cli
node_cli -->|"generates HTTP"| node_http_codegen
node_cli -.->|"generates errors"| node_errors_codegen
node_developer -->|"runs service"| node_app
node_app -->|"starts and stops"| node_http_server
node_app -.->|"starts and stops"| node_grpc_server
node_app -->|"registers instance"| node_registry_api
node_http_server -->|"applies middleware"| node_middleware
node_grpc_server -->|"applies middleware"| node_middleware
node_app -->|"sets default logger"| node_logging
node_http_client -->|"encodes requests"| node_encoding
node_http_client -->|"uses discovery"| node_registry_api
node_http_client -->|"selects nodes"| node_selector
node_grpc_client -->|"uses discovery"| node_registry_api
node_grpc_client -->|"selects peers"| node_selector
node_grpc_client -->|"chains middleware"| node_middleware
node_consul -->|"returns instances"| node_registry_api
node_polaris -->|"reads node metadata"| node_selector
node_form_proto -->|"uses proto JSON"| node_encoding
node_mcp -->|"extends transport"| node_contrib
node_oauth -->|"implements middleware"| node_middleware
node_developer -.->|"adopts integrations"| node_contrib
node_developer -.->|"configures services"| node_config
node_developer -.->|"chooses formats"| node_encoding

click node_cli "https://github.com/go-kratos/kratos/tree/main/cmd/kratos"
click node_http_codegen "https://github.com/go-kratos/kratos/blob/main/cmd/protoc-gen-go-http/main.go"
click node_errors_codegen "https://github.com/go-kratos/kratos/blob/main/cmd/protoc-gen-go-errors/main.go"
click node_app "https://github.com/go-kratos/kratos/blob/main/app.go"
click node_middleware "https://github.com/go-kratos/kratos/tree/main/middleware"
click node_config "https://github.com/go-kratos/kratos/tree/main/config"
click node_logging "https://github.com/go-kratos/kratos/tree/main/log"
click node_http_server "https://github.com/go-kratos/kratos/blob/main/transport/http/server.go"
click node_grpc_server "https://github.com/go-kratos/kratos/blob/main/transport/grpc/server.go"
click node_http_client "https://github.com/go-kratos/kratos/blob/main/transport/http/client.go"
click node_grpc_client "https://github.com/go-kratos/kratos/blob/main/transport/grpc/client.go"
click node_encoding "https://github.com/go-kratos/kratos/tree/main/encoding"
click node_registry_api "https://github.com/go-kratos/kratos/blob/main/registry/registry.go"
click node_selector "https://github.com/go-kratos/kratos/tree/main/selector"
click node_consul "https://github.com/go-kratos/kratos/blob/main/contrib/registry/consul/client.go"
click node_polaris "https://github.com/go-kratos/kratos/blob/main/contrib/polaris/router.go"
click node_form_proto "https://github.com/go-kratos/kratos/blob/main/encoding/form/proto_decode.go"
click node_contrib "https://github.com/go-kratos/kratos/tree/main/contrib"
click node_mcp "https://github.com/go-kratos/kratos/blob/main/contrib/transport/mcp/server.go"
click node_oauth "https://github.com/go-kratos/kratos/blob/main/contrib/middleware/oauth2/server.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_cli,node_proto_api,node_http_codegen,node_errors_codegen toneBlue
class node_app,node_middleware,node_config,node_logging toneAmber
class node_http_server,node_grpc_server,node_http_client,node_grpc_client,node_encoding toneMint
class node_registry_api,node_selector,node_consul,node_polaris,node_form_proto toneRose
class node_contrib,node_mcp,node_oauth,node_developer toneIndigo
```

## Components

### Service development

- [Kratos CLI](https://github.com/go-kratos/kratos/tree/main/cmd/kratos): `cmd/kratos`
- **Protobuf API**
- [HTTP generator](https://github.com/go-kratos/kratos/blob/main/cmd/protoc-gen-go-http/main.go): `cmd/protoc-gen-go-http/main.go`
- [Errors generator](https://github.com/go-kratos/kratos/blob/main/cmd/protoc-gen-go-errors/main.go): `cmd/protoc-gen-go-errors/main.go`

### Application runtime

- [App lifecycle](https://github.com/go-kratos/kratos/blob/main/app.go): `app.go`
- [Middleware](https://github.com/go-kratos/kratos/tree/main/middleware): `middleware`
- [Configuration](https://github.com/go-kratos/kratos/tree/main/config): `config`
- [Logging](https://github.com/go-kratos/kratos/tree/main/log): `log`

### Transport and clients

- [HTTP server](https://github.com/go-kratos/kratos/blob/main/transport/http/server.go): `transport/http/server.go`
- [gRPC server](https://github.com/go-kratos/kratos/blob/main/transport/grpc/server.go): `transport/grpc/server.go`
- [HTTP client](https://github.com/go-kratos/kratos/blob/main/transport/http/client.go): `transport/http/client.go`
- [gRPC client](https://github.com/go-kratos/kratos/blob/main/transport/grpc/client.go): `transport/grpc/client.go`
- [Encoding codecs](https://github.com/go-kratos/kratos/tree/main/encoding): `encoding`

### Service platform

- [Registry API](https://github.com/go-kratos/kratos/blob/main/registry/registry.go): `registry/registry.go`
- [Node selection](https://github.com/go-kratos/kratos/tree/main/selector): `selector`
- [Consul registry](https://github.com/go-kratos/kratos/blob/main/contrib/registry/consul/client.go): `contrib/registry/consul/client.go`
- [Polaris routing](https://github.com/go-kratos/kratos/blob/main/contrib/polaris/router.go): `contrib/polaris/router.go`
- [Protobuf form decoding](https://github.com/go-kratos/kratos/blob/main/encoding/form/proto_decode.go): `encoding/form/proto_decode.go`

### Extensions

- [Contrib integrations](https://github.com/go-kratos/kratos/tree/main/contrib): `contrib`
- [MCP transport](https://github.com/go-kratos/kratos/blob/main/contrib/transport/mcp/server.go): `contrib/transport/mcp/server.go`
- [OAuth2 middleware](https://github.com/go-kratos/kratos/blob/main/contrib/middleware/oauth2/server.go): `contrib/middleware/oauth2/server.go`

### Other components

- **Service developer**

## Connections

- Service developer → Kratos CLI: scaffolds service (evidence: `README.md`)
- Service developer → Protobuf API: defines API (evidence: `README.md`)
- Protobuf API → Kratos CLI: adds API (evidence: `README.md`)
- Kratos CLI → HTTP generator: generates HTTP (evidence: `README.md`)
- Kratos CLI → Errors generator: generates errors
- Service developer → App lifecycle: runs service (evidence: `README.md`)
- App lifecycle → HTTP server: starts and stops (evidence: `app.go`)
- App lifecycle → gRPC server: starts and stops
- App lifecycle → Registry API: registers instance (evidence: `app.go`)
- HTTP server → Middleware: applies middleware (evidence: `transport/http/server.go`)
- gRPC server → Middleware: applies middleware (evidence: `transport/grpc/server.go`)
- App lifecycle → Logging: sets default logger (evidence: `app.go`)
- HTTP client → Encoding codecs: encodes requests (evidence: `transport/http/client.go`)
- HTTP client → Registry API: uses discovery (evidence: `transport/http/client.go`)
- HTTP client → Node selection: selects nodes (evidence: `transport/http/client.go`)
- gRPC client → Registry API: uses discovery (evidence: `transport/grpc/client.go`)
- gRPC client → Node selection: selects peers (evidence: `transport/grpc/client.go`)
- gRPC client → Middleware: chains middleware (evidence: `transport/grpc/client.go`)
- Consul registry → Registry API: returns instances (evidence: `contrib/registry/consul/client.go`)
- Polaris routing → Node selection: reads node metadata (evidence: `contrib/polaris/router.go`)
- Protobuf form decoding → Encoding codecs: uses proto JSON (evidence: `encoding/form/proto_decode.go`)
- MCP transport → Contrib integrations: extends transport (evidence: `contrib/transport/mcp/server.go`)
- OAuth2 middleware → Middleware: implements middleware (evidence: `contrib/middleware/oauth2/server.go`)
- Service developer → Contrib integrations: adopts integrations (evidence: `README.md`)
- Service developer → Configuration: configures services (evidence: `README.md`)
- Service developer → Encoding codecs: chooses formats (evidence: `README.md`)
