Examples#

Every subsystem ships a runnable example under cmd/, following the repository's conventions: compile-checked by CI, with a README that says what it demonstrates, how to run it, and what to look for.

go run ./cmd/<name>

The Fleet example in full#

The most complete example — three services, a cross-compile script, and a Compose file — is the reference for what a good example README looks like:

powershell -File cmd/fleet-example/build.ps1     # or: pwsh -File ...
docker compose -f cmd/fleet-example/docker-compose.yml up --build
curl http://localhost:3000/api/orders/123

Every service exposes /healthz and deliberately excludes it from tracing — see Fleet Tracing for why that matters for your own health-check and introspection routes. Open http://localhost:3000/dashboard (admin/admin) and select Fleet View to watch a request propagate through the gateway, auth, and orders services live. To see deterministic root-cause and blast-radius highlighting in action:

curl -X POST http://localhost:3002/chaos/fail
curl http://localhost:3000/api/orders/123
curl -X POST http://localhost:3002/chaos/recover

The gateway also serves an in-process MCP control endpoint on :2100 in app-runtime mode, scoped to runtime — a live demonstration of the scoping model described in MCP for AI Agents:

curl -H "Authorization: Bearer fleet-demo-mcp-token" http://127.0.0.1:2100/mcp/features

A minimal end-to-end app#

Putting several subsystems together — router, middleware, dashboard, events — in one file:

package main

import (
	"runtime"

	"github.com/nelthaarion/breeze/v2"
	"github.com/nelthaarion/breeze/v2/dashboard"
	"github.com/nelthaarion/breeze/v2/events"
	middleware "github.com/nelthaarion/breeze/v2/middlewares"
)

type UserRegistered struct {
	ID    string
	Email string
}

func main() {
	router := breeze.NewRouter()
	router.Use(middleware.RecoveryMiddleware())
	router.Use(middleware.LoggingMiddleware())
	router.Use(middleware.DefaultSecurityMiddleware())

	pool := breeze.NewEventLoopWorkerPool(runtime.NumCPU())
	app := breeze.New(router, pool)

	coll := dashboard.Install(app, router, dashboard.DefaultConfig())
	router.Use(coll.Middleware())

	events.On(UserRegistered{}, func(ctx *events.Context, e UserRegistered) error {
		coll.PushLog("app", "welcome email queued for "+e.Email, "main.go")
		return nil
	})

	router.HandleBlocking(breeze.POST, "/users", func(ctx *breeze.Context) error {
		var in struct {
			Email string `json:"email" validate:"required,email"`
		}
		if err := ctx.Bind(&in); err != nil {
			return nil // 422 problem+json already written
		}
		id := "usr_" + randomID()
		events.EmitAsync(UserRegistered{ID: id, Email: in.Email})
		ctx.Status(201)
		return ctx.JSON(map[string]string{"id": id})
	})

	app.Run(3000, true)
}

http://localhost:3000/dashboard shows the request live, the ORM-free "log" entry the event listener pushed, and the running memory/goroutine charts — with nothing more than the two lines that installed it.

Where to go from here#

• Getting Started — install, quick start, graceful shutdown
• CLI & Scaffolding — generate a full project instead of writing one by hand
• Repository Conventions — the rules these examples themselves follow