Practical Paths

Examples

The example paths Plumego can stand behind today, from the canonical runnable service to guided boundary-reading examples.

Architecture Docs

Start from one runnable service.

Clone and run the reference service before opening guides or recipes. Every example in this page assumes you have already run this path.

cd plumego/reference/standard-service && go run .

terminal — then verify

$ curl localhost:8080/healthz # {"data":{"status":"ok"}} $ curl "localhost:8080/api/v1/greet?name=Alice" # {"data":{"message":"hello, Alice"}}

One canonical service, then five focused recipe tracks.

The examples path has one runnable baseline and five guided recipe tracks. Start from reference/standard-service to see the default service shape, then pick a recipe to answer one concrete question — request flow, module fit, maturity check, or repository shape — before branching further.

runnable

One canonical runnable example

reference/standard-service is the example Plumego expects users to run first and compare against when creating a new service.

guided

Guided examples explain the repository around it

Request flow, module boundaries, and release posture are examples of how to navigate the repository rather than extra mini-apps.

honest scope

The site only promotes examples the repo can actually support

This page is intentionally narrower than a framework showcase. It favors examples that reinforce the canonical path instead of distracting from it.

One canonical service, then guided recipes.

Plumego examples are intentionally layered. There is one canonical runnable service, and there are guided recipes that explain how to read the repository around it without pretending every problem needs a separate demo app.

canonical example

reference/standard-service

The primary example is the service you can clone, run, compare against your own repository, and keep returning to while adoption decisions are still forming.

bootstrap and server construction stay visible
internal/app owns application-local wiring
route registration stays readable before deeper handlers or package families

reference/standard-service/

reference/standard-service/ ├── main.go ← bootstrap & server startup ├── internal/ │ ├── app/ │ │ ├── app.go ← dependency wiring │ │ └── routes.go ← route registration │ └── config/ │ └── config.go ← typed env config └── go.mod

terminal

$ go run ./reference/standard-service # Server started at :8080

Open the reference app guide

guided recipes

Recipes answer one repository question at a time.

These are not parallel mini-products. They are reusable reading patterns for request flow, ownership, maturity signals, and repository shape.

Run the reference app before opening unrelated package families.
Use recipes to answer a specific question, not as parallel product demos.
Return to the docs path once you know which boundary or capability owns the change.

Runnable now

If you want one example to clone, run, and compare against your own service, use the reference app first.

canonical

reference/standard-service

The default app layout for bootstrap, route wiring, and transport-only handlers.

best starting point for new services
shows the default directory shape
maps directly to docs and validation guidance

Open the reference app guide

Recipe tracks for focused adoption questions.

Recipes are smaller than the canonical example and more specific than a docs overview. Each one answers a concrete question quickly, then returns you to the default path with better classification.

recipe 01

Request-flow recipe

Use this when you need to trace one HTTP request from route registration to write path without guessing where transport responsibility ends.

follow route registration before handlers
confirm middleware order on the public path
stop once transport ownership ends

internal/app/routes.go

r := router.New()

r.Use(middleware.RequestID())
r.Use(middleware.Logger(a.log))

r.Get("/api/items",  a.items.List)
r.Get("/api/orders", a.orders.List)

Trace one request

recipe 02

Module-fit recipe

Use this when the real question is whether your work belongs in stable roots, app-local wiring, or an extension module.

classify the change before opening packages
protect stable-root compatibility promises
push optional capability work outward

import path check

// stable root — stable-root candidate, evaluate first
import "github.com/spcent/plumego/router"
import "github.com/spcent/plumego/middleware"

// extension family — Experimental, evaluate first
import "github.com/spcent/plumego/x/tenant"
import "github.com/spcent/plumego/x/ai"

Classify the change

recipe 03

Reference-app recipe

Use this when you want to inspect the canonical service shape and compare your own bootstrap and route layout against it.

start from internal/app ownership
compare directory shape before adding abstractions
treat the reference app as the reusable baseline

internal/app/app.go

type App struct {
    log    log.Logger
    db     *sql.DB
    items  *items.Handler
    orders *orders.Handler
}

func New(cfg *config.Config, deps AppDeps) *App {
    return &App{ /* explicit wiring */ }
}

Read the reference app

recipe 04

Maturity-check recipe

Use this when adoption depends on compatibility signals rather than on whether a package simply exists in the repository.

read stability promises before expanding scope
separate module maturity from roadmap ambition
keep evidence ahead of assumptions

maturity boundary

// GA stable roots — v1 compatibility promise
core, router, contract, middleware
security, store, health, log, metrics

// Beta — API frozen between minor release refs
x/rest, x/gateway, x/websocket, x/observability
x/tenant, x/frontend, x/messaging

// Experimental — useful, but API may change
x/ai, x/data, x/fileapi, x/resilience

Check module maturity

recipe 05

Repository-shape recipe

Use this when a change spans docs, generated facts, and implementation work and you need to know which layer owns what.

use docs for learning paths
use specs and generated facts for source-of-truth signals
keep app-local code and extensions clearly separated

repo layer map

docs/    ← human-readable learning paths
specs/   ← machine-readable rules & ownership
tasks/   ← executable work cards
x/       ← capability extension families

// app-local: only in your service repo
internal/app/app.go
internal/app/routes.go

Open architecture

Guided examples

These examples are not separate runnable apps. They are release-grade walkthroughs that teach the repository's intended reading path and ownership rules.

request path

Read one request from route to write path

Use the request-flow page when you need to trace where HTTP work begins and where transport responsibility should end.

Open request flow

module fit

Classify a change before opening packages

Use modules overview, stable roots, and x/* family pages to decide whether work belongs in the stable surface or an extension family.

Open modules overview

maturity

Check whether an area is stable enough to adopt

Use release posture and the public releases page to keep compatibility assumptions explicit.

Open release posture

Advanced reference apps

These reference apps demonstrate capability-specific service shapes. Each one extends reference/standard-service by adding one x/* family. Read the canonical reference app first, then open one of these when you are ready to evaluate a specific capability.

ai service

reference/with-ai

Multi-provider AI with streaming responses and tool routing. Adds x/ai to the stable HTTP kernel without altering the canonical route shape.

x/ai — Experimental

provider abstraction separate from HTTP transport
streaming responses through standard net/http handlers
stable roots stay compatible as AI API shapes evolve

Open x/ai primer Check maturity posture

multi-tenant saas

reference/with-tenant

Per-tenant routing, quota enforcement, and JWT-backed policy evaluation. Adds x/tenant outside the HTTP kernel so stable roots stay compatible when tenant logic evolves.

x/tenant — Beta

tenant identity from JWT or header, evaluated at the transport layer
per-tenant quota and policy separate from route wiring
stable roots carry the HTTP baseline; x/tenant carries the tenant layer

Open x/tenant primer Check maturity posture

All capability reference apps

Each app adds one x/* family to the standard-service baseline. Read the canonical reference app first, then open the one that matches your capability.

Reference app Capability Description Maturity

reference/with-ai x/ai Multi-provider AI with streaming responses and tool routing Experimental

reference/with-tenant x/tenant Per-tenant routing, quota enforcement, and JWT-backed policy Beta

reference/with-tenant-admin x/tenant Multi-tenant admin plane: lifecycle, quota admin, and usage recording Beta

reference/with-gateway x/gateway Edge proxy, load balancing, and route rewriting Beta

reference/with-rest x/rest CRUD resource controllers and REST conventions Beta

reference/with-websocket x/websocket WebSocket real-time transport Beta

reference/with-messaging x/messaging Async message publishing and subscription wiring Beta

reference/with-events x/messaging In-process pubsub, idempotent consumption, delayed retry, and webhook delivery Experimental

reference/with-rpc x/rpc gRPC server with HTTP gateway mount via x/rpc/server and x/rpc/gateway Experimental

reference/with-webhook x/messaging/webhook Webhook receiver with signature verification Experimental

reference/with-observability x/observability Prometheus metrics and OpenTelemetry distributed tracing Beta

reference/with-ops x/observability/ops Protected admin and operations surfaces Experimental

reference/with-frontend x/frontend Static and embedded SPA serving with cache headers, SPA fallback, and API co-location Beta

reference/production-service stable roots Production-hardened variant with full lifecycle, TLS, and tests Supported reference

Production-scale reference: reference/workerfleet

reference/workerfleet is a full-depth production reference app — distributed worker fleet management with domain models, MongoDB-backed stores, Kubernetes pod discovery, Prometheus metrics with custom collectors, alert engine with deduplication and threshold evaluation, and Feishu/webhook notifications. Use it to evaluate Plumego's capability depth beyond tutorial services.

Production reference — full-depth example

reference/workerfleet

domain-driven design: task, worker, pod, alert, and event models
MongoDB stores with index management and integration tests
Kubernetes watch-based pod sync and discovery
Prometheus metrics with custom collectors and Grafana dashboards
alert engine with deduplication, threshold rules, and notifiers (Feishu, webhook)

Read workerfleet README

Check module maturity before expanding.

Once the default path makes sense, verify which surfaces are stable enough to adopt before widening scope.

Project status & release evidence → Detailed stability tiers →

Examples

Start from the reference service, then use recipes

Start from one runnable service.

One canonical service, then five focused recipe tracks.

One canonical runnable example

Guided examples explain the repository around it

The site only promotes examples the repo can actually support

One canonical service, then guided recipes.

reference/standard-service

Recipes answer one repository question at a time.

Runnable now

reference/standard-service

Recipe tracks for focused adoption questions.

Request-flow recipe

Module-fit recipe

Reference-app recipe

Maturity-check recipe

Repository-shape recipe

Suggested reading order.

Run the canonical service first

Use recipes to answer one concrete question

Return to docs for durable guidance

Check module maturity before expanding scope

Guided examples

Read one request from route to write path

Classify a change before opening packages

Check whether an area is stable enough to adopt

Advanced reference apps

reference/with-ai

reference/with-tenant

All capability reference apps

Production-scale reference: reference/workerfleet

reference/workerfleet

Check module maturity before expanding.