examples

The examples package holds several microservices that demonstrate how the Microbus framework is used. Each example doc opens with what the microservice demonstrates, includes URLs to exercise it in a browser, and walks the code in service.go handler-by-handler. The generated intermediate.go is shown alongside, since that is where endpoints, configs, tickers, metrics, and event hooks are actually wired.

  • HelloWorld — the smallest possible microservice; one web endpoint, no state.
  • Hello — the showcase grab-bag: configs, tickers, embedded resources, localization, multicast discovery, service-to-service calls.
  • Calculator — functional endpoints, custom struct types, observable metrics.
  • Messaging — load-balanced unicast, multicast, direct addressing, and the per-service distributed cache.
  • Event source and sink — how events reverse the dependency between two services (synchronous veto + asynchronous notification).
  • Browser — calls the HTTP egress core microservice, with a mock-friendly test pattern.
  • Login — authentication and authorization via JWT actor claims and an ingress middleware redirect.
  • Yellow Pages — a SQL CRUD microservice generated from the sequel skills.
  • Chatbox — the LLM tool-calling on-ramp: a mock provider + an interactive demo wired into llm.core.
  • Weather — the canonical “how to build an agent” example: an agent modeled as a workflow that chains two tools (geocode, then forecast) to answer natural-language questions.
  • Credit Flow — agentic workflows with fan-out/fan-in, subgraphs, conditional transitions, and goto loops.
  • Bank Support — the authentication + structured-output agent: actor-scoped LLM tools that read only the signed-in customer’s own data, returning a typed verdict.
  • Flight Booking — the human-in-the-loop agent: a durable flow that parks on a real Interrupt/Resume decision, with graph composition and a nested seat-selection subgraph.
  • Embedder — Python integration via pyvenv: a real sentence-transformers model loaded in an in-process Python venv with deferred subscriptions. Not wired into main by default; add explicitly.
  • Petstore — the canonical worked output of the OpenAPI-import skill: three endpoints generated from the public Swagger Petstore document covering typed JSON, path arguments, and raw web upload shapes. Not wired into main by default since it calls a live remote API; add explicitly to exercise.

In case you missed it, the quick start guide explains how to set up your system to run the examples.

Topology

When the examples app starts, every example runs alongside the core services it needs, connected over the bus. The diagram below is the actual topology that the main app composes (source: main/topology.mmd). Pink nodes are core microservices, teal nodes are example microservices, orange edges indicate security-sensitive paths (token issuance and validation), and clouds / cylinders are external dependencies (HTTP, SQL, Python).

%%{init: {'themeVariables': {'lineColor': '#32a7c1', 'edgeLabelBackground': '#2d2d2d', 'textColor': '#f4f2ef'}}}%%
graph LR
    classDef core fill:#ed2e92,color:#f4f2ef,stroke-width:0px
    classDef svc fill:#32a7c1,color:#f4f2ef,stroke-width:0px
    classDef danger fill:#f15922,color:#f4f2ef,stroke-width:0px
    classDef ext fill:#e5f4f3,color:#434343,stroke:#32a7c1

    configurator.core[Configurator<br>configurator.core]
    http.egress.core[HTTPEgress<br>http.egress.core] --- http.egress.core.cloud@{shape: cloud, label: "various"}
    foreman.core[Foreman<br>foreman.core] --->|danger| access.token.core[accesstoken<br>access.token.core]
    foreman.core --- foreman.core.db[(SQL)]
    http.ingress.core[HTTPIngress<br>http.ingress.core] --->|danger| access.token.core
    http.ingress.core --->|danger| bearer.token.core[bearertoken<br>bearer.token.core]
    llm.core[LLM<br>llm.core]
    chatgpt.llm.core[ChatGPTLLM<br>chatgpt.llm.core] ---> http.egress.core
    chatgpt.llm.core --- chatgpt.llm.core.cloud@{shape: cloud, label: "api.openai.com"}
    claude.llm.core[ClaudeLLM<br>claude.llm.core] ---> http.egress.core
    claude.llm.core --- claude.llm.core.cloud@{shape: cloud, label: "api.anthropic.com"}
    gemini.llm.core[GeminiLLM<br>gemini.llm.core] ---> http.egress.core
    gemini.llm.core --- gemini.llm.core.cloud@{shape: cloud, label: "generativelanguage.googleapis.com"}
    lite.llm.core[LiteLLM<br>lite.llm.core] ---> http.egress.core
    lite.llm.core --- lite.llm.core.cloud@{shape: cloud, label: "localhost"}
    mcp.core[MCPPortal<br>mcp.core] ---> openapi.core[OpenAPIPortal<br>openapi.core]
    metrics.core[Metrics<br>metrics.core]
    banksupport.example[BankSupport<br>banksupport.example] --->|danger| bearer.token.core
    banksupport.example ---> foreman.core
    browser.example[Browser<br>browser.example] ---> http.egress.core
    browser.example --- browser.example.cloud@{shape: cloud, label: "various"}
    calculator.example[Calculator<br>calculator.example]
    chatbox.example[Chatbox<br>chatbox.example] ---> llm.core
    creditflow.example[CreditFlow<br>creditflow.example] ---> foreman.core
    embedder.example[embedder<br>embedder.example] --- embedder.example.py[[Py]]
    eventsource.example[EventSource<br>eventsource.example] -..-> eventsink.example[EventSink<br>eventsink.example]
    flightbooking.example[FlightBooking<br>flightbooking.example] ---> foreman.core
    hello.example[Hello<br>hello.example] ---> calculator.example
    helloworld.example[HelloWorld<br>helloworld.example]
    login.example[Login<br>login.example] --->|danger| bearer.token.core
    messaging.example[Messaging<br>messaging.example]
    weather.example[Weather<br>weather.example] ---> llm.core
    yellowpages.example[Person<br>yellowpages.example] --- yellowpages.example.db[(SQL)]
    docextractionflow.verify[docextractionflow<br>docextractionflow.verify]
    perelementpipelineflow.verify[perelementpipelineflow<br>perelementpipelineflow.verify]

    class banksupport.example,browser.example,calculator.example,chatbox.example,creditflow.example,embedder.example,eventsink.example,eventsource.example,flightbooking.example,hello.example,helloworld.example,login.example,messaging.example,weather.example,yellowpages.example,docextractionflow.verify,perelementpipelineflow.verify svc
    class configurator.core,http.egress.core,foreman.core,http.ingress.core,llm.core,chatgpt.llm.core,claude.llm.core,gemini.llm.core,lite.llm.core,mcp.core,metrics.core,openapi.core core
    class access.token.core,bearer.token.core danger
    class http.egress.core.cloud,foreman.core.db,chatgpt.llm.core.cloud,claude.llm.core.cloud,gemini.llm.core.cloud,lite.llm.core.cloud,browser.example.cloud,embedder.example.py,yellowpages.example.db ext

A few things to notice in this topology:

  • No example service talks directly to a public API. Every outbound HTTPS hop goes through http.egress.core, which gives every external call the same tracing, retries, mocking, and time budget treatment. The four LLM providers (claudellm, chatgptllm, geminillm, litellm) all route through it on their way to the respective vendor cloud.
  • Token issuance and validation are the only “danger” paths. Login → bearer token; Bank Support → bearer token (it mints its own customer sessions); HTTP ingress → bearer + access token; Foreman → access token. Concentrating the security-sensitive code in named core services makes the trust boundary explicit.
  • eventsource → eventsink is dotted — the source publishes events without naming the sink. The arrow only shows up in the topology because we know which sink the demo app registered; the source itself has no compile-time reference to it. See the events example.
  • hello → calculator is the only example-to-example call, demonstrating the service-to-service client pattern.
Backward env banksupport Forward