# ankorstore/yokai: a modular Go framework for observable backend services

> Yokai wraps Echo, gRPC-go, Viper, OpenTelemetry and Uber Fx into a modular Go framework with a private HTTP server for infrastructure and debugging. It suits teams that want logging, tracing, metrics and health checks wired before they write business logic.

**ankorstore/yokai** — Simple, modular, and observable Go framework for backend applications.

- Repository: https://github.com/ankorstore/yokai
- Website: https://ankorstore.github.io/yokai
- Stars: 842 · Forks: 32
- Language: Go
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/ankorstore-yokai

## The boilerplate problem Yokai targets in Go backends

The README states the motivation directly: building production-grade Go applications means writing a lot of code that has nothing to do with the application's logic, such as dependency wiring, configuration management and observability instrumentation. Yokai's answer is to preload those concerns as core modules and let extensions add the rest. The stated goals are simple, modular and observable, and the repository is organised to match: each concern lives in its own top-level directory, with a plain module and a matching fx-prefixed integration module. You can see the pattern in entries like log/ and fxlog/, trace/ and fxtrace/, metrics/ and fxmetrics/, worker/ and fxworker/, orm/ and fxorm/, sql/ and fxsql/. The audience is Go teams building backend services that will run on Kubernetes, where health endpoints, structured logs and trace propagation are usually mandatory rather than optional. It is not a web framework in the Rails sense. It is an assembly layer over libraries you probably already use.

## Core modules, extension modules and the dependency injection graph

The architecture section of the README describes two layers. Core modules preload logging, tracing, metrics and health check instrumentation, and expose a private HTTP server for infrastructure and debugging needs. Extension modules enrich the application with public HTTP servers, gRPC servers, workers, ORM support and more, and the project also points to a separate contrib repository for additional modules. Everything is made available through the dependency injection system, which the README identifies as Uber Fx. That choice shapes the whole framework: modules are Fx providers, and your application logic resolves its dependencies from the same graph. Configuration is handled by Viper, HTTP servers by Echo, gRPC servers by gRPC-go, and observability instrumentation by OpenTelemetry. The data flow is therefore conventional for this style of Go service: configuration is read and bound, providers are registered, the Fx graph is built, and the core and extension modules start their servers, workers or clients. The private HTTP server is the piece worth noting, because it separates infrastructure endpoints from your public API surface by design rather than by convention.

## Installing Yokai and starting from a template

The README does not give a go get command for the framework itself. Instead, the getting started section points to ready-to-use application templates for gRPC, HTTP, MCP and worker applications, hosted on the documentation site. The repository also links a showroom with demo applications for each of those four shapes, described as ready to run. The practical first step is therefore to pick the template that matches the service you are building and follow its page, rather than adding a single module to an existing project. The Go version badge in the README states Go 1.20 or later, so confirm your toolchain before you begin.

A minimal Go module declaration for a new service looks like this:

```go
go 1.20
```

The same section of the README documents no CLI, no generator command and no configuration file format, so there is nothing further to copy from it verbatim. For the actual scaffolding steps, the HTTP application and gRPC application pages under getting started are the source, and the showroom's http-demo and grpc-demo directories are the runnable references. If you want to see the framework in action before writing anything, start the corresponding demo from the showroom and inspect how its modules are registered.

## The private HTTP server and why it is a design decision, not a detail

Separating a private infrastructure server from the public one is the most opinionated thing in the architecture diagram. Health checks, metrics scraping and debugging endpoints do not belong on the same listener as user traffic, and Yokai builds that separation in from the start. The trade-off is operational: you now have two ports to expose, two sets of network policies to write in Kubernetes, and a clear rule about which endpoints may be reachable from outside the cluster. Teams that already run a sidecar or a separate admin port will recognise the pattern. Teams that expect a single server to serve everything will have to adjust their deployment manifests. The README does not document the default ports, the exact endpoint paths or how to disable the private server, so those details have to come from the module documentation rather than from the repository root.

## Where Yokai is the wrong tool

The framework's value comes from the Fx graph, and that is also its main constraint. If your service is a small binary with two handlers and no background workers, the module-and-provider structure adds indirection without buying much; a plain net/http server with a logging library would be shorter and easier to read. If you are retrofitting observability into an existing service that already has its own wiring, adopting Yokai means either migrating that wiring into Fx providers or running two systems side by side, and the README offers no incremental adoption path. The same applies to configuration: Viper is the configuration mechanism, and a project with an established configuration library would be fighting the framework rather than using it. Finally, the README does not document rollback or upgrade procedures for the modules, and the release process relies on conventional commits through release-please, which tells you how releases are cut but not how a consumer should move between them. Treat the module versions as something you pin deliberately.

## Yokai compared with assembling the same libraries yourself

The honest alternative is not a different framework. It is doing the assembly yourself: Echo for HTTP, gRPC-go for gRPC, Viper for configuration, OpenTelemetry for instrumentation and Fx for dependency injection, wired in your own main package. The difference in approach is ownership. With Yokai, the wiring, the module boundaries and the private server layout are decided for you, and updates to those decisions arrive as module releases such as httpclient/v1.7.0 or worker/v1.4.0. With your own assembly, you decide the layout and you absorb every upstream change in each library separately. Yokai's bet is that the assembly is similar enough across backend services that standardising it is worth the loss of control. That bet is reasonable for a team running many similar Go services, and less reasonable for a single service with unusual requirements. A second, smaller alternative is to use the underlying libraries directly for one concern only, for example adding OpenTelemetry by hand while keeping your existing HTTP stack.

## Maintenance, licensing and the cost of staying current

The repository is not archived, and the last push was on 2026-07-16. The most recent releases listed are httpclient/v1.7.0 and fxhttpclient/v1.6.0, both dated 2026-07-16, and worker/v1.4.0 from 2026-06-19. Releases are per module rather than for the framework as a whole, which is consistent with the modular design but means your dependency list will contain several Yokai modules at different versions. Upgrading is therefore a per-module decision, and the project uses release-please with conventional commits to determine versions and generate release notes, so the notes are the place to check what changed. The licence is MIT, which is permissive and places few obligations on how you distribute or modify the code; this is a description of the licence identifier in the repository, not legal advice, and your organisation's own review still applies. The practical maintenance cost is the Fx and OpenTelemetry surface: as those upstream projects evolve, the fx-prefixed modules are where the adaptation lands, and that is what you are paying for by depending on Yokai rather than on the libraries directly.

## Conclusion

Adopt Yokai if you are starting a Go backend and want dependency injection, OpenTelemetry instrumentation and a private infrastructure HTTP server in place from the first commit, and if you accept that configuration flows through Viper and the DI graph through Uber Fx. Do not adopt it if you need a framework that hides its dependencies, or if you are adding observability to an existing service that already has its own wiring; the extension modules assume Fx. Before committing, read the HTTP, gRPC, MCP and worker application pages under the getting started section of the documentation, and check the release notes for the specific module versions you plan to pin.

## FAQ

### What is ankorstore/yokai?

It is a Go framework for backend applications, described in its README as simple, modular and observable. It preloads logging, tracing, metrics and health check instrumentation through core modules, and exposes a private HTTP server for infrastructure and debugging needs.

### Which Go version does ankorstore/yokai require?

The README's Go version badge states Go 1.20 or later.

### How do I start a new ankorstore/yokai application?

The getting started section of the README points to ready-to-use application templates for gRPC, HTTP, MCP and worker applications, and the showroom repository provides a runnable demo for each of those four shapes.

### Which libraries does ankorstore/yokai build on?

The README lists Echo for HTTP servers, gRPC-go for gRPC servers, Viper for configuration management, OpenTelemetry for observability instrumentation and Uber Fx for the dependency injection system.

### What licence does ankorstore/yokai use?

The repository is MIT licensed, as stated by the licence badge and the LICENSE file at the root. That is a permissive licence; it is not legal advice and your own review still applies.

## Sources

- [ankorstore/yokai on GitHub](https://github.com/ankorstore/yokai)
- [License: MIT](https://github.com/ankorstore/yokai/blob/main/LICENSE)
- [Project website](https://ankorstore.github.io/yokai)
- [README](https://github.com/ankorstore/yokai/blob/main/README.md)
- [Releases](https://github.com/ankorstore/yokai/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ankorstore-yokai