Skip to main content
Kratos is a microservice framework designed around clean architecture principles, providing a structured approach to building scalable Go applications. The framework follows a layered architecture that separates concerns and promotes maintainability.

​
Core Architecture

Kratos uses a component-based architecture where each part of the system has a clear responsibility:

Application Layer

The App struct manages the lifecycle of all components, coordinating startup, shutdown, and signal handling.

Transport Layer

Pluggable transport servers (HTTP, gRPC) that handle network communication independently.

Registry Layer

Service registration and discovery for microservice coordination.

Middleware Layer

Cross-cutting concerns like logging, tracing, and authentication.

​
Key Components

​
Transport Abstraction

Kratos defines a clean transport.Server interface that all transport implementations must satisfy:
transport/transport.go
type Server interface {
    Start(context.Context) error
    Stop(context.Context) error
}
This abstraction allows you to run multiple transport servers (HTTP, gRPC, etc.) within the same application without tight coupling.
The Endpointer interface allows transport servers to expose their endpoints for service registration.

​
Service Registry

The registry package provides interfaces for service registration and discovery:
registry/registry.go
type Registrar interface {
    // Register the registration.
    Register(ctx context.Context, service *ServiceInstance) error
    // Deregister the registration.
    Deregister(ctx context.Context, service *ServiceInstance) error
}

type Discovery interface {
    // GetService return the service instances in memory according to the service name.
    GetService(ctx context.Context, serviceName string) ([]*ServiceInstance, error)
    // Watch creates a watcher according to the service name.
    Watch(ctx context.Context, serviceName string) (Watcher, error)
}
A ServiceInstance contains all metadata needed for service discovery:
registry/registry.go
type ServiceInstance struct {
    ID        string            `json:"id"`
    Name      string            `json:"name"`
    Version   string            `json:"version"`
    Metadata  map[string]string `json:"metadata"`
    Endpoints []string          `json:"endpoints"`
}

​
Design Principles

​
Separation of Concerns

Each layer in Kratos has a specific responsibility:
  • Transport layer handles network protocols
  • Business layer contains domain logic
  • Data layer manages persistence
  • Service layer orchestrates use cases

​
Interface-Driven Design

Kratos heavily uses Go interfaces to define contracts: 
type Server interface {
    Start(context.Context) error
    Stop(context.Context) error
}
This approach enables:
  • Easy mocking for tests
  • Swappable implementations
  • Clear API boundaries

​
Context Propagation

Kratos uses Go’s context.Context throughout the framework for:
  • Request-scoped values (app info, transport metadata)
  • Cancellation signals
  • Timeout management
app.go:91
sctx := NewContext(a.ctx, a)
The NewContext function creates a context carrying application information:
app.go:204-206
func NewContext(ctx context.Context, s AppInfo) context.Context {
    return context.WithValue(ctx, appKey{}, s)
}

​
Lifecycle Management

The framework provides hooks at various lifecycle stages:
1

Before Start

Execute initialization logic before servers start
2

Start

Launch all transport servers concurrently
3

After Start

Perform post-startup tasks (register with service discovery)
4

Before Stop

Cleanup before shutdown begins
5

Stop

Gracefully stop all servers
6

After Stop

Final cleanup after all servers have stopped

​
Extensibility

Kratos is designed to be extended:
  • Custom transports: Implement the transport.Server interface
  • Middleware: Add cross-cutting concerns via middleware chains
  • Registry adapters: Implement Registrar and Discovery for different service registries
  • Custom options: Use the functional options pattern for configuration
The framework comes with built-in support for HTTP and gRPC transports, but you can add support for any protocol by implementing the transport.Server interface.

​
Next Steps

Application Lifecycle

Learn how the App struct manages component lifecycles

Dependency Injection

Understand how to wire components together

Build docs developers (and LLMs) love

Get started for freeTalk to us