Architecture

July 12, 2026 · View on GitHub

This document explains how RonyKIT works, how the components fit together, and how the repository is organized.

Two Layers

RonyKIT provides two levels of abstraction:

Layer	Package	Description
High-level	`rony`	Batteries-included framework. Type-safe handlers, built-in docs, state management. Start here.
Low-level	`kit`	Core building blocks. Use when you need custom gateways, protocols, or deeper control.

rony is built on top of kit. You can always drop down to kit APIs from within rony handlers using ctx.KitCtx().

Request Flow

Client
  │
  ▼
Gateway (fasthttp / silverhttp / fastws)
  │
  ▼
EdgeServer
  │
  ▼
Service lookup
  │
  ▼
Contract match (route selector)
  │
  ▼
Middleware chain
  │
  ▼
Handler
  │
  ▼
Response

A Gateway receives inbound traffic (HTTP, WebSocket, etc.).
The EdgeServer routes the request to the matching Service.
Within the service, the Contract is matched by its route selector.
The Middleware chain runs (service-level, then contract-level).
The Handler processes the request and returns a response.

Key Abstractions

EdgeServer

The main orchestrator. Binds gateways, clusters, and services together. In the rony layer, rony.Server wraps an EdgeServer with opinionated defaults.

Gateway

Handles inbound traffic. RonyKIT ships with several gateway implementations:

Gateway	Package	Description
fasthttp	`std/gateways/fasthttp`	High-performance HTTP gateway using valyala/fasthttp
silverhttp	`std/gateways/silverhttp`	HTTP gateway using silverlining
fastws	`std/gateways/fastws`	WebSocket gateway using gnet + gobwas/ws
mcp	`std/gateways/mcp`	Model Context Protocol gateway

When using rony.NewServer(), the fasthttp gateway is configured automatically.

Cluster

Optional. Enables multi-instance coordination for shared state across EdgeServer instances.

Cluster	Package	Description
rediscluster	`std/clusters/rediscluster`	Redis-backed cluster
p2pcluster	`std/clusters/p2pcluster`	Peer-to-peer cluster using libp2p

Service

A logical grouping of contracts. One EdgeServer can host multiple services. Services are registered with rony.Setup().

A single API operation. Defines the input/output types, route selectors, and handler. In the rony layer, contracts are created implicitly with rony.WithUnary(), rony.WithStream(), or rony.WithRelay() (passthrough HTTP/WebSocket proxy).

Context

Request-scoped state with four storage layers:

Layer	Lifecycle	Access
Context	Per request	Available in all handlers
Connection	Per connection	Persists across requests on the same connection (WebSocket)
Local	Per server instance	Shared between all contracts and services
Cluster	Cross-instance	Shared across EdgeServer instances (requires a Cluster bundle)

Repository Layout

ronykit/
├── rony/              High-level framework (start here)
│   ├── server.go      Server creation and lifecycle
│   ├── setup.go       Service registration with contracts
│   ├── ctx.go         Type-safe handler contexts
│   ├── selector.go    Route helpers (GET, POST, etc.)
│   └── errs/          Structured error handling
│
├── kit/               Low-level core
│   ├── edge.go        EdgeServer implementation
│   ├── ctx.go         Raw request context
│   └── desc/          Service/Contract descriptors
│
├── ronyup/            Scaffolding CLI + MCP server
│   ├── cmd/           CLI commands (setup, text, mcp, template)
│   └── internal/      Skeleton templates, MCP tools
│
├── std/
│   ├── gateways/      Gateway implementations
│   │   ├── fasthttp/
│   │   ├── silverhttp/
│   │   ├── fastws/
│   │   └── mcp/
│   └── clusters/      Cluster implementations
│       ├── rediscluster/
│       └── p2pcluster/
│
├── stub/              Client stub generation (Go, TypeScript)
├── flow/              Workflow helpers (Temporal integration)
├── testenv/           Testing environment utilities
│
├── x/                 Extended utilities
│   ├── di/            Dependency injection (uber/fx helpers)
│   ├── telemetry/     Observability (logging, tracing, metrics)
│   ├── apidoc/        OpenAPI doc generation
│   ├── cache/         Caching utilities
│   ├── datasource/    Database and Redis connection helpers
│   ├── i18n/          Internationalization
│   ├── ratelimit/     Rate limiting
│   ├── settings/      Configuration management (Viper-backed)
│   ├── batch/         Batch processing
│   ├── rkit/          Common helpers
│   ├── testkit/       Testing utilities
│   └── p/             Additional primitives
│
└── example/           Runnable examples
    ├── ex-01-rpc/
    ├── ex-02-rest/
    ├── ex-04-stubgen/
    ├── ex-05-counter/
    └── ...

Encoding

RonyKIT supports multiple encoding formats:

Format	Description
JSON	Default. Uses struct `json` tags
Protobuf	Protocol Buffers encoding
MessagePack	Binary encoding
Multipart	`multipart/form-data` for file uploads
Custom	Implement your own codec

Routing

Two routing strategies are available:

REST selectors — HTTP method + path pattern (e.g., GET /users/{id})
RPC selectors — Predicate-based routing over WebSocket (e.g., RPC("getUser"))

A single handler can serve both REST and RPC routes, which is how RonyKIT achieves "define once, serve everywhere."

Extended Utilities (`x/`)

The x/ directory contains optional packages that integrate with the RonyKIT ecosystem. These are recommended when using the ronyup scaffolding:

Package	Purpose
`x/di`	Dependency injection helpers for uber/fx
`x/settings`	Configuration management with Viper
`x/telemetry/logkit`	Structured logging
`x/telemetry/tracekit`	Distributed tracing (OpenTelemetry)
`x/telemetry/meterkit`	Metrics collection
`x/apidoc`	OpenAPI document generation
`x/cache`	Caching utilities
`x/datasource`	Database and Redis connection management
`x/i18n`	Internationalization support
`x/ratelimit`	Rate limiting
`x/batch`	Batch processing
`x/rkit`	Common helper functions
`x/testkit`	Testing utilities

Next Steps

Getting Started — build your first server
Cookbook — production patterns and examples
ronyup Guide — scaffolding and MCP server
Advanced: Kit — low-level toolkit for custom gateways